skills/docs/worklogs/2025-12-03-bd-issue-tracking-skill-creation.org

bd-issue-tracking Skill Creation and Upstream Comparison

• Session Summary
  • Date: 2025-12-03 (Wednesday evening)
  • Focus Area: Creating bd-issue-tracking skill from upstream beads repo, then discovering and fixing content gaps
• Accomplishments
• Key Decisions
  • Decision 1: Adopt temporal layering (both TodoWrite and bd)
  • Decision 2: Create adapted version vs fetch upstream directly
  • Decision 3: Replace condensed files with full upstream
• Problems & Solutions
• Technical Details
  • Code Changes
  • Commands Used
  • Line Count Comparison (Before/After)
  • Architecture Notes
• Process and Workflow
  • What Worked Well
  • What Was Challenging
• Learning and Insights
  • Technical Insights
  • Process Insights
  • Architectural Insights
• Context for Future Work
  • Open Questions
  • Next Steps
  • Related Work
• Raw Notes
• Session Metrics

Session Summary

Date: 2025-12-03 (Wednesday evening)

Focus Area: Creating bd-issue-tracking skill from upstream beads repo, then discovering and fixing content gaps

Accomplishments

• Created beads issue skills-7sh to track skill setup
• Entered plan mode to design implementation approach
• Discussed temporal layering philosophy (TodoWrite + bd) vs bd-only
• Created initial bd-issue-tracking skill with YAML frontmatter
• Created 9 files: SKILL.md, README.md, and 7 reference files
• Added "bd-issue-tracking" to flake.nix availableSkills
• Committed and pushed initial implementation
• User challenged "That's it" characterization of differences
• Created bd issues to systematically compare each file with upstream
• Used curl to fetch actual raw upstream files
• Discovered WebFetch summarized content instead of returning raw markdown
• Found 70-80% content missing from most files
• Replaced 7/8 files with full upstream versions (+2770 lines)
• Kept STATIC_DATA.md (ours was 59 lines vs upstream 54)
• Closed all comparison issues with documented deltas

Key Decisions

Decision 1: Adopt temporal layering (both TodoWrite and bd)

• Context: User asked whether to use bd-only or allow both tools

• Options considered:

  1. bd-only - One system of record, but fights Claude Code's built-in TodoWrite nudges
  2. Both tools (temporal layering) - TodoWrite for single-session, bd for multi-session
• Rationale: User said "I want to go with both tools, but I imagine this is going to evolve so let's not make it a requirement"
• Impact: Kept upstream philosophy intact, less friction with Claude Code defaults

Decision 2: Create adapted version vs fetch upstream directly

• Context: Our skills use YAML frontmatter, upstream might not

• Options considered:

  1. Fetch upstream directly
  2. Create adapted version
• Rationale: Initially chose adapted version due to presumed frontmatter needs
• Impact: This was later superseded - upstream already had correct frontmatter

Decision 3: Replace condensed files with full upstream

• Context: User pushed back on "That's it" summary of differences
• Rationale: Comparison showed 70-80% content missing from most files
• Impact: +2770 lines added, comprehensive documentation now included

Problems & Solutions

Problem	Solution	Learning
WebFetch returned summarized content, not raw markdown	Used curl to fetch raw files from GitHub raw.githubusercontent.com	WebFetch is for extracting information, not copying files verbatim
Initial characterization of differences was inaccurate	Created systematic bd issues to compare each file line-by-line	Don't make definitive claims without evidence; use "could be" instead of "that's the issue"
bd sync failed with worktree error	Used separate git add/commit commands	bd sync has edge cases with worktrees; manual git commands work as fallback
Beads hook says "no TodoWrite" but skill teaches temporal layering	Left as-is per user preference to "see what happens"	Philosophy can evolve; don't over-constrain upfront

Technical Details

Code Changes

• Total files modified: 11 (initial) + 8 (replacement)

• Key files created:

  • skills/bd-issue-tracking/SKILL.md - Main skill instructions (644 lines)
  • skills/bd-issue-tracking/README.md - Human documentation
  • skills/bd-issue-tracking/references/CLI_REFERENCE.md - Command reference (559 lines)
  • skills/bd-issue-tracking/references/BOUNDARIES.md - bd vs TodoWrite decisions (469 lines)
  • skills/bd-issue-tracking/references/DEPENDENCIES.md - Dependency types guide (747 lines)
  • skills/bd-issue-tracking/references/WORKFLOWS.md - Step-by-step procedures (548 lines)
  • skills/bd-issue-tracking/references/ISSUE_CREATION.md - Issue quality guidelines (139 lines)
  • skills/bd-issue-tracking/references/RESUMABILITY.md - Cross-session patterns (207 lines)
  • skills/bd-issue-tracking/references/STATIC_DATA.md - Reference db usage (59 lines, kept ours)
