diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 5ab5124..3f56cf8 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,14 +1,23 @@ +{"id":"skills-20s","title":"Compare BOUNDARIES.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:53.585115099-08:00","updated_at":"2025-12-03T20:19:28.442646801-08:00","closed_at":"2025-12-03T20:19:28.442646801-08:00","dependencies":[{"issue_id":"skills-20s","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:53.586442134-08:00","created_by":"daemon"}]} {"id":"skills-25l","title":"Create orch skill for multi-model consensus","description":"Build a skill that exposes orch CLI capabilities to agents for querying multiple AI models","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-30T15:43:49.209528963-08:00","updated_at":"2025-11-30T15:47:36.608887453-08:00","closed_at":"2025-11-30T15:47:36.608887453-08:00"} {"id":"skills-2xo","title":"Add README.md for web-search skill","description":"web-search skill has SKILL.md and scripts but no README.md. AGENTS.md says README.md is for humans, contains installation instructions, usage examples, prerequisites.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.26066025-08:00","updated_at":"2025-11-30T12:00:25.561281052-08:00","dependencies":[{"issue_id":"skills-2xo","depends_on_id":"skills-vb5","type":"blocks","created_at":"2025-11-30T12:01:30.240439018-08:00","created_by":"daemon"}]} {"id":"skills-39g","title":"RFC: .skills manifest pattern for per-repo skill deployment","description":"Document the .skills file pattern where projects declare skills in a manifest, .envrc reads it, and agents can query/edit it.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-30T12:37:50.106992381-08:00","updated_at":"2025-11-30T12:43:04.155161727-08:00","closed_at":"2025-11-30T12:43:04.155161727-08:00"} {"id":"skills-3o7","title":"Fix ai-skills.nix missing sha256 hash","description":"modules/ai-skills.nix:16 has empty sha256 placeholder for opencode-skills npm package. Either get actual hash or remove/comment out the incomplete fetchFromNpm approach.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-30T11:58:24.404929863-08:00","updated_at":"2025-11-30T12:12:39.372107348-08:00","closed_at":"2025-11-30T12:12:39.372107348-08:00"} {"id":"skills-4yn","title":"Decide on screenshot-latest skill deployment","description":"DEPLOYED.md shows screenshot-latest as 'Not yet deployed - Pending decision'. Low risk skill that finds existing files. Need to decide whether to deploy or archive.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.099790809-08:00","updated_at":"2025-11-30T11:58:33.099790809-08:00"} +{"id":"skills-5v8","title":"Replace SKILL.md with upstream version","description":"Upstream has 644 lines vs our 122. Missing: self-test questions, notes quality checks, token checkpointing, database selection, field usage table, lifecycle workflow, common patterns, troubleshooting","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-03T20:15:53.025829293-08:00","updated_at":"2025-12-03T20:16:20.470185004-08:00","closed_at":"2025-12-03T20:16:20.470185004-08:00","dependencies":[{"issue_id":"skills-5v8","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:53.027601712-08:00","created_by":"daemon"}]} +{"id":"skills-7s0","title":"Compare STATIC_DATA.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:55.193704589-08:00","updated_at":"2025-12-03T20:19:29.659256809-08:00","closed_at":"2025-12-03T20:19:29.659256809-08:00","dependencies":[{"issue_id":"skills-7s0","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:55.195160705-08:00","created_by":"daemon"}]} {"id":"skills-7sh","title":"Set up bd-issue-tracking Claude Code skill from beads repo","description":"Install the beads Claude Code skill from https://github.com/steveyegge/beads/tree/main/examples/claude-code-skill\n\nThis skill teaches Claude how to effectively use beads for issue tracking across multi-session coding workflows. It provides strategic guidance on when/how to use beads, not just command syntax.\n\nFiles to install to ~/.claude/skills/bd-issue-tracking/:\n- SKILL.md - Core workflow patterns and decision criteria\n- BOUNDARIES.md - When to use beads vs markdown alternatives\n- CLI_REFERENCE.md - Complete command documentation\n- DEPENDENCIES.md - Relationship types and patterns\n- WORKFLOWS.md - Step-by-step procedures\n- ISSUE_CREATION.md - Quality guidelines\n- RESUMABILITY.md - Making work resumable across sessions\n- STATIC_DATA.md - Using beads as reference databases\n\nCan symlink or copy the files. Restart Claude Code after install.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T17:53:43.254007992-08:00","updated_at":"2025-12-03T20:04:53.416579381-08:00","closed_at":"2025-12-03T20:04:53.416579381-08:00"} +{"id":"skills-8d4","title":"Compare CLI_REFERENCE.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:53.268324087-08:00","updated_at":"2025-12-03T20:17:26.552616779-08:00","closed_at":"2025-12-03T20:17:26.552616779-08:00","dependencies":[{"issue_id":"skills-8d4","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:53.27265681-08:00","created_by":"daemon"}]} {"id":"skills-a23","title":"Update main README to list all 9 skills","description":"Main README.md 'Skills Included' section only lists worklog and update-spec-kit. Repo actually has 9 skills: template, worklog, update-spec-kit, screenshot-latest, niri-window-capture, tufte-press, update-opencode, web-research, web-search.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.042397754-08:00","updated_at":"2025-11-30T12:00:18.916270858-08:00","dependencies":[{"issue_id":"skills-a23","depends_on_id":"skills-4yn","type":"blocks","created_at":"2025-11-30T12:01:30.306742184-08:00","created_by":"daemon"}]} {"id":"skills-cnc","title":"Add direnv helper for per-repo skill deployment","description":"Create sourceable helper script and documentation for the standard per-repo skill deployment pattern using direnv + nix build.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-30T12:19:20.71056749-08:00","updated_at":"2025-11-30T12:37:47.22638278-08:00","closed_at":"2025-11-30T12:37:47.22638278-08:00"} {"id":"skills-czz","title":"Research OpenCode agents for skill integration","description":"DEPLOYMENT.md:218 has TODO to research OpenCode agents. Need to understand how Build/Plan/custom agents work and whether skills need agent-specific handling.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:24.855701141-08:00","updated_at":"2025-11-30T11:58:24.855701141-08:00"} +{"id":"skills-ebh","title":"Compare bd-issue-tracking skill files with upstream","description":"Fetch upstream beads skill files and compare with our condensed versions to identify differences","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:14:07.886535859-08:00","updated_at":"2025-12-03T20:19:37.579815337-08:00","closed_at":"2025-12-03T20:19:37.579815337-08:00"} +{"id":"skills-fo3","title":"Compare WORKFLOWS.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.283175561-08:00","updated_at":"2025-12-03T20:19:28.897037199-08:00","closed_at":"2025-12-03T20:19:28.897037199-08:00","dependencies":[{"issue_id":"skills-fo3","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.286009672-08:00","created_by":"daemon"}]} {"id":"skills-kmj","title":"Orch skill: document or handle orch not in PATH","description":"Skill docs show 'orch consensus' but orch requires 'uv run' from ~/proj/orch. Either update skill to invoke correctly or document installation requirement.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-01T17:29:48.844997238-08:00","updated_at":"2025-12-01T18:28:11.374048504-08:00","closed_at":"2025-12-01T18:28:11.374048504-08:00"} +{"id":"skills-lie","title":"Compare DEPENDENCIES.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:53.925914243-08:00","updated_at":"2025-12-03T20:19:28.665641809-08:00","closed_at":"2025-12-03T20:19:28.665641809-08:00","dependencies":[{"issue_id":"skills-lie","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:53.9275694-08:00","created_by":"daemon"}]} +{"id":"skills-lvg","title":"Compare ISSUE_CREATION.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.609282051-08:00","updated_at":"2025-12-03T20:19:29.134966356-08:00","closed_at":"2025-12-03T20:19:29.134966356-08:00","dependencies":[{"issue_id":"skills-lvg","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.610717055-08:00","created_by":"daemon"}]} {"id":"skills-m21","title":"Apply niri-window-capture code review recommendations","description":"CODE-REVIEW-niri-window-capture.md identifies action items: add dependency checks to scripts, improve error handling for niri failures, add screenshot directory validation, implement rate limiting. See High/Medium priority sections.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:24.648846875-08:00","updated_at":"2025-11-30T11:58:24.648846875-08:00"} {"id":"skills-pu4","title":"Clean up stale beads.left.jsonl merge artifact","description":"bd doctor flagged multiple JSONL files. beads.left.jsonl is empty merge artifact that should be removed: git rm .beads/beads.left.jsonl","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.292221449-08:00","updated_at":"2025-11-30T12:37:49.916795223-08:00","closed_at":"2025-11-30T12:37:49.916795223-08:00"} {"id":"skills-qeh","title":"Add README.md for web-research skill","description":"web-research skill has SKILL.md and scripts but no README.md. AGENTS.md says README.md is for humans, contains installation instructions, usage examples, prerequisites.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.475647113-08:00","updated_at":"2025-11-30T12:00:30.309340468-08:00","dependencies":[{"issue_id":"skills-qeh","depends_on_id":"skills-vb5","type":"blocks","created_at":"2025-11-30T12:01:30.278784381-08:00","created_by":"daemon"}]} +{"id":"skills-uz4","title":"Compare RESUMABILITY.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.897754095-08:00","updated_at":"2025-12-03T20:19:29.384645842-08:00","closed_at":"2025-12-03T20:19:29.384645842-08:00","dependencies":[{"issue_id":"skills-uz4","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.899671178-08:00","created_by":"daemon"}]} {"id":"skills-vb5","title":"Resolve web search design questions","description":"web_search_brainstorm.md has unanswered design questions: single smart skill vs explicit flags, specific sources priority, raw links vs summaries. Need user input to finalize web-search/web-research direction.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.482270742-08:00","updated_at":"2025-11-30T11:58:33.482270742-08:00"} diff --git a/skills/bd-issue-tracking/SKILL.md b/skills/bd-issue-tracking/SKILL.md index 7e645f0..ab7cde9 100644 --- a/skills/bd-issue-tracking/SKILL.md +++ b/skills/bd-issue-tracking/SKILL.md @@ -1,122 +1,644 @@ --- name: bd-issue-tracking -description: Guide for effective beads (bd) issue tracking across multi-session coding workflows. Use when working on complex features, bug investigations, or any work spanning multiple sessions. Teaches temporal layering with TodoWrite for single-session tasks and bd for persistent strategic work. +description: Track complex, multi-session work with dependency graphs using bd (beads) issue tracker. Use when work spans multiple sessions, has complex dependencies, or requires persistent context across compaction cycles. For simple single-session linear tasks, TodoWrite remains appropriate. --- -# bd Issue Tracking Skill +# bd Issue Tracking -Guide for using bd (beads) for persistent issue tracking across coding sessions. +## Overview -## When to Use +bd is a graph-based issue tracker for persistent memory across sessions. Use for multi-session work with complex dependencies; use TodoWrite for simple single-session tasks. -This skill activates when: -- Starting work on a project with `.beads/` directory -- Planning multi-session features or investigations -- Managing complex work with dependencies -- Deciding between bd and TodoWrite for task tracking +## When to Use bd vs TodoWrite -## Core Philosophy: Temporal Layering +### Use bd when: +- **Multi-session work** - Tasks spanning multiple compaction cycles or days +- **Complex dependencies** - Work with blockers, prerequisites, or hierarchical structure +- **Knowledge work** - Strategic documents, research, or tasks with fuzzy boundaries +- **Side quests** - Exploratory work that might pause the main task +- **Project memory** - Need to resume work after weeks away with full context -Use both tools for different time horizons: +### Use TodoWrite when: +- **Single-session tasks** - Work that completes within current session +- **Linear execution** - Straightforward step-by-step tasks with no branching +- **Immediate context** - All information already in conversation +- **Simple tracking** - Just need a checklist to show progress -| Tool | Use Case | Persistence | -|------|----------|-------------| -| **TodoWrite** | Single-session micro-tasks | Ephemeral (conversation only) | -| **bd** | Multi-session strategic work | Persistent (survives compaction) | +**Key insight**: If resuming work after 2 weeks would be difficult without bd, use bd. If the work can be picked up from a markdown skim, TodoWrite is sufficient. -**The 2-week test**: Would bd help you resume this work after 2 weeks away? If yes, use bd. +### Test Yourself: bd or TodoWrite? + +Ask these questions to decide: + +**Choose bd if:** +- ❓ "Will I need this context in 2 weeks?" → Yes = bd +- ❓ "Could conversation history get compacted?" → Yes = bd +- ❓ "Does this have blockers/dependencies?" → Yes = bd +- ❓ "Is this fuzzy/exploratory work?" → Yes = bd + +**Choose TodoWrite if:** +- ❓ "Will this be done in this session?" → Yes = TodoWrite +- ❓ "Is this just a task list for me right now?" → Yes = TodoWrite +- ❓ "Is this linear with no branching?" → Yes = TodoWrite + +**When in doubt**: Use bd. Better to have persistent memory you don't need than to lose context you needed. + +**For detailed decision criteria and examples, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md) + +## Surviving Compaction Events + +**Critical**: Compaction events delete conversation history but preserve beads. After compaction, bd state is your only persistent memory. + +**What survives compaction:** +- All bead data (issues, notes, dependencies, status) +- Complete work history and context + +**What doesn't survive:** +- Conversation history +- TodoWrite lists +- Recent discussion context + +**Writing notes for post-compaction recovery:** + +Write notes as if explaining to a future agent with zero conversation context: + +**Pattern:** +```markdown +notes field format: +- COMPLETED: Specific deliverables ("implemented JWT refresh endpoint + rate limiting") +- IN PROGRESS: Current state + next immediate step ("testing password reset flow, need user input on email template") +- BLOCKERS: What's preventing progress +- KEY DECISIONS: Important context or user guidance +``` + +**After compaction:** `bd show ` reconstructs full context from notes field. + +### Notes Quality Self-Check + +Before checkpointing (especially pre-compaction), verify your notes pass these tests: + +❓ **Future-me test**: "Could I resume this work in 2 weeks with zero conversation history?" +- [ ] What was completed? (Specific deliverables, not "made progress") +- [ ] What's in progress? (Current state + immediate next step) +- [ ] What's blocked? (Specific blockers with context) +- [ ] What decisions were made? (Why, not just what) + +❓ **Stranger test**: "Could another developer understand this without asking me?" +- [ ] Technical choices explained (not just stated) +- [ ] Trade-offs documented (why this approach vs alternatives) +- [ ] User input captured (decisions that came from discussion) + +**Good note example:** +``` +COMPLETED: JWT auth with RS256 (1hr access, 7d refresh tokens) +KEY DECISION: RS256 over HS256 per security review - enables key rotation +IN PROGRESS: Password reset flow - email service working, need rate limiting +BLOCKERS: Waiting on user decision: reset token expiry (15min vs 1hr trade-off) +NEXT: Implement rate limiting (5 attempts/15min) once expiry decided +``` + +**Bad note example:** +``` +Working on auth. Made some progress. More to do. +``` + +**For complete compaction recovery workflow, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#compaction-survival) ## Session Start Protocol -When starting work where bd is available: +**bd is available when:** +- Project has a `.beads/` directory (project-local database), OR +- `~/.beads/` exists (global fallback database for any directory) -1. Run `bd ready --json` to see available work -2. Report status to user: "X items ready: [summary]" -3. If none ready, check `bd blocked --json` -4. Review in_progress issues with `bd show ` -5. Read notes field for context from previous sessions +**At session start, always check for bd availability and run ready check.** -## During Work +### Session Start Checklist -### Creating Issues +Copy this checklist when starting any session where bd is available: -**Create directly** (no user question needed): -- Clear bugs discovered during implementation -- Obvious follow-up work identified -- Technical debt with clear scope - -**Ask first** (get user input): -- Knowledge work with fuzzy boundaries -- Multiple valid approaches exist -- User's intent needs clarification - -### Status Maintenance - -- `open` → `in_progress` when starting work -- Update notes field with progress -- Add dependencies as blockers discovered -- Close with summary when complete - -### Discovery Pattern - -When finding new work during implementation: - -```bash -# Create and link in one command -bd create "Found issue" -t bug -p 1 --deps discovered-from: --json +``` +Session Start: +- [ ] Run bd ready --json to see available work +- [ ] Run bd list --status in_progress --json for active work +- [ ] If in_progress exists: bd show to read notes +- [ ] Report context to user: "X items ready: [summary]" +- [ ] If using global ~/.beads, mention this in report +- [ ] If nothing ready: bd blocked --json to check blockers ``` -## Session End Protocol +**Pattern**: Always check both `bd ready` AND `bd list --status in_progress`. Read notes field first to understand where previous session left off. -Before ending a session: +**Report format**: +- "I can see X items ready to work on: [summary]" +- "Issue Y is in_progress. Last session: [summary from notes]. Next: [from notes]. Should I continue with that?" -1. Update notes field with current state: - ``` - COMPLETED: What was finished - IN PROGRESS: Current state - NEXT: Concrete next step - KEY DECISION: Important choices made (with rationale) - ``` +This establishes immediate shared context about available and active work without requiring user prompting. -2. Run `bd sync` to ensure changes are committed +**For detailed collaborative handoff process, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-handoff) -## Compaction Survival +**Note**: bd auto-discovers the database: +- Uses `.beads/*.db` in current project if exists +- Falls back to `~/.beads/default.db` otherwise +- No configuration needed -After compaction events, conversation history is deleted but bd state persists. +### When No Work is Ready -**Recovery checklist:** -1. `bd list --status in_progress` - see active work -2. `bd show ` for each - read notes field -3. Reconstruct context from COMPLETED/IN PROGRESS/NEXT - -## Reference Documentation - -For detailed guidance, see the references/ subdirectory: - -- **BOUNDARIES.md** - Decision criteria: bd vs TodoWrite -- **CLI_REFERENCE.md** - Complete command documentation -- **DEPENDENCIES.md** - Dependency types and patterns -- **WORKFLOWS.md** - Step-by-step procedures with checklists -- **ISSUE_CREATION.md** - Quality guidelines for creating issues -- **RESUMABILITY.md** - Making work resumable across sessions -- **STATIC_DATA.md** - Using bd as reference database - -## Quick Command Reference +If `bd ready` returns empty but issues exist: ```bash -# Find work -bd ready --json # Unblocked issues -bd blocked --json # See what's stuck - -# Manage issues -bd create "Title" -t bug -p 1 --json -bd update --status in_progress --json -bd close --reason "Done" --json - -# Dependencies -bd dep add -bd dep tree - -# Session end -bd sync # Force sync to git +bd blocked --json ``` + +Report blockers and suggest next steps. + +--- + +## Progress Checkpointing + +Update bd notes at these checkpoints (don't wait for session end): + +**Critical triggers:** +- ⚠️ **Context running low** - User says "running out of context" / "approaching compaction" / "close to token limit" +- 📊 **Token budget > 70%** - Proactively checkpoint when approaching limits +- 🎯 **Major milestone reached** - Completed significant piece of work +- 🚧 **Hit a blocker** - Can't proceed, need to capture what was tried +- 🔄 **Task transition** - Switching issues or about to close this one +- ❓ **Before user input** - About to ask decision that might change direction + +**Proactive monitoring during session:** +- At 70% token usage: "We're at 70% token usage - good time to checkpoint bd notes?" +- At 85% token usage: "Approaching token limit (85%) - checkpointing current state to bd" +- At 90% token usage: Automatically checkpoint without asking + +**Current token usage**: Check `Token usage:` messages to monitor proactively. + +**Checkpoint checklist:** + +``` +Progress Checkpoint: +- [ ] Update notes with COMPLETED/IN_PROGRESS/NEXT format +- [ ] Document KEY DECISIONS or BLOCKERS since last update +- [ ] Mark current status (in_progress/blocked/closed) +- [ ] If discovered new work: create issues with discovered-from +- [ ] Verify notes are self-explanatory for post-compaction resume +``` + +**Most important**: When user says "running out of context" OR when you see >70% token usage - checkpoint immediately, even if mid-task. + +**Test yourself**: "If compaction happened right now, could future-me resume from these notes?" + +--- + +### Database Selection + +bd automatically selects the appropriate database: +- **Project-local** (`.beads/` in project): Used for project-specific work +- **Global fallback** (`~/.beads/`): Used when no project-local database exists + +**Use case for global database**: Cross-project tracking, personal task management, knowledge work that doesn't belong to a specific project. + +**When to use --db flag explicitly:** +- Accessing a specific database outside current directory +- Working with multiple databases (e.g., project database + reference database) +- Example: `bd --db /path/to/reference/terms.db list` + +**Database discovery rules:** +- bd looks for `.beads/*.db` in current working directory +- If not found, uses `~/.beads/default.db` +- Shell cwd can reset between commands - use absolute paths with --db when operating on non-local databases + +**For complete session start workflows, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-start) + +## Core Operations + +All bd commands support `--json` flag for structured output when needed for programmatic parsing. + +### Essential Operations + +**Check ready work:** +```bash +bd ready +bd ready --json # For structured output +bd ready --priority 0 # Filter by priority +bd ready --assignee alice # Filter by assignee +``` + +**Create new issue:** + +**IMPORTANT**: Always quote title and description arguments with double quotes, especially when containing spaces or special characters. + +```bash +bd create "Fix login bug" +bd create "Add OAuth" -p 0 -t feature +bd create "Write tests" -d "Unit tests for auth module" --assignee alice +bd create "Research caching" --design "Evaluate Redis vs Memcached" + +# Examples with special characters (requires quoting): +bd create "Fix: auth doesn't handle edge cases" -p 1 +bd create "Refactor auth module" -d "Split auth.go into separate files (handlers, middleware, utils)" +``` + +**Update issue status:** +```bash +bd update issue-123 --status in_progress +bd update issue-123 --priority 0 +bd update issue-123 --assignee bob +bd update issue-123 --design "Decided to use Redis for persistence support" +``` + +**Close completed work:** +```bash +bd close issue-123 +bd close issue-123 --reason "Implemented in PR #42" +bd close issue-1 issue-2 issue-3 --reason "Bulk close related work" +``` + +**Show issue details:** +```bash +bd show issue-123 +bd show issue-123 --json +``` + +**List issues:** +```bash +bd list +bd list --status open +bd list --priority 0 +bd list --type bug +bd list --assignee alice +``` + +**For complete CLI reference with all flags and examples, read:** [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md) + +## Field Usage Reference + +Quick guide for when and how to use each bd field: + +| Field | Purpose | When to Set | Update Frequency | +|-------|---------|-------------|------------------| +| **description** | Immutable problem statement | At creation | Never (fixed forever) | +| **design** | Initial approach, architecture, decisions | During planning | Rarely (only if approach changes) | +| **acceptance-criteria** | Concrete deliverables checklist (`- [ ]` syntax) | When design is clear | Mark `- [x]` as items complete | +| **notes** | Session handoff (COMPLETED/IN_PROGRESS/NEXT) | During work | At session end, major milestones | +| **status** | Workflow state (open→in_progress→closed) | As work progresses | When changing phases | +| **priority** | Urgency level (0=highest, 3=lowest) | At creation | Adjust if priorities shift | + +**Key pattern**: Notes field is your "read me first" at session start. See [WORKFLOWS.md](references/WORKFLOWS.md#session-handoff) for session handoff details. + +--- + +## Issue Lifecycle Workflow + +### 1. Discovery Phase (Proactive Issue Creation) + +**During exploration or implementation, proactively file issues for:** +- Bugs or problems discovered +- Potential improvements noticed +- Follow-up work identified +- Technical debt encountered +- Questions requiring research + +**Pattern:** +```bash +# When encountering new work during a task: +bd create "Found: auth doesn't handle profile permissions" +bd dep add current-task-id new-issue-id --type discovered-from + +# Continue with original task - issue persists for later +``` + +**Key benefit**: Capture context immediately instead of losing it when conversation ends. + +### 2. Execution Phase (Status Maintenance) + +**Mark issues in_progress when starting work:** +```bash +bd update issue-123 --status in_progress +``` + +**Update throughout work:** +```bash +# Add design notes as implementation progresses +bd update issue-123 --design "Using JWT with RS256 algorithm" + +# Update acceptance criteria if requirements clarify +bd update issue-123 --acceptance "- JWT validation works\n- Tests pass\n- Error handling returns 401" +``` + +**Close when complete:** +```bash +bd close issue-123 --reason "Implemented JWT validation with tests passing" +``` + +**Important**: Closed issues remain in database - they're not deleted, just marked complete for project history. + +### 3. Planning Phase (Dependency Graphs) + +For complex multi-step work, structure issues with dependencies before starting: + +**Create parent epic:** +```bash +bd create "Implement user authentication" -t epic -d "OAuth integration with JWT tokens" +``` + +**Create subtasks:** +```bash +bd create "Set up OAuth credentials" -t task +bd create "Implement authorization flow" -t task +bd create "Add token refresh" -t task +``` + +**Link with dependencies:** +```bash +# parent-child for epic structure +bd dep add auth-epic auth-setup --type parent-child +bd dep add auth-epic auth-flow --type parent-child + +# blocks for ordering +bd dep add auth-setup auth-flow +``` + +**For detailed dependency patterns and types, read:** [references/DEPENDENCIES.md](references/DEPENDENCIES.md) + +## Dependency Types Reference + +bd supports four dependency types: + +1. **blocks** - Hard blocker (issue A blocks issue B from starting) +2. **related** - Soft link (issues are related but not blocking) +3. **parent-child** - Hierarchical (epic/subtask relationship) +4. **discovered-from** - Provenance (issue B discovered while working on A) + +**For complete guide on when to use each type with examples and patterns, read:** [references/DEPENDENCIES.md](references/DEPENDENCIES.md) + +## Integration with TodoWrite + +**Both tools complement each other at different timescales:** + +### Temporal Layering Pattern + +**TodoWrite** (short-term working memory - this hour): +- Tactical execution: "Review Section 3", "Expand Q&A answers" +- Marked completed as you go +- Present/future tense ("Review", "Expand", "Create") +- Ephemeral: Disappears when session ends + +**Beads** (long-term episodic memory - this week/month): +- Strategic objectives: "Continue work on strategic planning document" +- Key decisions and outcomes in notes field +- Past tense in notes ("COMPLETED", "Discovered", "Blocked by") +- Persistent: Survives compaction and session boundaries + +### The Handoff Pattern + +1. **Session start**: Read bead → Create TodoWrite items for immediate actions +2. **During work**: Mark TodoWrite items completed as you go +3. **Reach milestone**: Update bead notes with outcomes + context +4. **Session end**: TodoWrite disappears, bead survives with enriched notes + +**After compaction**: TodoWrite is gone forever, but bead notes reconstruct what happened. + +### Example: TodoWrite tracks execution, Beads capture meaning + +**TodoWrite:** +``` +[completed] Implement login endpoint +[in_progress] Add password hashing with bcrypt +[pending] Create session middleware +``` + +**Corresponding bead notes:** +``` +bd update issue-123 --notes "COMPLETED: Login endpoint with bcrypt password +hashing (12 rounds). KEY DECISION: Using JWT tokens (not sessions) for stateless +auth - simplifies horizontal scaling. IN PROGRESS: Session middleware implementation. +NEXT: Need user input on token expiry time (1hr vs 24hr trade-off)." +``` + +**Don't duplicate**: TodoWrite tracks execution, Beads captures meaning and context. + +**For patterns on transitioning between tools mid-session, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md#integration-patterns) + +## Common Patterns + +### Pattern 1: Knowledge Work Session + +**Scenario**: User asks "Help me write a proposal for expanding the analytics platform" + +**What you see**: +```bash +$ bd ready +# Returns: bd-42 "Research analytics platform expansion proposal" (in_progress) + +$ bd show bd-42 +Notes: "COMPLETED: Reviewed current stack (Mixpanel, Amplitude) +IN PROGRESS: Drafting cost-benefit analysis section +NEXT: Need user input on budget constraints before finalizing recommendations" +``` + +**What you do**: +1. Read notes to understand current state +2. Create TodoWrite for immediate work: + ``` + - [ ] Draft cost-benefit analysis + - [ ] Ask user about budget constraints + - [ ] Finalize recommendations + ``` +3. Work on tasks, mark TodoWrite items completed +4. At milestone, update bd notes: + ```bash + bd update bd-42 --notes "COMPLETED: Cost-benefit analysis drafted. + KEY DECISION: User confirmed $50k budget cap - ruled out enterprise options. + IN PROGRESS: Finalizing recommendations (Posthog + custom ETL). + NEXT: Get user review of draft before closing issue." + ``` + +**Outcome**: TodoWrite disappears at session end, but bd notes preserve context for next session. + +### Pattern 2: Side Quest Handling + +During main task, discover a problem: +1. Create issue: `bd create "Found: inventory system needs refactoring"` +2. Link using discovered-from: `bd dep add main-task new-issue --type discovered-from` +3. Assess: blocker or can defer? +4. If blocker: `bd update main-task --status blocked`, work on new issue +5. If deferrable: note in issue, continue main task + +### Pattern 3: Multi-Session Project Resume + +Starting work after time away: +1. Run `bd ready` to see available work +2. Run `bd blocked` to understand what's stuck +3. Run `bd list --status closed --limit 10` to see recent completions +4. Run `bd show issue-id` on issue to work on +5. Update status and begin work + +**For complete workflow walkthroughs with checklists, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md) + +## Issue Creation + +**Quick guidelines:** +- Ask user first for knowledge work with fuzzy boundaries +- Create directly for clear bugs, technical debt, or discovered work +- Use clear titles, sufficient context in descriptions +- Design field: HOW to build (can change during implementation) +- Acceptance criteria: WHAT success looks like (should remain stable) + +### Issue Creation Checklist + +Copy when creating new issues: + +``` +Creating Issue: +- [ ] Title: Clear, specific, action-oriented +- [ ] Description: Problem statement (WHY this matters) - immutable +- [ ] Design: HOW to build (can change during work) +- [ ] Acceptance: WHAT success looks like (stays stable) +- [ ] Priority: 0=critical, 1=high, 2=normal, 3=low +- [ ] Type: bug/feature/task/epic/chore +``` + +**Self-check for acceptance criteria:** + +❓ "If I changed the implementation approach, would these criteria still apply?" +- → **Yes** = Good criteria (outcome-focused) +- → **No** = Move to design field (implementation-focused) + +**Example:** +- ✅ Acceptance: "User tokens persist across sessions and refresh automatically" +- ❌ Wrong: "Use JWT tokens with 1-hour expiry" (that's design, not acceptance) + +**For detailed guidance on when to ask vs create, issue quality, resumability patterns, and design vs acceptance criteria, read:** [references/ISSUE_CREATION.md](references/ISSUE_CREATION.md) + +## Alternative Use Cases + +bd is primarily for work tracking, but can also serve as queryable database for static reference data (glossaries, terminology) with adaptations. + +**For guidance on using bd for reference databases and static data, read:** [references/STATIC_DATA.md](references/STATIC_DATA.md) + +## Statistics and Monitoring + +**Check project health:** +```bash +bd stats +bd stats --json +``` + +Returns: total issues, open, in_progress, closed, blocked, ready, avg lead time + +**Find blocked work:** +```bash +bd blocked +bd blocked --json +``` + +Use stats to: +- Report progress to user +- Identify bottlenecks +- Understand project velocity + +## Advanced Features + +### Issue Types + +```bash +bd create "Title" -t task # Standard work item (default) +bd create "Title" -t bug # Defect or problem +bd create "Title" -t feature # New functionality +bd create "Title" -t epic # Large work with subtasks +bd create "Title" -t chore # Maintenance or cleanup +``` + +### Priority Levels + +```bash +bd create "Title" -p 0 # Highest priority (critical) +bd create "Title" -p 1 # High priority +bd create "Title" -p 2 # Normal priority (default) +bd create "Title" -p 3 # Low priority +``` + +### Bulk Operations + +```bash +# Close multiple issues at once +bd close issue-1 issue-2 issue-3 --reason "Completed in sprint 5" + +# Create multiple issues from markdown file +bd create --file issues.md +``` + +### Dependency Visualization + +```bash +# Show full dependency tree for an issue +bd dep tree issue-123 + +# Check for circular dependencies +bd dep cycles +``` + +### Built-in Help + +```bash +# Quick start guide (comprehensive built-in reference) +bd quickstart + +# Command-specific help +bd create --help +bd dep --help +``` + +## JSON Output + +All bd commands support `--json` flag for structured output: + +```bash +bd ready --json +bd show issue-123 --json +bd list --status open --json +bd stats --json +``` + +Use JSON output when you need to parse results programmatically or extract specific fields. + +## Troubleshooting + +**If bd command not found:** +- Check installation: `bd version` +- Verify PATH includes bd binary location + +**If issues seem lost:** +- Use `bd list` to see all issues +- Filter by status: `bd list --status closed` +- Closed issues remain in database permanently + +**If bd show can't find issue by name:** +- `bd show` requires issue IDs, not issue titles +- Workaround: `bd list | grep -i "search term"` to find ID first +- Then: `bd show issue-id` with the discovered ID +- For glossaries/reference databases where names matter more than IDs, consider using markdown format alongside the database + +**If dependencies seem wrong:** +- Use `bd show issue-id` to see full dependency tree +- Use `bd dep tree issue-id` for visualization +- Dependencies are directional: `bd dep add from-id to-id` means from-id blocks to-id +- See [references/DEPENDENCIES.md](references/DEPENDENCIES.md#common-mistakes) + +**If database seems out of sync:** +- bd auto-syncs JSONL after each operation (5s debounce) +- bd auto-imports JSONL when newer than DB (after git pull) +- Manual operations: `bd export`, `bd import` + +## Reference Files + +Detailed information organized by topic: + +| Reference | Read When | +|-----------|-----------| +| [references/BOUNDARIES.md](references/BOUNDARIES.md) | Need detailed decision criteria for bd vs TodoWrite, or integration patterns | +| [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md) | Need complete command reference, flag details, or examples | +| [references/WORKFLOWS.md](references/WORKFLOWS.md) | Need step-by-step workflows with checklists for common scenarios | +| [references/DEPENDENCIES.md](references/DEPENDENCIES.md) | Need deep understanding of dependency types or relationship patterns | +| [references/ISSUE_CREATION.md](references/ISSUE_CREATION.md) | Need guidance on when to ask vs create issues, issue quality, or design vs acceptance criteria | +| [references/STATIC_DATA.md](references/STATIC_DATA.md) | Want to use bd for reference databases, glossaries, or static data instead of work tracking | diff --git a/skills/bd-issue-tracking/references/BOUNDARIES.md b/skills/bd-issue-tracking/references/BOUNDARIES.md index b5c4284..c98f564 100644 --- a/skills/bd-issue-tracking/references/BOUNDARIES.md +++ b/skills/bd-issue-tracking/references/BOUNDARIES.md @@ -1,6 +1,24 @@ # Boundaries: When to Use bd vs TodoWrite -Decision criteria for choosing between bd issue tracking and TodoWrite. +This reference provides detailed decision criteria for choosing between bd issue tracking and TodoWrite for task management. + +## Contents + +- [The Core Question](#the-core-question) +- [Decision Matrix](#decision-matrix) + - [Use bd for](#use-bd-for): Multi-Session Work, Complex Dependencies, Knowledge Work, Side Quests, Project Memory + - [Use TodoWrite for](#use-todowrite-for): Single-Session Tasks, Linear Execution, Immediate Context, Simple Tracking +- [Detailed Comparison](#detailed-comparison) +- [Integration Patterns](#integration-patterns) + - Pattern 1: bd as Strategic, TodoWrite as Tactical + - Pattern 2: TodoWrite as Working Copy of bd + - Pattern 3: Transition Mid-Session +- [Real-World Examples](#real-world-examples) + - Strategic Document Development, Simple Feature Implementation, Bug Investigation, Refactoring with Dependencies +- [Common Mistakes](#common-mistakes) + - Using TodoWrite for multi-session work, using bd for simple tasks, not transitioning when complexity emerges, creating too many bd issues, never using bd +- [The Transition Point](#the-transition-point) +- [Summary Heuristics](#summary-heuristics) ## The Core Question @@ -9,74 +27,443 @@ Decision criteria for choosing between bd issue tracking and TodoWrite. - If bd would help you resume → **use bd** - If markdown skim would suffice → **TodoWrite is fine** +This heuristic captures the essential difference: bd provides structured context that persists across long gaps, while TodoWrite excels at immediate session tracking. + ## Decision Matrix ### Use bd for: -| Scenario | Why | -|----------|-----| -| **Multi-session work** | Issues capture context that survives compaction | -| **Complex dependencies** | Dependency graph shows blockers, `bd ready` surfaces work | -| **Knowledge work** | Design notes capture evolving understanding | -| **Side quests** | `discovered-from` preserves context for both tracks | -| **Project memory** | Git-backed database persists indefinitely | +#### Multi-Session Work +Work spanning multiple compaction cycles or days where context needs to persist. + +**Examples:** +- Strategic document development requiring research across multiple sessions +- Feature implementation split across several coding sessions +- Bug investigation requiring experimentation over time +- Architecture design evolving through multiple iterations + +**Why bd wins**: Issues capture context that survives compaction. Return weeks later and see full history, design decisions, and current status. + +#### Complex Dependencies +Work with blockers, prerequisites, or hierarchical structure. + +**Examples:** +- OAuth integration requiring database setup, endpoint creation, and frontend changes +- Research project with multiple parallel investigation threads +- Refactoring with dependencies between different code areas +- Migration requiring sequential steps in specific order + +**Why bd wins**: Dependency graph shows what's blocking what. `bd ready` automatically surfaces unblocked work. No manual tracking required. + +#### Knowledge Work +Tasks with fuzzy boundaries, exploration, or strategic thinking. + +**Examples:** +- Architecture decision requiring research into frameworks and trade-offs +- API design requiring research into multiple options +- Performance optimization requiring measurement and experimentation +- Documentation requiring understanding system architecture + +**Why bd wins**: `design` and `acceptance_criteria` fields capture evolving understanding. Issues can be refined as exploration reveals more information. + +#### Side Quests +Exploratory work that might pause the main task. + +**Examples:** +- During feature work, discover a better pattern worth exploring +- While debugging, notice related architectural issue +- During code review, identify potential improvement +- While writing tests, find edge case requiring research + +**Why bd wins**: Create issue with `discovered-from` dependency, pause main work safely. Context preserved for both tracks. Resume either one later. + +#### Project Memory +Need to resume work after significant time with full context. + +**Examples:** +- Open source contributions across months +- Part-time projects with irregular schedule +- Complex features split across sprints +- Research projects with long investigation periods + +**Why bd wins**: Git-backed database persists indefinitely. All context, decisions, and history available on resume. No relying on conversation scrollback or markdown files. + +--- ### Use TodoWrite for: -| Scenario | Why | -|----------|-----| -| **Single-session tasks** | Simple checklist for linear execution | -| **Linear execution** | Steps are predetermined and sequential | -| **Immediate context** | All information already in conversation | -| **Simple tracking** | Just need visible progress for user | +#### Single-Session Tasks +Work that completes within current conversation. + +**Examples:** +- Implementing a single function based on clear spec +- Fixing a bug with known root cause +- Adding unit tests for existing code +- Updating documentation for recent changes + +**Why TodoWrite wins**: Simple checklist is perfect for linear execution. No need for persistence or dependencies. Clear completion within session. + +#### Linear Execution +Straightforward step-by-step tasks with no branching. + +**Examples:** +- Database migration with clear sequence +- Deployment checklist +- Code style cleanup across files +- Dependency updates following upgrade guide + +**Why TodoWrite wins**: Steps are predetermined and sequential. No discovery, no blockers, no side quests. Just execute top to bottom. + +#### Immediate Context +All information already in conversation. + +**Examples:** +- User provides complete spec and asks for implementation +- Bug report with reproduction steps and fix approach +- Refactoring request with clear before/after vision +- Config changes based on user preferences + +**Why TodoWrite wins**: No external context to track. Everything needed is in current conversation. TodoWrite provides user visibility, nothing more needed. + +#### Simple Tracking +Just need a checklist to show progress to user. + +**Examples:** +- Breaking down implementation into visible steps +- Showing validation workflow progress +- Demonstrating systematic approach +- Providing reassurance work is proceeding + +**Why TodoWrite wins**: User wants to see thinking and progress. TodoWrite is visible in conversation. bd is invisible background structure. + +--- ## Detailed Comparison | Aspect | bd | TodoWrite | |--------|-----|-----------| -| **Persistence** | Git-backed, survives compaction | Session-only | -| **Dependencies** | Graph-based, automatic ready detection | Manual | -| **Visibility** | Background structure | Visible in conversation | +| **Persistence** | Git-backed, survives compaction | Session-only, lost after conversation | +| **Dependencies** | Graph-based, automatic ready detection | Manual, no automatic tracking | +| **Discoverability** | `bd ready` surfaces work | Scroll conversation for todos | +| **Complexity** | Handles nested epics, blockers | Flat list only | +| **Visibility** | Background structure, not in conversation | Visible to user in chat | +| **Setup** | Requires `.beads/` directory in project | Always available | | **Best for** | Complex, multi-session, explorative | Simple, single-session, linear | +| **Context capture** | Design notes, acceptance criteria, links | Just task description | +| **Evolution** | Issues can be updated, refined over time | Static once written | +| **Audit trail** | Full history of changes | Only visible in conversation | ## Integration Patterns -### Pattern 1: bd Strategic, TodoWrite Tactical +bd and TodoWrite can coexist effectively in a session. Use both strategically. +### Pattern 1: bd as Strategic, TodoWrite as Tactical + +**Setup:** - bd tracks high-level issues and dependencies - TodoWrite tracks current session's execution steps -### Pattern 2: TodoWrite as Working Copy +**Example:** +``` +bd issue: "Implement user authentication" (epic) + ├─ Child issue: "Create login endpoint" + ├─ Child issue: "Add JWT token validation" ← Currently working on this + └─ Child issue: "Implement logout" -1. Start with bd issue containing full context -2. Create TodoWrite from acceptance criteria -3. Update bd as TodoWrite items complete +TodoWrite (for JWT validation): +- [ ] Install JWT library +- [ ] Create token validation middleware +- [ ] Add tests for token expiry +- [ ] Update API documentation +``` + +**When to use:** +- Complex features with clear implementation steps +- User wants to see current progress but larger context exists +- Multi-session work currently in single-session execution phase + +### Pattern 2: TodoWrite as Working Copy of bd + +**Setup:** +- Start with bd issue containing full context +- Create TodoWrite checklist from bd issue's acceptance criteria +- Update bd as TodoWrite items complete + +**Example:** +``` +Session start: +- Check bd: "issue-auth-42: Add JWT token validation" is ready +- Extract acceptance criteria into TodoWrite +- Mark bd issue as in_progress +- Work through TodoWrite items +- Update bd design notes as you learn +- When TodoWrite completes, close bd issue +``` + +**When to use:** +- bd issue is ready but execution is straightforward +- User wants visible progress tracking +- Need structured approach to larger issue ### Pattern 3: Transition Mid-Session -**From TodoWrite to bd** when: +**From TodoWrite to bd:** + +Recognize mid-execution that work is more complex than anticipated. + +**Trigger signals:** - Discovering blockers or dependencies - Realizing work won't complete this session -- Finding side quests +- Finding side quests or related issues +- Needing to pause and resume later **How to transition:** +``` 1. Create bd issue with current TodoWrite content -2. Note: "Discovered this is multi-session work" +2. Note: "Discovered this is multi-session work during implementation" 3. Add dependencies as discovered -4. Update bd issue before session ends +4. Keep TodoWrite for current session +5. Update bd issue before session ends +6. Next session: resume from bd, create new TodoWrite if needed +``` + +**From bd to TodoWrite:** + +Rare, but happens when bd issue turns out simpler than expected. + +**Trigger signals:** +- All context already clear +- No dependencies discovered +- Can complete within session +- User wants execution visibility + +**How to transition:** +``` +1. Keep bd issue for historical record +2. Create TodoWrite from issue description +3. Execute via TodoWrite +4. Close bd issue when done +5. Note: "Completed in single session, simpler than expected" +``` + +## Real-World Examples + +### Example 1: Database Migration Planning + +**Scenario**: Planning migration from MySQL to PostgreSQL for production application. + +**Why bd**: +- Multi-session work across days/weeks +- Fuzzy boundaries - scope emerges through investigation +- Side quests - discover schema incompatibilities requiring refactoring +- Dependencies - can't migrate data until schema validated +- Project memory - need to resume after interruptions + +**bd structure**: +``` +db-epic: "Migrate production database to PostgreSQL" + ├─ db-1: "Audit current MySQL schema and queries" + ├─ db-2: "Research PostgreSQL equivalents for MySQL features" (blocks schema design) + ├─ db-3: "Design PostgreSQL schema with type mappings" + └─ db-4: "Create migration scripts and test data integrity" (blocked by db-3) +``` + +**TodoWrite role**: None initially. Might use TodoWrite for single-session testing sprints once migration scripts ready. + +### Example 2: Simple Feature Implementation + +**Scenario**: Add logging to existing endpoint based on clear specification. + +**Why TodoWrite**: +- Single session work +- Linear execution - add import, call logger, add test +- All context in user message +- Completes within conversation + +**TodoWrite**: +``` +- [ ] Import logging library +- [ ] Add log statements to endpoint +- [ ] Add test for log output +- [ ] Run tests +``` + +**bd role**: None. Overkill for straightforward task. + +### Example 3: Bug Investigation + +**Initial assessment**: Seems simple, try TodoWrite first. + +**TodoWrite**: +``` +- [ ] Reproduce bug +- [ ] Identify root cause +- [ ] Implement fix +- [ ] Add regression test +``` + +**What actually happens**: Reproducing bug reveals it's intermittent. Root cause investigation shows multiple potential issues. Needs time to investigate. + +**Transition to bd**: +``` +Create bd issue: "Fix intermittent auth failure in production" + - Description: Initially seemed simple but reproduction shows complex race condition + - Design: Three potential causes identified, need to test each + - Created issues for each hypothesis with discovered-from dependency + +Pause for day, resume next session from bd context +``` + +### Example 4: Refactoring with Dependencies + +**Scenario**: Extract common validation logic from three controllers. + +**Why bd**: +- Dependencies - must extract before modifying callers +- Multi-file changes need coordination +- Potential side quest - might discover better pattern during extraction +- Need to track which controllers updated + +**bd structure**: +``` +refactor-1: "Create shared validation module" + → blocks refactor-2, refactor-3, refactor-4 + +refactor-2: "Update auth controller to use shared validation" +refactor-3: "Update user controller to use shared validation" +refactor-4: "Update payment controller to use shared validation" +``` + +**TodoWrite role**: Could use TodoWrite for individual controller updates as implementing. + +**Why this works**: bd ensures you don't forget to update a controller. `bd ready` shows next available work. Dependencies prevent starting controller update before extraction complete. ## Common Mistakes -1. **TodoWrite for multi-session work** - Lose context after conversation -2. **bd for simple linear tasks** - Overhead not justified -3. **Not transitioning when complexity emerges** - Keep TodoWrite despite poor fit -4. **Creating too many bd issues** - Reserve bd for work needing persistence +### Mistake 1: Using TodoWrite for Multi-Session Work + +**What happens**: +- Next session, forget what was done +- Scroll conversation history to reconstruct +- Lose design decisions made during implementation +- Start over or duplicate work + +**Solution**: Create bd issue instead. Persist context across sessions. + +### Mistake 2: Using bd for Simple Linear Tasks + +**What happens**: +- Overhead of creating issue not justified +- User can't see progress in conversation +- Extra tool use for no benefit + +**Solution**: Use TodoWrite. It's designed for exactly this case. + +### Mistake 3: Not Transitioning When Complexity Emerges + +**What happens**: +- Start with TodoWrite for "simple" task +- Discover blockers and dependencies mid-way +- Keep using TodoWrite despite poor fit +- Lose context when conversation ends + +**Solution**: Transition to bd when complexity signal appears. Not too late mid-session. + +### Mistake 4: Creating Too Many bd Issues + +**What happens**: +- Every tiny task gets an issue +- Database cluttered with trivial items +- Hard to find meaningful work in `bd ready` + +**Solution**: Reserve bd for work that actually benefits from persistence. Use "2 week test" - would bd help resume after 2 weeks? If no, skip it. + +### Mistake 5: Never Using bd Because TodoWrite is Familiar + +**What happens**: +- Multi-session projects become markdown swamps +- Lose track of dependencies and blockers +- Can't resume work effectively +- Rotten half-implemented plans + +**Solution**: Force yourself to use bd for next multi-session project. Experience the difference in organization and resumability. + +### Mistake 6: Always Asking Before Creating Issues (or Never Asking) + +**When to create directly** (no user question needed): +- **Bug reports**: Clear scope, specific problem ("Found: auth doesn't check profile permissions") +- **Research tasks**: Investigative work ("Research workaround for Slides export") +- **Technical TODOs**: Discovered during implementation ("Add validation to form handler") +- **Side quest capture**: Discoveries that need tracking ("Issue: MCP can't read Shared Drive files") + +**Why create directly**: Asking slows discovery capture. User expects proactive issue creation for clear-cut problems. + +**When to ask first** (get user input): +- **Strategic work**: Fuzzy boundaries, multiple valid approaches ("Should we implement X or Y pattern?") +- **Potential duplicates**: Might overlap with existing work +- **Large epics**: Multiple approaches, unclear scope ("Plan migration strategy") +- **Major scope changes**: Changing direction of existing issue + +**Why ask**: Ensures alignment on fuzzy work, prevents duplicate effort, clarifies scope before investment. + +**Rule of thumb**: If you can write a clear, specific issue title and description in one sentence, create directly. If you need user input to clarify the work, ask first. + +**Examples**: +- ✅ Create directly: "workspace MCP: Google Doc → .docx export fails with UTF-8 encoding error" +- ✅ Create directly: "Research: Workarounds for reading Google Slides from Shared Drives" +- ❓ Ask first: "Should we refactor the auth system now or later?" (strategic decision) +- ❓ Ask first: "I found several data validation issues, should I file them all?" (potential overwhelming) + +## The Transition Point + +Most work starts with an implicit mental model: + +**"This looks straightforward"** → TodoWrite + +**As work progresses:** + +✅ **Stays straightforward** → Continue with TodoWrite, complete in session + +⚠️ **Complexity emerges** → Transition to bd, preserve context + +The skill is recognizing the transition point: + +**Transition signals:** +- "This is taking longer than expected" +- "I've discovered a blocker" +- "This needs more research" +- "I should pause this and investigate X first" +- "The user might not be available to continue today" +- "I found three related issues while working on this" + +**When you notice these signals**: Create bd issue, preserve context, work from structured foundation. ## Summary Heuristics -| Factor | TodoWrite | bd | -|--------|-----------|-----| -| **Time horizon** | Same session | Multiple sessions | -| **Dependencies** | Linear steps | Blockers/prerequisites | -| **Scope** | Well-defined | Exploratory | -| **Resume difficulty** | Easy | Need structured history | +Quick decision guides: + +**Time horizon:** +- Same session → TodoWrite +- Multiple sessions → bd + +**Dependency structure:** +- Linear steps → TodoWrite +- Blockers/prerequisites → bd + +**Scope clarity:** +- Well-defined → TodoWrite +- Exploratory → bd + +**Context complexity:** +- Conversation has everything → TodoWrite +- External context needed → bd + +**User interaction:** +- User watching progress → TodoWrite visible in chat +- Background work → bd invisible structure + +**Resume difficulty:** +- Easy from markdown → TodoWrite +- Need structured history → bd + +When in doubt: **Use the 2-week test**. If you'd struggle to resume this work after 2 weeks without bd, use bd. diff --git a/skills/bd-issue-tracking/references/CLI_REFERENCE.md b/skills/bd-issue-tracking/references/CLI_REFERENCE.md index 222efa8..704c22b 100644 --- a/skills/bd-issue-tracking/references/CLI_REFERENCE.md +++ b/skills/bd-issue-tracking/references/CLI_REFERENCE.md @@ -1,15 +1,44 @@ # CLI Command Reference -Complete bd command-line interface documentation. +**For:** AI agents and developers using bd command-line interface +**Version:** 0.21.0+ + +## Quick Navigation + +- [Basic Operations](#basic-operations) +- [Issue Management](#issue-management) +- [Dependencies & Labels](#dependencies--labels) +- [Filtering & Search](#filtering--search) +- [Advanced Operations](#advanced-operations) +- [Database Management](#database-management) ## Basic Operations ### Check Status ```bash -bd info --json # Database path, daemon status -bd ready --json # Find ready work (no blockers) -bd stale --days 30 --json # Find stale issues +# Check database path and daemon status +bd info --json + +# Example output: +# { +# "database_path": "/path/to/.beads/beads.db", +# "issue_prefix": "bd", +# "daemon_running": true, +# "agent_mail_enabled": false +# } +``` + +### Find Work + +```bash +# Find ready work (no blockers) +bd ready --json + +# Find stale issues (not updated recently) +bd stale --days 30 --json # Default: 30 days +bd stale --days 90 --status in_progress --json # Filter by status +bd stale --limit 20 --json # Limit results ``` ## Issue Management @@ -18,40 +47,68 @@ bd stale --days 30 --json # Find stale issues ```bash # Basic creation +# IMPORTANT: Always quote titles and descriptions with double quotes bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json -# With labels +# Create with explicit ID (for parallel workers) +bd create "Issue title" --id worker1-100 -p 1 --json + +# Create with labels (--labels or --label work) bd create "Issue title" -t bug -p 1 -l bug,critical --json +bd create "Issue title" -t bug -p 1 --label bug,critical --json -# Create and link discovered work -bd create "Found bug" -t bug -p 1 --deps discovered-from: --json +# Examples with special characters (all require quoting): +bd create "Fix: auth doesn't validate tokens" -t bug -p 1 --json +bd create "Add support for OAuth 2.0" -d "Implement RFC 6749 (OAuth 2.0 spec)" --json -# Create epic with hierarchical children +# Create multiple issues from markdown file +bd create -f feature-plan.md --json + +# Create epic with hierarchical child tasks bd create "Auth System" -t epic -p 1 --json # Returns: bd-a3f8e9 bd create "Login UI" -p 1 --json # Auto-assigned: bd-a3f8e9.1 +bd create "Backend validation" -p 1 --json # Auto-assigned: bd-a3f8e9.2 +bd create "Tests" -p 1 --json # Auto-assigned: bd-a3f8e9.3 + +# Create and link discovered work (one command) +bd create "Found bug" -t bug -p 1 --deps discovered-from: --json ``` ### Update Issues ```bash -bd update --status in_progress --json -bd update --priority 1 --json -bd update --notes "COMPLETED: X. IN PROGRESS: Y. NEXT: Z" -bd update --design "Implementation approach notes" +# Update one or more issues +bd update [...] --status in_progress --json +bd update [...] --priority 1 --json + +# Edit issue fields in $EDITOR (HUMANS ONLY - not for agents) +# NOTE: This command is intentionally NOT exposed via the MCP server +# Agents should use 'bd update' with field-specific parameters instead +bd edit # Edit description +bd edit --title # Edit title +bd edit --design # Edit design notes +bd edit --notes # Edit notes +bd edit --acceptance # Edit acceptance criteria ``` ### Close/Reopen Issues ```bash +# Complete work (supports multiple IDs) bd close [...] --reason "Done" --json -bd reopen --reason "Reopening" --json + +# Reopen closed issues (supports multiple IDs) +bd reopen [...] --reason "Reopening" --json ``` ### View Issues ```bash -bd show --json # Issue details -bd dep tree # Dependency tree +# Show dependency tree +bd dep tree + +# Get issue details (supports multiple IDs) +bd show [...] --json ``` ## Dependencies & Labels @@ -59,100 +116,444 @@ bd dep tree # Dependency tree ### Dependencies ```bash -bd dep add # blocker blocks blocked -bd dep add --type discovered-from # Provenance link -bd dep add --type parent-child # Hierarchy -bd dep add --type related # Soft link +# Link discovered work (old way - two commands) +bd dep add --type discovered-from + +# Create and link in one command (new way - preferred) +bd create "Issue title" -t bug -p 1 --deps discovered-from: --json ``` ### Labels ```bash -bd label add