bdaf82026a
* Update skill installation path and document new features Installation path changes: - Update from ~/.claude/skills/bd to bd-issue-tracking - Matches internal skill name for consistency with other skills Documentation additions: - Add 3 new reference files to documentation list - Document compaction survival patterns (critical for Claude Code) - Mention self-check checklists and quality guidelines This prepares the README for upcoming skill content improvements. * Add new reference files for enhanced skill guidance New reference documentation: 1. ISSUE_CREATION.md - When to ask vs create issues - Decision criteria for knowledge work vs technical work - Issue quality guidelines and best practices - Design vs acceptance criteria guidance - Self-check questions for well-scoped issues 2. RESUMABILITY.md - Making issues resumable across sessions - Patterns for complex technical work with APIs - Working code examples and API response samples - When enhanced documentation matters vs simple descriptions - Critical for multi-session work and crash recovery 3. STATIC_DATA.md - Using bd for reference databases - Alternative use case beyond work tracking - Glossaries and terminology management - Dual format patterns (database + markdown) - When bd helps vs when simpler formats suffice These additions emerged from real-world usage patterns and enable Claude to make better decisions about issue structure and resumability. * Enhance existing skill files with real-world usage patterns SKILL.md major enhancements (~194 net lines added): - Add "Test Yourself" decision framework with self-check questions - Document compaction survival patterns (critical for Claude Code) - Add Notes Quality Self-Check (future-me test, stranger test) - Session Start Checklist with copy-paste templates - Field Usage Reference table (when to use each bd field) - Progress Checkpointing triggers and patterns - Issue Creation Checklist with quality self-checks - Enhanced session handoff protocols WORKFLOWS.md enhancements (~114 lines added): - Session handoff workflow with detailed checklists - Collaborative handoff between Claude and user - Compaction survival workflow - Notes format guidelines (current state, not cumulative) - Session start checklist expansion BOUNDARIES.md updates (~49 lines removed): - Streamlined content (moved detailed workflows to WORKFLOWS.md) - Retained core decision criteria - Improved examples and integration patterns CLI_REFERENCE.md minor updates: - Additional command examples - Clarified flag usage These improvements emerged from extensive real-world usage, particularly around crash recovery, compaction events, and multi-session workflows. The additions make the skill more practical for autonomous agent use.
2.0 KiB
2.0 KiB
Using bd for Static 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)
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 / Glossaries (Alternative Use)
When using bd for static data (terminology, glossaries, reference information):
Characteristics:
- Entities are mostly static (typically always open)
- 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) 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) andGLOSSARY.md(browsable by name)
Key difference: Work items have lifecycle; reference entities are stable knowledge.
When to Use This Pattern
Good fit:
- 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 (use work tracking pattern)
- Simple lists (markdown is simpler)
- Data that needs complex queries (use proper database)
Limitations
bd show requires IDs, not names:
bd show term-42worksbd show "API endpoint"doesn't work- Workaround:
bd list | grep -i "api endpoint"to find ID first - This is why dual format (bd + markdown) is recommended for reference data
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