• flake.nix modified to add "bd-issue-tracking" to availableSkills

Commands Used

# Fetching raw upstream content (correct approach)
curl -sL https://raw.githubusercontent.com/steveyegge/beads/main/examples/claude-code-skill/SKILL.md > /tmp/upstream-SKILL.md

# Comparing line counts
wc -l /tmp/upstream-SKILL.md /home/dan/proj/skills/skills/bd-issue-tracking/SKILL.md

# Creating bd issues with discovered-from dependency
bd create "Replace SKILL.md with upstream version" -t task -p 1 --deps discovered-from:skills-ebh

# Viewing ready work
bd ready

Line Count Comparison (Before/After)

File	Before	After	Delta
SKILL.md	122	644	+522
CLI_REFERENCE.md	158	559	+401
DEPENDENCIES.md	141	747	+606
WORKFLOWS.md	178	548	+370
BOUNDARIES.md	82	469	+387
ISSUE_CREATION.md	104	139	+35
RESUMABILITY.md	171	207	+36
STATIC_DATA.md	59	54	-5 (kept ours)

Architecture Notes

• Skills are deployed via Home Manager module in modules/ai-skills.nix
• Skills source lives in home/dan/proj/skills/skills
• flake.nix lists availableSkills that get packaged
• User's Home Manager config specifies claudeCodeSkills list for deployment
• Skills require YAML frontmatter with name and description fields

Process and Workflow

What Worked Well

• Plan mode for designing implementation approach
• Using bd issues to track comparison work systematically
• User pushing back on inaccurate characterization
• Parallel fetching of multiple upstream files with curl
• Closing issues with documented reasons (line count deltas)

What Was Challenging

• WebFetch not returning raw content (returned summaries instead)
• bd sync failing with worktree error
• Initial overconfidence in characterizing differences
• Finding where skills are actually managed (proj/skills vs dotfiles)

Learning and Insights

Technical Insights

• WebFetch tool summarizes content rather than returning verbatim
• For raw file content from GitHub, use: curl -sL https://raw.githubusercontent.com/...
• Upstream beads skill already has correct YAML frontmatter
• Skills directory structure: SKILL.md, README.md, references/ subdirectory

Process Insights

• "That's it" should never be said without comprehensive comparison
• Creating bd issues for each file comparison creates accountability
• User skepticism is valuable - don't dismiss pushback
• wc -l is a quick way to spot content gaps

Architectural Insights

• Temporal layering (TodoWrite + bd) is the upstream philosophy
• TodoWrite: ephemeral single-session tactical work
• bd: persistent multi-session strategic work
• Both tools complement each other at different timescales

Context for Future Work

Open Questions

• Should the beads startup hook be updated to remove "no TodoWrite" language?
• How will temporal layering philosophy evolve with actual usage?
• Should we set up automatic upstream tracking/sync for this skill?

Next Steps

• User needs to add "bd-issue-tracking" to claudeCodeSkills in Home Manager config
• Run home-manager switch to deploy
• Restart Claude Code to load new skill
• Consider updating beads hook to align with temporal layering

Related Work

• docs/worklogs/2025-11-30-per-repo-skill-deployment-design.org (skill deployment patterns)
• Upstream source: https://github.com/steveyegge/beads/tree/main/examples/claude-code-skill
• Beads issue tracking: skills-ebh (parent), skills-5v8 through skills-7s0 (file comparisons)

Raw Notes

• The upstream skill is comprehensive - 644 lines in SKILL.md alone

• Key sections we were missing:

  • Self-test questions for bd vs TodoWrite decisions
  • Notes quality self-check (Future-me test, Stranger test)
  • Token budget checkpointing (70%, 85%, 90% triggers)
  • Database selection guidance
  • Field Usage Reference table
  • Detailed issue lifecycle workflow
  • Common patterns with full examples
  • Troubleshooting section
  • Statistics and Monitoring
  • Advanced Features (bulk ops, dep visualization)
• User correctly identified that "30-50% shorter" was inaccurate - we were 70-80% shorter
• STATIC_DATA.md was the only file where ours was slightly longer (59 vs 54 lines)

Session Metrics

• Commits made: 3
• Files touched: 25
• Lines added: +4625
• Lines removed: -90
• Issues created: 9 (1 parent, 8 file comparisons)
• Issues closed: 10 (including parent and original setup issue)