#+TITLE: bd-issue-tracking Skill Creation and Upstream Comparison
#+DATE: 2025-12-03
#+KEYWORDS: bd-issue-tracking, beads, skill, upstream, webfetch, temporal-layering
#+COMMITS: 3
#+COMPRESSION_STATUS: uncompressed

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

** 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)