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.
55 lines
2.0 KiB
Markdown
55 lines
2.0 KiB
Markdown
# 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) 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 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-42` works
|
|
- `bd 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`
|