chore: replace STATIC_DATA.md with upstream, add session worklog
Code review found upstream STATIC_DATA.md was better quality despite being 5 lines shorter. Added comprehensive session worklog. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
dan
parent
8902a4f4a6
commit
148f219887
183
docs/worklogs/2025-12-03-bd-issue-tracking-skill-creation.org
Normal file
183
docs/worklogs/2025-12-03-bd-issue-tracking-skill-creation.org
Normal file
|
|
@ -0,0 +1,183 @@
|
|||
#+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)
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Using bd for Static Reference Data
|
||||
|
||||
bd is primarily for work tracking, but can serve as a queryable database for reference data.
|
||||
bd is primarily designed for work tracking, but can also serve as a queryable database for static reference data with some adaptations.
|
||||
|
||||
## Work Tracking (Primary Use Case)
|
||||
|
||||
|
|
@ -8,52 +8,47 @@ Standard bd workflow:
|
|||
- Issues flow through states (open → in_progress → closed)
|
||||
- Priorities and dependencies matter
|
||||
- Status tracking is essential
|
||||
- IDs are sufficient for referencing
|
||||
|
||||
## Reference Databases (Alternative Use)
|
||||
## Reference Databases / Glossaries (Alternative Use)
|
||||
|
||||
When using bd for static data (terminology, glossaries):
|
||||
When using bd for static data (terminology, glossaries, reference information):
|
||||
|
||||
**Characteristics:**
|
||||
- Entities are mostly static (typically always open)
|
||||
- No workflow or state transitions
|
||||
- No real workflow or state transitions
|
||||
- Names/titles more important than IDs
|
||||
- Minimal or no dependencies
|
||||
|
||||
**Recommended approach:**
|
||||
- Use separate database (not mixed with work tracking)
|
||||
- Consider dual format: bd + markdown for name-based lookup
|
||||
- Use separate database (not mixed with work tracking) to avoid confusion
|
||||
- Consider dual format: maintain markdown version alongside database for name-based lookup
|
||||
- Example: A terminology database could use both `terms.db` (queryable via bd) and `GLOSSARY.md` (browsable by name)
|
||||
|
||||
**Key difference**: Work items have lifecycle; reference entities are stable knowledge.
|
||||
|
||||
## When to Use This Pattern
|
||||
|
||||
**Good fit:**
|
||||
- Technical glossaries
|
||||
- Reference documentation with relationships
|
||||
- Knowledge bases with dependencies
|
||||
- Structured data needing queryability
|
||||
- Technical glossaries or terminology databases
|
||||
- Reference documentation that needs dependency tracking
|
||||
- Knowledge bases with relationships between entries
|
||||
- Structured data that benefits from queryability
|
||||
|
||||
**Poor fit:**
|
||||
- Data that changes frequently
|
||||
- Data that changes frequently (use work tracking pattern)
|
||||
- Simple lists (markdown is simpler)
|
||||
- Complex queries (use proper database)
|
||||
- Data that needs complex queries (use proper database)
|
||||
|
||||
## Limitations
|
||||
|
||||
**bd show requires IDs:**
|
||||
**bd show requires IDs, not names:**
|
||||
- `bd show term-42` works
|
||||
- `bd show "API endpoint"` doesn't work
|
||||
- Workaround: `bd list | grep -i "term"` to find ID
|
||||
- Workaround: `bd list | grep -i "api endpoint"` to find ID first
|
||||
- This is why dual format (bd + markdown) is recommended for reference data
|
||||
|
||||
**No full-text search:**
|
||||
- bd searches by ID, title, status, labels
|
||||
- For content search: `grep -i "term" .beads/issues.jsonl`
|
||||
|
||||
## Summary
|
||||
|
||||
Use bd for static reference data when:
|
||||
- You need relationships/dependencies between entries
|
||||
- Queryability matters
|
||||
- Dual format (bd + markdown) acceptable
|
||||
|
||||
Stick with markdown for:
|
||||
- Simple lists
|
||||
- No relationships needed
|
||||
- Name-based lookup is primary use case
|
||||
**No search by content:**
|
||||
- bd searches by ID, title filters, status, labels
|
||||
- For full-text search across descriptions/notes, use grep on the JSONL file
|
||||
- Example: `grep -i "authentication" .beads/issues.jsonl`
|
||||
|
|
|
|||
Loading…
Reference in a new issue