dan/skills
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

fix(bd-issue-tracking): replace condensed files with full upstream

Browse source 
WebFetch returned summarized content, not raw markdown.
Replaced 7/8 files with actual upstream versions:

- SKILL.md: 644 lines (was 122)
- CLI_REFERENCE.md: 559 lines (was 158)
- BOUNDARIES.md: 469 lines (was 82)
- DEPENDENCIES.md: 747 lines (was 141)
- WORKFLOWS.md: 548 lines (was 178)
- ISSUE_CREATION.md: 139 lines (was 104)
- RESUMABILITY.md: 207 lines (was 171)
- STATIC_DATA.md: kept ours (59 vs 54)

Source: github.com/steveyegge/beads/examples/claude-code-skill

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
dan 2025-12-03 20:19:56 -08:00
parent a74d0a2f26
commit 8902a4f4a6
8 changed files with 2794 additions and 428 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
.beads/issues.jsonl
View file

@ -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"}

680
skills/bd-issue-tracking/SKILL.md
View file

@ -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 <issue-id>` 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 <id>`
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
```
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 <issue-id> 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
```
**Ask first** (get user input):
- Knowledge work with fuzzy boundaries
- Multiple valid approaches exist
- User's intent needs clarification
**Pattern**: Always check both `bd ready` AND `bd list --status in_progress`. Read notes field first to understand where previous session left off.
### Status Maintenance
**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?"
- `open` → `in_progress` when starting work
- Update notes field with progress
- Add dependencies as blockers discovered
- Close with summary when complete
This establishes immediate shared context about available and active work without requiring user prompting.
### Discovery Pattern
**For detailed collaborative handoff process, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-handoff)
When finding new work during implementation:
**Note**: bd auto-discovers the database:
- Uses `.beads/*.db` in current project if exists
- Falls back to `~/.beads/default.db` otherwise
- No configuration needed
### When No Work is Ready
If `bd ready` returns empty but issues exist:
```bash
# Create and link in one command
bd create "Found issue" -t bug -p 1 --deps discovered-from:<current-id> --json
bd blocked --json
```
## Session End Protocol
Report blockers and suggest next steps.
Before ending a session:
---
## 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 `<system-warning>Token usage:` messages to monitor proactively.
**Checkpoint checklist:**
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)
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
```
2. Run `bd sync` to ensure changes are committed
**Most important**: When user says "running out of context" OR when you see >70% token usage - checkpoint immediately, even if mid-task.
## Compaction Survival
**Test yourself**: "If compaction happened right now, could future-me resume from these notes?"
After compaction events, conversation history is deleted but bd state persists.
---
**Recovery checklist:**
1. `bd list --status in_progress` - see active work
2. `bd show <id>` for each - read notes field
3. Reconstruct context from COMPLETED/IN PROGRESS/NEXT
### Database Selection
## Reference Documentation
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
For detailed guidance, see the references/ subdirectory:
**Use case for global database**: Cross-project tracking, personal task management, knowledge work that doesn't belong to a specific project.
- **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
**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`
## Quick Command Reference
**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
# Find work
bd ready --json # Unblocked issues
bd blocked --json # See what's stuck
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"
# Manage issues
bd create "Title" -t bug -p 1 --json
bd update <id> --status in_progress --json
bd close <id> --reason "Done" --json
# Dependencies
bd dep add <blocker> <blocked>
bd dep tree <id>
# Session end
bd sync # Force sync to git
# 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 |

459
skills/bd-issue-tracking/references/BOUNDARIES.md
View file

@ -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.

521
skills/bd-issue-tracking/references/CLI_REFERENCE.md
View file

@ -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:<parent-id> --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:<parent-id> --json
```
### Update Issues
```bash
bd update <id> --status in_progress --json
bd update <id> --priority 1 --json
bd update <id> --notes "COMPLETED: X. IN PROGRESS: Y. NEXT: Z"
bd update <id> --design "Implementation approach notes"
# Update one or more issues
bd update <id> [<id>...] --status in_progress --json
bd update <id> [<id>...] --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 <id> # Edit description
bd edit <id> --title # Edit title
bd edit <id> --design # Edit design notes
bd edit <id> --notes # Edit notes
bd edit <id> --acceptance # Edit acceptance criteria
```
### Close/Reopen Issues
```bash
# Complete work (supports multiple IDs)
bd close <id> [<id>...] --reason "Done" --json
bd reopen <id> --reason "Reopening" --json
# Reopen closed issues (supports multiple IDs)
bd reopen <id> [<id>...] --reason "Reopening" --json
```
### View Issues
```bash
bd show <id> --json # Issue details
bd dep tree <id> # Dependency tree
# Show dependency tree
bd dep tree <id>
# Get issue details (supports multiple IDs)
bd show <id> [<id>...] --json
```
## Dependencies & Labels
@ -59,100 +116,444 @@ bd dep tree <id> # Dependency tree
### Dependencies
```bash
bd dep add <blocker-id> <blocked-id> # blocker blocks blocked
bd dep add <id> <parent> --type discovered-from # Provenance link
bd dep add <child> <parent> --type parent-child # Hierarchy
bd dep add <id1> <id2> --type related # Soft link
# Link discovered work (old way - two commands)
bd dep add <discovered-id> <parent-id> --type discovered-from
# Create and link in one command (new way - preferred)
bd create "Issue title" -t bug -p 1 --deps discovered-from:<parent-id> --json
```
### Labels
```bash
bd label add <id> <label> --json
bd label remove <id> <label> --json
# Label management (supports multiple IDs)
bd label add <id> [<id>...] <label> --json
bd label remove <id> [<id>...] <label> --json
bd label list <id> --json
bd label list-all --json
```
## Filtering & Search
```bash
# By status, priority, type
bd list --status open --priority 1 --json
bd list --type bug --json
### Basic Filters
# By labels (AND)
```bash
# Filter by status, priority, type
bd list --status open --priority 1 --json # Status and priority
bd list --assignee alice --json # By assignee
bd list --type bug --json # By issue type
bd list --id bd-123,bd-456 --json # Specific IDs
```
### Label Filters
```bash
# Labels (AND: must have ALL)
bd list --label bug,critical --json
# By labels (OR)
# Labels (OR: has ANY)
bd list --label-any frontend,backend --json
```
# Text search
### Text Search
```bash
# Title search (substring)
bd list --title "auth" --json
bd list --desc-contains "implement" --json
# Date filters
bd list --created-after 2024-01-01 --json
bd list --updated-after 2024-06-01 --json
# Pattern matching (case-insensitive substring)
bd list --title-contains "auth" --json # Search in title
bd list --desc-contains "implement" --json # Search in description
bd list --notes-contains "TODO" --json # Search in notes
```
### Date Range Filters
```bash
# Date range filters (YYYY-MM-DD or RFC3339)
bd list --created-after 2024-01-01 --json # Created after date
bd list --created-before 2024-12-31 --json # Created before date
bd list --updated-after 2024-06-01 --json # Updated after date
bd list --updated-before 2024-12-31 --json # Updated before date
bd list --closed-after 2024-01-01 --json # Closed after date
bd list --closed-before 2024-12-31 --json # Closed before date
```
### Empty/Null Checks
```bash
# Empty/null checks
bd list --empty-description --json # Issues with no description
bd list --no-assignee --json # Unassigned issues
bd list --no-labels --json # Issues with no labels
```
### Priority Ranges
```bash
# Priority ranges
bd list --priority-min 0 --priority-max 1 --json # P0 and P1 only
bd list --priority-min 2 --json # P2 and below
```
### Combine Filters
```bash
# Combine multiple filters
bd list --status open --priority 1 --label-any urgent,critical --no-assignee --json
```
## Global Flags
```bash
bd --json <command> # JSON output
bd --sandbox <command> # Sandbox mode (auto-detected)
bd --allow-stale <command> # Skip staleness check
bd --no-daemon <command> # Direct mode
```
Global flags work with any bd command and must appear **before** the subcommand.
## Sync Operations
### Sandbox Mode
**Auto-detection (v0.21.1+):** bd automatically detects sandboxed environments and enables sandbox mode.
When detected, you'll see: `ℹ️ Sandbox detected, using direct mode`
**Manual override:**
```bash
bd sync # Force immediate sync
# Does: export → commit → pull → import → push
# Explicitly enable sandbox mode
bd --sandbox <command>
# Equivalent to combining these flags:
bd --no-daemon --no-auto-flush --no-auto-import <command>
```
**ALWAYS run `bd sync` at end of agent sessions.**
**What it does:**
- Disables daemon (uses direct SQLite mode)
- Disables auto-export to JSONL
- Disables auto-import from JSONL
**When to use:** Sandboxed environments where daemon can't be controlled (permission restrictions), or when auto-detection doesn't trigger.
### Staleness Control
```bash
# Skip staleness check (emergency escape hatch)
bd --allow-stale <command>
# Example: access database even if out of sync with JSONL
bd --allow-stale ready --json
bd --allow-stale list --status open --json
```
**Shows:** `⚠️ Staleness check skipped (--allow-stale), data may be out of sync`
**⚠️ Caution:** May show stale or incomplete data. Use only when stuck and other options fail.
### Force Import
```bash
# Force metadata update even when DB appears synced
bd import --force -i .beads/beads.jsonl
```
**When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.
**Shows:** `Metadata updated (database already in sync with JSONL)`
### Other Global Flags
```bash
# JSON output for programmatic use
bd --json <command>
# Force direct mode (bypass daemon)
bd --no-daemon <command>
# Disable auto-sync
bd --no-auto-flush <command> # Disable auto-export to JSONL
bd --no-auto-import <command> # Disable auto-import from JSONL
# Custom database path
bd --db /path/to/.beads/beads.db <command>
# Custom actor for audit trail
bd --actor alice <command>
```
**See also:**
- [TROUBLESHOOTING.md - Sandboxed environments](TROUBLESHOOTING.md#sandboxed-environments-codex-claude-code-etc) for detailed sandbox troubleshooting
- [DAEMON.md](DAEMON.md) for daemon mode details
## Advanced Operations
### Cleanup
```bash
# Clean up closed issues (bulk deletion)
bd cleanup --force --json # Delete ALL closed issues
bd cleanup --older-than 30 --force --json # Delete closed >30 days ago
bd cleanup --dry-run --json # Preview what would be deleted
bd cleanup --older-than 90 --cascade --force --json # Delete old + dependents
```
### Duplicate Detection & Merging
```bash
# Find and merge duplicate issues
bd duplicates # Show all duplicates
bd duplicates --auto-merge # Automatically merge all
bd duplicates --dry-run # Preview merge operations
# Merge specific duplicate issues
bd merge <source-id...> --into <target-id> --json # Consolidate duplicates
bd merge bd-42 bd-43 --into bd-41 --dry-run # Preview merge
```
### Compaction (Memory Decay)
```bash
# Agent-driven compaction
bd compact --analyze --json # Get candidates for review
bd compact --analyze --tier 1 --limit 10 --json # Limited batch
bd compact --apply --id bd-42 --summary summary.txt # Apply compaction
bd compact --apply --id bd-42 --summary - < summary.txt # From stdin
bd compact --stats --json # Show statistics
# Legacy AI-powered compaction (requires ANTHROPIC_API_KEY)
bd compact --auto --dry-run --all # Preview
bd compact --auto --all --tier 1 # Auto-compact tier 1
# Restore compacted issue from git history
bd restore <id> # View full history at time of compaction
```
### Rename Prefix
```bash
# Rename issue prefix (e.g., from 'knowledge-work-' to 'kw-')
bd rename-prefix kw- --dry-run # Preview changes
bd rename-prefix kw- --json # Apply rename
```
## Database Management
### Import/Export
```bash
# Import issues from JSONL
bd import -i .beads/issues.jsonl --dry-run # Preview changes
bd import -i .beads/issues.jsonl # Import and update issues
bd import -i .beads/issues.jsonl --dedupe-after # Import + detect duplicates
# Handle missing parents during import
bd import -i issues.jsonl --orphan-handling allow # Default: import orphans without validation
bd import -i issues.jsonl --orphan-handling resurrect # Auto-resurrect deleted parents as tombstones
bd import -i issues.jsonl --orphan-handling skip # Skip orphans with warning
bd import -i issues.jsonl --orphan-handling strict # Fail if parent is missing
# Configure default orphan handling behavior
bd config set import.orphan_handling "resurrect"
bd sync # Now uses resurrect mode by default
```
**Orphan handling modes:**
- **`allow` (default)** - Import orphaned children without parent validation. Most permissive, ensures no data loss even if hierarchy is temporarily broken.
- **`resurrect`** - Search JSONL history for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis.
- **`skip`** - Skip orphaned children with warning. Partial import succeeds but some issues are excluded.
- **`strict`** - Fail import immediately if a child's parent is missing. Use when database integrity is critical.
**When to use:**
- Use `allow` (default) for daily imports and auto-sync
- Use `resurrect` when importing from databases with deleted parents
- Use `strict` for controlled imports requiring guaranteed parent existence
- Use `skip` rarely - only for selective imports
See [CONFIG.md](CONFIG.md#example-import-orphan-handling) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md#import-fails-with-missing-parent-errors) for more details.
### Migration
```bash
# Migrate databases after version upgrade
bd migrate # Detect and migrate old databases
bd migrate --dry-run # Preview migration
bd migrate --cleanup --yes # Migrate and remove old files
# AI-supervised migration (check before running bd migrate)
bd migrate --inspect --json # Show migration plan for AI agents
bd info --schema --json # Get schema, tables, config, sample IDs
```
**Migration workflow for AI agents:**
1. Run `--inspect` to see pending migrations and warnings
2. Check for `missing_config` (like issue_prefix)
3. Review `invariants_to_check` for safety guarantees
4. If warnings exist, fix config issues first
5. Then run `bd migrate` safely
**Migration safety invariants:**
- **required_config_present**: Ensures issue_prefix and schema_version are set
- **foreign_keys_valid**: No orphaned dependencies or labels
- **issue_count_stable**: Issue count doesn't decrease unexpectedly
These invariants prevent data loss and would have caught issues like GH #201 (missing issue_prefix after migration).
### Daemon Management
See [docs/DAEMON.md](DAEMON.md) for complete daemon management reference.
```bash
# List all running daemons
bd daemons list --json
# Check health (version mismatches, stale sockets)
bd daemons health --json
# Stop/restart specific daemon
bd daemons stop /path/to/workspace --json
bd daemons restart 12345 --json # By PID
# View daemon logs
bd daemons logs /path/to/workspace -n 100
bd daemons logs 12345 -f # Follow mode
# Stop all daemons
bd daemons killall --json
bd daemons killall --force --json # Force kill if graceful fails
```
### Sync Operations
```bash
# Manual sync (force immediate export/import/commit/push)
bd sync
# What it does:
# 1. Export pending changes to JSONL
# 2. Commit to git
# 3. Pull from remote
# 4. Import any updates
# 5. Push to remote
```
## Issue Types
- `bug` - Something broken
- `bug` - Something broken that needs fixing
- `feature` - New functionality
- `task` - Work item
- `epic` - Large feature with children
- `chore` - Maintenance work
- `task` - Work item (tests, docs, refactoring)
- `epic` - Large feature composed of multiple issues (supports hierarchical children)
- `chore` - Maintenance work (dependencies, tooling)
**Hierarchical children:** Epics can have child issues with dotted IDs (e.g., `bd-a3f8e9.1`, `bd-a3f8e9.2`). Children are auto-numbered sequentially. Up to 3 levels of nesting supported.
## Priorities
- `0` - Critical (security, data loss)
- `0` - Critical (security, data loss, broken builds)
- `1` - High (major features, important bugs)
- `2` - Medium (nice-to-have)
- `3` - Low (polish)
- `2` - Medium (nice-to-have features, minor bugs)
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)
## Dependency Types
- `blocks` - Hard dependency (affects `bd ready`)
- `related` - Soft link (informational only)
- `parent-child` - Epic/subtask hierarchy
- `discovered-from` - Track provenance
- `blocks` - Hard dependency (issue X blocks issue Y)
- `related` - Soft relationship (issues are connected)
- `parent-child` - Epic/subtask relationship
- `discovered-from` - Track issues discovered during work
Only `blocks` dependencies affect the ready work queue.
## Common Patterns
**Note:** When creating an issue with a `discovered-from` dependency, the new issue automatically inherits the parent's `source_repo` field.
## Output Formats
### JSON Output (Recommended for Agents)
Always use `--json` flag for programmatic use:
```bash
# Single issue
bd show bd-42 --json
# List of issues
bd ready --json
# Operation result
bd create "Issue" -p 1 --json
```
### Human-Readable Output
Default output without `--json`:
```bash
bd ready
# bd-42 Fix authentication bug [P1, bug, in_progress]
# bd-43 Add user settings page [P2, feature, open]
```
## Common Patterns for AI Agents
### Claim and Complete Work
```bash
bd ready --json # Find work
bd update bd-42 --status in_progress --json # Claim
# ... work ...
bd close bd-42 --reason "Done" --json # Complete
# 1. Find available work
bd ready --json
# 2. Claim issue
bd update bd-42 --status in_progress --json
# 3. Work on it...
# 4. Close when done
bd close bd-42 --reason "Implemented and tested" --json
```
### Discover and Link Work
```bash
# While working on bd-100, discover a bug
# Old way (two commands):
bd create "Found auth bug" -t bug -p 1 --json # Returns bd-101
bd dep add bd-101 bd-100 --type discovered-from
# New way (one command):
bd create "Found auth bug" -t bug -p 1 --deps discovered-from:bd-100 --json
```
### Batch Operations
```bash
# Update multiple issues at once
bd update bd-41 bd-42 bd-43 --priority 0 --json
bd close bd-41 bd-42 bd-43 --reason "Batch" --json
bd label add bd-41 bd-42 urgent --json
# Close multiple issues
bd close bd-41 bd-42 bd-43 --reason "Batch completion" --json
# Add label to multiple issues
bd label add bd-41 bd-42 bd-43 urgent --json
```
### Session Workflow
```bash
# Start of session
bd ready --json # Find work
# During session
bd create "..." -p 1 --json
bd update bd-42 --status in_progress --json
# ... work ...
# End of session (IMPORTANT!)
bd sync # Force immediate sync, bypass debounce
```
**ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
## See Also
- [AGENTS.md](../AGENTS.md) - Main agent workflow guide
- [DAEMON.md](DAEMON.md) - Daemon management and event-driven mode
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflows and merge strategies
- [LABELS.md](../LABELS.md) - Label system guide
- [README.md](../README.md) - User documentation

702
skills/bd-issue-tracking/references/DEPENDENCIES.md
View file

@ -1,84 +1,345 @@
# Dependency Types Guide
Deep dive into bd's four dependency types.
Deep dive into bd's four dependency types: blocks, related, parent-child, and discovered-from.
## Contents
- [Overview](#overview) - Four types at a glance, which affect bd ready?
- [blocks - Hard Blocker](#blocks---hard-blocker)
- [When to Use](#when-to-use) - Prerequisites, sequential steps, build order
- [When NOT to Use](#when-not-to-use) - Soft preferences, parallel work
- [Examples](#examples) - API development, migrations, library dependencies
- [Creating blocks Dependencies](#creating-blocks-dependencies)
- [Common Patterns](#common-patterns) - Build foundation first, migration sequences, testing gates
- [Automatic Unblocking](#automatic-unblocking)
- [related - Soft Link](#related---soft-link)
- [When to Use](#when-to-use-1) - Context, related features, parallel work
- [When NOT to Use](#when-not-to-use-1)
- [Examples](#examples-1) - Feature context, research links, parallel development
- [Creating related Dependencies](#creating-related-dependencies)
- [Common Patterns](#common-patterns-1) - Context clusters, research threads, feature families
- [parent-child - Hierarchical](#parent-child---hierarchical)
- [When to Use](#when-to-use-2) - Epics/subtasks, phases
- [When NOT to Use](#when-not-to-use-2)
- [Examples](#examples-2) - Epic with subtasks, phased projects
- [Creating parent-child Dependencies](#creating-parent-child-dependencies)
- [Combining with blocks](#combining-with-blocks)
- [Common Patterns](#common-patterns-2) - Epic decomposition, nested hierarchies
- [discovered-from - Provenance](#discovered-from---provenance)
- [When to Use](#when-to-use-3) - Side quests, research findings
- [Why This Matters](#why-this-matters)
- [Examples](#examples-3) - Bug discovered during feature work, research branches
- [Creating discovered-from Dependencies](#creating-discovered-from-dependencies)
- [Common Patterns](#common-patterns-3) - Discovery during implementation, research expansion
- [Combining with blocks](#combining-with-blocks-1)
- [Decision Guide](#decision-guide)
- [Decision Tree](#decision-tree)
- [Quick Reference by Situation](#quick-reference-by-situation)
- [Common Mistakes](#common-mistakes)
- Using blocks for preferences, using discovered-from for planning, not using dependencies, over-using blocks, wrong direction
- [Advanced Patterns](#advanced-patterns)
- Diamond dependencies, optional dependencies, discovery cascade, epic with phases
- [Visualization](#visualization)
- [Summary](#summary)
## Overview
bd supports four dependency types that serve different purposes in organizing and tracking work:
| Type | Purpose | Affects `bd ready`? | Common Use |
|------|---------|---------------------|------------|
| **blocks** | Hard blocker | Yes | Sequential work, prerequisites |
| **related** | Soft link | No | Context, related work |
| **parent-child** | Hierarchy | No | Epics and subtasks |
| **discovered-from** | Provenance | No | Side quests, research findings |
| **blocks** | Hard blocker | Yes - blocked issues excluded | Sequential work, prerequisites |
| **related** | Soft link | No - just informational | Context, related work |
| **parent-child** | Hierarchy | No - structural only | Epics and subtasks |
| **discovered-from** | Provenance | No - tracks origin | Side quests, research findings |
**Key insight**: Only `blocks` dependencies affect what work is ready.
**Key insight**: Only `blocks` dependencies affect what work is ready. The other three provide structure and context.
---
## blocks - Hard Blocker
**Semantics**: Issue A blocks issue B. B cannot start until A is complete.
**Effect**: Issue B disappears from `bd ready` until issue A is closed.
### When to Use
- **Prerequisites**: Database schema must exist before endpoints
- **Sequential steps**: Migration step 1 before step 2
- **Build order**: Foundation before building on top
Use `blocks` when work literally cannot proceed:
- **Prerequisites**: Database schema must exist before endpoints can use it
- **Sequential steps**: Migration step 1 must complete before step 2
- **Build order**: Foundation must be done before building on top
- **Technical blockers**: Library must be installed before code can use it
### When NOT to Use
- Soft preferences ("should do X before Y")
- Parallel work
- Information links
Don't use `blocks` for:
### Creating
- **Soft preferences**: "Should do X before Y but could do either"
- **Parallel work**: Both can proceed independently
- **Information links**: Just want to note relationship
- **Recommendations**: "Would be better if done in this order"
Use `related` instead for soft connections.
### Examples
**Example 1: API Development**
```
db-schema-1: "Create users table"
blocks
api-endpoint-2: "Add GET /users endpoint"
Why: Endpoint literally needs table to exist
Effect: api-endpoint-2 won't show in bd ready until db-schema-1 closed
```
**Example 2: Migration Sequence**
```
migrate-1: "Backup production database"
blocks
migrate-2: "Run schema migration"
blocks
migrate-3: "Verify data integrity"
Why: Each step must complete before next can safely proceed
Effect: bd ready shows only migrate-1; closing it reveals migrate-2, etc.
```
**Example 3: Library Installation**
```
setup-1: "Install JWT library"
blocks
auth-2: "Implement JWT validation"
Why: Code won't compile/run without library
Effect: Can't start auth-2 until setup-1 complete
```
### Creating blocks Dependencies
```bash
bd dep add prerequisite-id blocked-id
# Direction: from_id blocks to_id
bd dep add prerequisite-issue blocked-issue
# or explicitly:
bd dep add prerequisite-issue blocked-issue --type blocks
```
**Direction matters**: `from_id` blocks `to_id`. Think: "prerequisite blocks dependent".
### Common Patterns
**Pattern: Build Foundation First**
```
foundation-1: "Set up authentication system"
blocks all of:
- feature-2: "Add user profiles"
- feature-3: "Add admin panel"
- feature-4: "Add API access"
One foundational issue blocks multiple dependent features.
```
**Pattern: Sequential Pipeline**
```
step-1 blocks step-2 blocks step-3 blocks step-4
Linear chain where each step depends on previous.
bd ready shows only current step.
```
**Pattern: Parallel Then Merge**
```
research-1: "Investigate option A"
research-2: "Investigate option B"
research-3: "Investigate option C"
All three block:
decision-4: "Choose approach based on research"
Multiple parallel tasks must complete before next step.
```
### Automatic Unblocking
When you close a blocking issue, blocked issues automatically become ready.
When you close an issue that's blocking others:
```
1. Close db-schema-1
2. bd automatically updates: api-endpoint-2 is now ready
3. bd ready shows api-endpoint-2
4. No manual unblocking needed
```
This is why `blocks` is powerful - bd maintains ready state automatically.
---
## related - Soft Link
**Semantics**: Issues are related but neither blocks the other.
**Effect**: No impact on `bd ready`. Pure informational link.
### When to Use
- Similar work tackling same problem
- Shared context
- Alternative approaches
- Complementary features
Use `related` for context and discoverability:
### Creating
- **Similar work**: "These tackle the same problem from different angles"
- **Shared context**: "Working on one provides insight for the other"
- **Alternative approaches**: "These are different ways to solve X"
- **Complementary features**: "These work well together but aren't required"
### When NOT to Use
Don't use `related` if:
- One actually blocks the other → use `blocks`
- One discovered the other → use `discovered-from`
- One is parent of the other → use `parent-child`
### Examples
**Example 1: Related Refactoring**
```
refactor-1: "Extract validation logic"
related to
refactor-2: "Extract error handling logic"
Why: Both are refactoring efforts, similar patterns, but independent
Effect: None on ready state; just notes the relationship
```
**Example 2: Documentation and Code**
```
feature-1: "Add OAuth login"
related to
docs-2: "Document OAuth setup"
Why: Docs and feature go together, but can be done in any order
Effect: Can work on either whenever; just notes they're connected
```
**Example 3: Alternative Approaches**
```
perf-1: "Investigate Redis caching"
related to
perf-2: "Investigate CDN caching"
Why: Both address performance, different approaches, explore both
Effect: Both show in bd ready; choosing one doesn't block the other
```
### Creating related Dependencies
```bash
bd dep add issue-1 issue-2 --type related
# Direction doesn't matter - symmetric link
```
**Direction doesn't matter** for `related` - it's a symmetric link.
### Common Patterns
**Pattern: Cluster Related Work**
```
api-redesign related to:
- api-docs-update
- api-client-update
- api-tests-update
- api-versioning
Group of issues all related to API work.
Use related to show they're part of same initiative.
```
**Pattern: Cross-Cutting Concerns**
```
security-audit related to:
- auth-module
- api-endpoints
- database-access
- frontend-forms
Security audit touches multiple areas.
Related links show what areas it covers.
```
---
## parent-child - Hierarchical
**Semantics**: Issue A is parent of issue B (epic/subtask).
**Semantics**: Issue A is parent of issue B. Typically A is an epic, B is a subtask.
**Effect**: No impact on `bd ready`. Creates hierarchical structure.
### When to Use
- Epics and subtasks
- Hierarchical organization
- Progress tracking
- Work breakdown structure
Use `parent-child` for breaking down large work:
### Creating
- **Epics and subtasks**: Big feature split into smaller pieces
- **Hierarchical organization**: Logical grouping of related tasks
- **Progress tracking**: See completion of children relative to parent
- **Work breakdown structure**: Decompose complex work
### When NOT to Use
Don't use `parent-child` if:
- Siblings need ordering → add `blocks` between children
- Relationship is equality → use `related`
- Just discovered one from the other → use `discovered-from`
### Examples
**Example 1: Feature Epic**
```
oauth-epic: "Implement OAuth integration" (epic)
parent of:
- oauth-1: "Set up OAuth credentials" (task)
- oauth-2: "Implement authorization flow" (task)
- oauth-3: "Add token refresh" (task)
- oauth-4: "Create login UI" (task)
Why: Epic decomposed into implementable tasks
Effect: Hierarchical structure; all show in bd ready (unless blocked)
```
**Example 2: Research with Findings**
```
research-epic: "Investigate caching strategies" (epic)
parent of:
- research-1: "Redis evaluation"
- research-2: "Memcached evaluation"
- research-3: "CDN evaluation"
- decision-4: "Choose caching approach"
Why: Research project with multiple investigation threads
Effect: Can track progress across all investigations
```
### Creating parent-child Dependencies
```bash
bd dep add child-id parent-id --type parent-child
# Child depends on parent
bd dep add child-task-id parent-epic-id --type parent-child
```
**Direction matters**: The child depends on the parent. Think: "child depends on parent" or "task is part of epic".
### Combining with blocks
parent-child gives structure; blocks gives ordering:
Parent-child gives structure; blocks gives ordering:
```
auth-epic (parent of all)
@ -86,34 +347,182 @@ auth-epic (parent of all)
├─ auth-2: "Create middleware" (blocked by auth-1)
├─ auth-3: "Add endpoints" (blocked by auth-2)
└─ auth-4: "Add tests" (blocked by auth-3)
parent-child: Shows these are all part of auth epic
blocks: Shows they must be done in order
```
### Common Patterns
**Pattern: Epic with Independent Subtasks**
```
Epic with no ordering between children:
All children show in bd ready immediately.
Work on any child in any order.
Close epic when all children complete.
```
**Pattern: Epic with Sequential Subtasks**
```
Epic with blocks dependencies between children:
bd ready shows only first child.
Closing each child unblocks next.
Epic provides structure, blocks provides order.
```
**Pattern: Nested Epics**
```
major-epic
├─ sub-epic-1
│ ├─ task-1a
│ └─ task-1b
└─ sub-epic-2
├─ task-2a
└─ task-2b
Multiple levels of hierarchy for complex projects.
```
---
## discovered-from - Provenance
**Semantics**: Issue B was discovered while working on issue A.
**Effect**: No impact on `bd ready`. Tracks origin and provides context.
### When to Use
- Side quests found during implementation
- Research findings
- Bug found during feature work
- Follow-up work
Use `discovered-from` to preserve discovery context:
- **Side quests**: Found new work during implementation
- **Research findings**: Discovered issue while investigating
- **Bug found during feature work**: Context of discovery matters
- **Follow-up work**: Identified next steps during current work
### Why This Matters
Knowing where an issue came from helps:
- Understand context
- Reconstruct thinking
- Assess relevance
### Creating
- **Understand context**: Why was this created?
- **Reconstruct thinking**: What led to this discovery?
- **Assess relevance**: Is this still important given original context?
- **Track exploration**: See what emerged from research
### Examples
**Example 1: Bug During Feature**
```
feature-10: "Add user profiles"
discovered-from leads to
bug-11: "Existing auth doesn't handle profile permissions"
Why: While adding profiles, discovered auth system inadequate
Context: Bug might not exist if profiles weren't being added
```
**Example 2: Research Findings**
```
research-5: "Investigate caching options"
discovered-from leads to
finding-6: "Redis supports persistence unlike Memcached"
finding-7: "CDN caching incompatible with our auth model"
decision-8: "Choose Redis based on findings"
Why: Research generated specific findings
Context: Findings only relevant in context of research question
```
**Example 3: Refactoring Reveals Technical Debt**
```
refactor-20: "Extract validation logic"
discovered-from leads to
debt-21: "Validation inconsistent across controllers"
debt-22: "No validation for edge cases"
improvement-23: "Could add validation library"
Why: Refactoring work revealed multiple related issues
Context: Issues discovered as side effect of refactoring
```
### Creating discovered-from Dependencies
```bash
bd dep add original-work-id discovered-issue-id --type discovered-from
# to_id was discovered while working on from_id
```
## Decision Tree
**Direction matters**: `to_id` was discovered while working on `from_id`.
### Common Patterns
**Pattern: Exploration Tree**
```
spike-1: "Investigate API redesign"
discovered-from →
finding-2: "Current API mixes REST and GraphQL"
finding-3: "Authentication not consistent"
finding-4: "Rate limiting missing"
One exploration generates multiple findings.
Tree structure shows exploration process.
```
**Pattern: Bug Investigation Chain**
```
bug-1: "Login fails intermittently"
discovered-from →
bug-2: "Race condition in session creation"
discovered-from →
bug-3: "Database connection pool too small"
Investigation of one bug reveals root cause as another bug.
Chain shows how you got from symptom to cause.
```
**Pattern: Feature Implementation Side Quests**
```
feature-main: "Add shopping cart"
discovered-from →
improvement-a: "Product images should be cached"
bug-b: "Price formatting wrong for some locales"
debt-c: "Inventory system needs refactoring"
Main feature work generates tangential discoveries.
Captured for later without derailing main work.
```
### Combining with blocks
Can use both together:
```
feature-10: "Add user profiles"
discovered-from →
bug-11: "Auth system needs role-based access"
blocks →
feature-10: "Add user profiles"
Discovery: Found bug during feature work
Assessment: Bug actually blocks feature
Actions: Mark feature blocked, work on bug first
```
---
## Decision Guide
**"Which dependency type should I use?"**
### Decision Tree
```
Does Issue A prevent Issue B from starting?
@ -121,21 +530,218 @@ Does Issue A prevent Issue B from starting?
NO ↓
Is Issue B a subtask of Issue A?
YES → parent-child
YES → parent-child (A parent, B child)
NO ↓
Was Issue B discovered while working on Issue A?
YES → discovered-from
YES → discovered-from (A original, B discovered)
NO ↓
Are Issues A and B just related?
YES → related
```
### Quick Reference by Situation
| Situation | Use |
|-----------|-----|
| B needs A complete to start | blocks |
| B is part of A (epic/task) | parent-child |
| Found B while working on A | discovered-from |
| A and B are similar/connected | related |
| B should come after A but could start | related + note |
| A and B are alternatives | related |
| B is follow-up to A | discovered-from |
---
## Common Mistakes
1. **Using blocks for preferences** - Use related instead
2. **Using discovered-from for planning** - Use parent-child instead
3. **Not using dependencies** - Add structure with dependencies
4. **Over-using blocks** - Allow parallel work where possible
5. **Wrong direction** - "from_id blocks to_id"
### Mistake 1: Using blocks for Preferences
**Wrong**:
```
docs-1: "Update documentation"
blocks
feature-2: "Add new feature"
Reason: "We prefer to update docs first"
```
**Problem**: Documentation doesn't actually block feature implementation.
**Right**: Use `related` or don't link at all. If you want ordering, note it in issue descriptions but don't enforce with blocks.
### Mistake 2: Using discovered-from for Planning
**Wrong**:
```
epic-1: "OAuth integration"
discovered-from →
task-2: "Set up OAuth credentials"
Reason: "I'm planning these tasks from the epic"
```
**Problem**: `discovered-from` is for emergent discoveries, not planned decomposition.
**Right**: Use `parent-child` for planned task breakdown.
### Mistake 3: Not Using Any Dependencies
**Symptom**: Long list of issues with no structure.
**Problem**: Can't tell what's blocked, what's related, how work is organized.
**Solution**: Add structure with dependencies:
- Group with parent-child
- Order with blocks
- Link with related
- Track discovery with discovered-from
### Mistake 4: Over-Using blocks
**Wrong**:
```
Everything blocks everything else in strict sequential order.
```
**Problem**: No parallel work possible; `bd ready` shows only one issue.
**Right**: Only use `blocks` for actual technical dependencies. Allow parallel work where possible.
### Mistake 5: Wrong Direction
**Wrong**:
```bash
bd dep add api-endpoint database-schema
Meaning: api-endpoint blocks database-schema
```
**Problem**: Backwards! Schema should block endpoint, not other way around.
**Right**:
```bash
bd dep add database-schema api-endpoint
Meaning: database-schema blocks api-endpoint
```
**Mnemonic**: "from_id blocks to_id" or "prerequisite blocks dependent"
---
## Advanced Patterns
### Pattern: Diamond Dependencies
```
setup
/ \
impl-a impl-b
\ /
testing
setup blocks both impl-a and impl-b
both impl-a and impl-b block testing
```
Both implementations must complete before testing can begin.
### Pattern: Optional Dependencies
```
core-feature (ready immediately)
related to
nice-to-have (ready immediately)
Both can be done, neither blocks the other.
Use related to show they're connected.
```
### Pattern: Discovery Cascade
```
research-main
discovered-from → finding-1
discovered-from → finding-2
discovered-from → deep-finding-3
Research generates findings.
Findings generate deeper findings.
Tree shows discovery process.
```
### Pattern: Epic with Phases
```
auth-epic
parent of phase-1-epic
parent of: setup-1, setup-2, setup-3
parent of phase-2-epic
parent of: implement-1, implement-2
parent of phase-3-epic
parent of: test-1, test-2
phase-1-epic blocks phase-2-epic blocks phase-3-epic
Nested hierarchy with phase ordering.
```
---
## Visualization
When you run `bd show issue-id` on an issue, you see:
```
Issue: feature-10
Dependencies (blocks this issue):
- setup-5: "Install library"
- config-6: "Add configuration"
Dependents (blocked by this issue):
- test-12: "Add integration tests"
- docs-13: "Document new feature"
Related:
- refactor-8: "Similar refactoring effort"
Discovered from:
- research-3: "API investigation"
```
This shows the full dependency context for an issue.
---
## Summary
**Four dependency types, four different purposes:**
1. **blocks**: Sequential work, prerequisites, hard blockers
- Affects bd ready
- Use for technical dependencies only
2. **related**: Context, similar work, soft connections
- Informational only
- Use liberally for discoverability
3. **parent-child**: Epics and subtasks, hierarchical structure
- Organizational only
- Use for work breakdown
4. **discovered-from**: Side quests, research findings, provenance
- Context preservation
- Use to track emergence
**Key insight**: Only `blocks` affects what work is ready. The other three provide rich context without constraining execution.
Use dependencies to create a graph that:
- Automatically maintains ready work
- Preserves discovery context
- Shows project structure
- Links related work
This graph becomes the persistent memory that survives compaction and enables long-horizon agent work.

173
skills/bd-issue-tracking/references/ISSUE_CREATION.md
View file

@ -1,104 +1,139 @@
# Issue Creation Guidelines
When and how to create bd issues for maximum effectiveness.
Guidance on when and how to create bd issues for maximum effectiveness.
## When to Ask First vs Create Directly
## Contents
- [When to Ask First vs Create Directly](#when-to-ask)
- [Issue Quality](#quality)
- [Making Issues Resumable](#resumable)
- [Design vs Acceptance Criteria](#design-vs-acceptance)
## When to Ask First vs Create Directly {#when-to-ask}
### Ask the user before creating when:
- Knowledge work with fuzzy boundaries
- Task scope is unclear
- Multiple valid approaches exist
- User's intent needs clarification
### Create directly when:
- Clear bug discovered during implementation
- Obvious follow-up work identified
- Technical debt with clear scope
- Dependency or blocker found
- **Clear bug discovered** during implementation
- **Obvious follow-up work** identified
- **Technical debt** with clear scope
- **Dependency or blocker** found
**Why ask first for knowledge work?** Task boundaries in strategic/research work are often unclear until discussed, whereas technical implementation tasks are usually well-defined. Discussion helps structure the work properly before creating issues, preventing poorly-scoped issues that need immediate revision.
### Ask first when:
## Issue Quality {#quality}
- Knowledge work with **fuzzy boundaries**
- **Multiple valid approaches** exist
- **User's intent** needs clarification
- **Large epics** with unclear scope
**Rule of thumb**: If you can write a clear, specific issue title in one sentence, create directly.
## Issue Quality
Use clear, specific titles and include sufficient context in descriptions to resume work later.
### Field Usage
**Title**: Clear, specific, action-oriented
- Good: "Fix: auth token expires before refresh"
- Bad: "Fix bug"
**Description**: Problem statement, context, why it matters
- Good: "Update database: add user_last_login for session analytics"
- Bad: "Update database"
**Design field** (--design): Implementation approach
- Architecture decisions
**Use --design flag for:**
- Implementation approach decisions
- Architecture notes
- Trade-offs considered
- Can change during implementation
**Acceptance criteria** (--acceptance): Definition of done
- Outcomes, not implementation steps
- Should remain stable across sessions
- Each criterion should be verifiable
**Use --acceptance flag for:**
- Definition of done
- Testing requirements
- Success metrics
**Notes field**: Session handoffs, implementation details
- COMPLETED/IN_PROGRESS/NEXT format
- Evolves over time
## Making Issues Resumable (Complex Technical Work) {#resumable}
## Design vs Acceptance Criteria
For complex technical features spanning multiple sessions, enhance notes field with implementation details.
Common mistake: Putting implementation details in acceptance criteria.
### Optional but valuable for technical work:
- Working API query code (tested, with response structure)
- Sample API responses showing actual data
- Desired output format examples (show, don't describe)
- Research context (why this approach, what was discovered)
### DESIGN field (HOW to build):
### Example pattern:
```
"Use two-phase batchUpdate approach: insert text first, then apply formatting"
"Parse with regex to find markers"
"Use JWT tokens with 1-hour expiry"
```markdown
bd update issue-9 --notes "IMPLEMENTATION GUIDE:
WORKING CODE: service.about().get(fields='importFormats')
Returns: dict with 49 entries like {'text/markdown': [...]}
OUTPUT FORMAT: # Drive Import Formats (markdown with categorized list)
CONTEXT: text/markdown support added July 2024, not in static docs"
```
### ACCEPTANCE CRITERIA (WHAT success looks like):
**When to add:** Multi-session technical features with APIs or specific formats. Skip for simple tasks.
```
"Bold and italic formatting renders correctly"
"User tokens persist across sessions"
"Returns doc_id and webViewLink to caller"
```
**For detailed patterns and examples, read:** [RESUMABILITY.md](RESUMABILITY.md)
## Design vs Acceptance Criteria (Critical Distinction) {#design-vs-acceptance}
Common mistake: Putting implementation details in acceptance criteria. Here's the difference:
### DESIGN field (HOW to build it):
- "Use two-phase batchUpdate approach: insert text first, then apply formatting"
- "Parse with regex to find * and _ markers"
- "Use JWT tokens with 1-hour expiry"
- Trade-offs: "Chose batchUpdate over streaming API for atomicity"
### ACCEPTANCE CRITERIA (WHAT SUCCESS LOOKS LIKE):
- "Bold and italic markdown formatting renders correctly in the Doc"
- "Solution accepts markdown input and creates Doc with specified title"
- "Returns doc_id and webViewLink to caller"
- "User tokens persist across sessions and refresh automatically"
### Why this matters:
- Design can change during implementation (e.g., use library instead of regex)
- Acceptance criteria should remain stable across sessions
- Criteria should be **outcome-focused** ("what must be true?") not **step-focused** ("do these steps")
- Each criterion should be **verifiable** - you can definitively say yes/no
- Design can change during implementation
- Acceptance criteria should remain stable
- Criteria should be **outcome-focused** not **step-focused**
- Each criterion should be **verifiable** (yes/no)
### The pitfall
### The test:
Writing criteria like "- [ ] Use batchUpdate approach" locks you into one implementation.
If you rewrote the solution using a different approach, would the acceptance criteria still apply? If not, they're design notes.
Better: "- [ ] Formatting is applied atomically (all at once or not at all)" - allows flexible implementation.
### Example
### Test yourself
**Wrong (design masquerading as criteria):**
If you rewrote the solution using a different approach, would the acceptance criteria still apply? If not, they're design notes, not criteria.
### Example of correct structure
✅ **Design field:**
```
Two-phase Docs API approach:
1. Parse markdown to positions
2. Create doc + insert text in one call
3. Apply formatting in second call
Rationale: Atomic operations, easier to debug formatting separately
```
✅ **Acceptance criteria:**
```
- [ ] Markdown formatting renders in Doc (bold, italic, headings)
- [ ] Lists preserve order and nesting
- [ ] Links are clickable
- [ ] Large documents (>50KB) process without timeout
```
❌ **Wrong (design masquerading as criteria):**
```
- [ ] Use two-phase batchUpdate approach
- [ ] Apply formatting in second call
```
**Right:**
```
Design: Two-phase Docs API approach for atomic operations
Acceptance:
- [ ] Markdown formatting renders in Doc
- [ ] Lists preserve order and nesting
- [ ] Large documents process without timeout
- [ ] Apply formatting in second batchUpdate call
```
## Quick Reference
**Creating good issues:**
1. **Title**: Clear, specific, action-oriented
2. **Description**: Problem statement, context
3. **Design**: Approach, trade-offs (can change)
4. **Acceptance**: Outcomes (should be stable)
5. **Notes**: Implementation details, session handoffs
2. **Description**: Problem statement, context, why it matters
3. **Design**: Approach, architecture, trade-offs (can change)
4. **Acceptance**: Outcomes, success criteria (should be stable)
5. **Notes**: Implementation details, session handoffs (evolves over time)
**Common mistakes:**
- Vague titles: "Fix bug" → "Fix: auth token expires before refresh"
- Implementation in acceptance: "Use JWT" → "Auth tokens persist across sessions"
- Missing context: "Update database" → "Update database: add user_last_login for session analytics"

152
skills/bd-issue-tracking/references/RESUMABILITY.md
View file

@ -1,171 +1,207 @@
# Making Issues Resumable Across Sessions
How to document issues so work can be resumed after days or weeks.
## When Resumability Matters
**Use enhanced documentation for:**
- Multi-session technical features with API integration
- Complex algorithms requiring code examples
- Features with specific output format requirements
- Work with undocumented API capabilities
- Work with "occult" APIs (undocumented capabilities)
**Skip for:**
- Simple bug fixes with clear scope
- Well-understood patterns
- Well-understood patterns (CRUD operations, etc.)
- Single-session tasks
- Work with obvious acceptance criteria
**The test:** Would a fresh Claude instance struggle to resume from the description alone?
**The test:** Would a fresh Claude instance (or you after 2 weeks) struggle to resume this work from the description alone? If yes, add implementation details.
## Anatomy of a Resumable Issue
### Minimal (Always Include)
```
```markdown
Description: What needs to be built and why
Acceptance Criteria: Concrete, testable outcomes
Acceptance Criteria: Concrete, testable outcomes (WHAT not HOW)
```
### Enhanced (Complex Technical Work)
```
```markdown
Notes Field - IMPLEMENTATION GUIDE:
WORKING CODE:
```python
# Tested code that works
# Tested code that queries the API
service = build('drive', 'v3', credentials=creds)
result = service.about().get(fields='importFormats').execute()
# Returns: {'text/markdown': ['application/vnd.google-apps.document'], ...}
```
API RESPONSE SAMPLE:
Shows actual data structure
Shows actual data structure (not docs description)
DESIRED OUTPUT FORMAT:
```markdown
# Example of actual output structure
# Example of what the output should look like
Not just "return markdown" but actual structure
```
RESEARCH CONTEXT:
Why this approach? What alternatives considered?
Why this approach? What alternatives were considered?
Key discoveries that informed the design.
```
## Real Example
### Not Resumable
## Real Example: Before vs After
### ❌ Not Resumable
```
Title: Add dynamic capabilities resources
Description: Query Google APIs for capabilities
Description: Query Google APIs for capabilities and return as resources
Acceptance: Resources return capability info
```
**Problem:** Future Claude doesn't know:
- Which API endpoints to call
- What responses look like
- What the responses look like
- What format to return
### Resumable
### ✅ Resumable
```
Title: Add dynamic capabilities resources
Description: Query Google APIs for system capabilities that aren't in static docs.
Description: Query Google APIs for system capabilities (import formats,
themes, quotas) that aren't in static docs. Makes server self-documenting.
Notes: IMPLEMENTATION GUIDE
WORKING CODE (tested):
```python
from workspace_mcp.tools.drive import get_credentials
from googleapiclient.discovery import build
creds = get_credentials()
service = build('drive', 'v3', credentials=creds)
about = service.about().get(
fields='importFormats,exportFormats'
fields='importFormats,exportFormats,folderColorPalette'
).execute()
# Returns: importFormats dict with 49 entries
# Returns:
# - importFormats: dict, 49 entries like {'text/markdown': [...]}
# - exportFormats: dict, 10 entries
# - folderColorPalette: list, 24 hex strings
```
OUTPUT FORMAT:
OUTPUT FORMAT EXAMPLE:
```markdown
# Drive Import Formats
- **text/markdown** → Google Docs (NEW July 2024)
Google Drive supports 49 import formats:
## Text Formats
- **text/markdown** → Google Docs ✨ (NEW July 2024)
- text/plain → Google Docs
...
```
RESEARCH CONTEXT:
text/markdown support not in static docs.
text/markdown support announced July 2024 but NOT in static Google docs.
Google's workspace-developer MCP server doesn't expose this.
This is why dynamic resources matter.
Acceptance:
- Query returns all formats including text/markdown
- Output is readable markdown
- Queries live API
Acceptance Criteria:
- User queries workspace://capabilities/drive/import-formats
- Response shows all 49 formats including text/markdown
- Output is readable markdown, not raw JSON
- Queries live API (not static data)
```
**Result:** Fresh Claude can implement with full context.
**Result:** Fresh Claude instance can:
1. See working API query code
2. Understand response structure
3. Know desired output format
4. Implement with context
## Template
## Optional Template
For complex technical features:
Copy this into notes field for complex technical features:
```markdown
IMPLEMENTATION GUIDE:
IMPLEMENTATION GUIDE FOR FUTURE SESSIONS:
WORKING CODE (tested):
```language
# Actual working code
# Paste actual code that works
# Include imports and setup
# Show what it returns
```
API RESPONSE SAMPLE:
```json
{ "actualField": "actualValue" }
{
"actualField": "actualValue",
"structure": "as returned by API"
}
```
DESIRED OUTPUT FORMAT:
```
Actual structure/style, not just "markdown"
Show what the final output should look like
Not just "markdown" but actual structure/style
```
RESEARCH CONTEXT:
- Why this approach?
- Alternatives considered?
- What alternatives considered?
- Key discoveries?
- Links to relevant docs/examples?
```
## Anti-Patterns
### Over-Documenting Simple Work
```
### ❌ Over-Documenting Simple Work
```markdown
Title: Fix typo in README
Notes: IMPLEMENTATION GUIDE...
Notes: IMPLEMENTATION GUIDE
WORKING CODE: Open README.md, change "teh" to "the"...
```
Wastes tokens on obvious work.
**Problem:** Wastes tokens on obvious work.
### Design in Acceptance Criteria
```
### ❌ Design Details in Acceptance Criteria
```markdown
Acceptance:
- [ ] Use batchUpdate approach
- [ ] Call API with fields parameter
- [ ] Format as markdown with ## headers
```
Locks implementation. Put in Design/Notes.
### Raw JSON Dumps
**Problem:** Locks implementation. Should be in Design/Notes, not Acceptance.
### ❌ Raw JSON Dumps
```markdown
API RESPONSE:
{giant unformatted JSON blob spanning 100 lines}
```
API RESPONSE: {giant unformatted blob}
```
Extract relevant parts, show structure.
**Problem:** Hard to read. Extract relevant parts, show structure.
## When to Add Detail
### ✅ Right Balance
```markdown
API RESPONSE SAMPLE:
Returns dict with 49 entries. Example entries:
- 'text/markdown': ['application/vnd.google-apps.document']
- 'text/plain': ['application/vnd.google-apps.document']
- 'application/pdf': ['application/vnd.google-apps.document']
```
## When to Add This Detail
**During issue creation:**
- Already have working code from research? Include it.
- Clear output format? Show example.
- Clear output format in mind? Show example.
**During work:**
- Got API query working? Add to notes.
**During work (update notes):**
- Just got API query working? Add to notes.
- Discovered important context? Document it.
- Made key decision? Explain rationale.
**Session end:**
- If resuming will be hard, add implementation guide.
- If obvious, skip it.
**Principle:** Help your future self resume without rediscovering everything.
**The principle:** Help your future self (or next Claude) resume without rediscovering everything.

498
skills/bd-issue-tracking/references/WORKFLOWS.md
View file

@ -1,57 +1,126 @@
# Workflows and Checklists
Step-by-step workflows for common bd usage patterns.
Detailed step-by-step workflows for common bd usage patterns with checklists.
## Session Start Workflow
## Contents
- [Session Start Workflow](#session-start) - Check bd ready, establish context
- [Compaction Survival](#compaction-survival) - Recovering after compaction events
- [Discovery and Issue Creation](#discovery) - Proactive issue creation during work
- [Status Maintenance](#status-maintenance) - Keeping bd status current
- [Epic Planning](#epic-planning) - Structuring complex work with dependencies
- [Side Quest Handling](#side-quests) - Discovery during main task, assessing blocker vs deferrable, resuming
- [Multi-Session Resume](#resume) - Returning after days/weeks away
- [Session Handoff Workflow](#session-handoff) - Collaborative handoff between sessions
- [Unblocking Work](#unblocking) - Handling blocked issues
- [Integration with TodoWrite](#integration-with-todowrite) - Using both tools together
- [Common Workflow Patterns](#common-workflow-patterns)
- Systematic Exploration, Bug Investigation, Refactoring with Dependencies, Spike Investigation
- [Checklist Templates](#checklist-templates)
- Starting Any Work Session, Creating Issues During Work, Completing Work, Planning Complex Features
- [Decision Points](#decision-points)
- [Troubleshooting Workflows](#troubleshooting-workflows)
## Session Start Workflow {#session-start}
**bd is available when**:
- Project has `.beads/` directory (project-local), OR
- `~/.beads/` exists (global fallback for any directory)
**Automatic checklist at session start:**
```
Session Start (when bd is available):
- [ ] Run bd ready --json
- [ ] Report: "X items ready to work on: [summary]"
- [ ] If using global ~/.beads, note this in report
- [ ] If none ready, check bd blocked --json
- [ ] Suggest next action based on findings
```
## Compaction Survival
**Pattern**: Always run `bd ready` when starting work where bd is available. Report status immediately to establish shared context.
After compaction events, conversation history is deleted but bd state persists.
**Database selection**: bd auto-discovers which database to use (project-local `.beads/` takes precedence over global `~/.beads/`).
---
## Compaction Survival {#compaction-survival}
**Critical**: After compaction events, conversation history is deleted but bd state persists. Beads are your only memory.
**Post-compaction recovery checklist:**
```
Post-Compaction Recovery:
- [ ] Run bd list --status in_progress
- [ ] Run bd show <id> for each in_progress issue
- [ ] Read notes field: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS
- [ ] Check dependencies: bd dep tree <id>
- [ ] Reconstruct context from issue data
After Compaction:
- [ ] Run bd list --status in_progress to see active work
- [ ] Run bd show <issue-id> for each in_progress issue
- [ ] Read notes field to understand: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS
- [ ] Check dependencies: bd dep tree <issue-id> for context
- [ ] If notes insufficient, check bd list --status open for related issues
- [ ] Reconstruct TodoWrite list from notes if needed
```
### Writing Notes for Compaction Survival
**Pattern**: Well-written notes enable full context recovery even with zero conversation history.
**Writing notes for compaction survival:**
**Good note (enables recovery):**
```
COMPLETED: User authentication - added JWT token generation with 1hr expiry.
IN PROGRESS: Password reset flow. Email service integration working.
NEXT: Add rate limiting to reset endpoint.
KEY DECISION: Using bcrypt with 12 rounds per OWASP recommendations.
bd update issue-42 --notes "COMPLETED: User authentication - added JWT token
generation with 1hr expiry, implemented refresh token endpoint using rotating
tokens pattern. IN PROGRESS: Password reset flow. Email service integration
working. NEXT: Need to add rate limiting to reset endpoint (currently unlimited
requests). KEY DECISION: Using bcrypt with 12 rounds after reviewing OWASP
recommendations, tech lead concerned about response time but benchmarks show <100ms."
```
**Bad note:**
**Bad note (insufficient for recovery):**
```
Working on auth feature. Made some progress. More to do later.
bd update issue-42 --notes "Working on auth feature. Made some progress.
More to do later."
```
## Discovery and Issue Creation
The good note contains:
- Specific accomplishments (what was implemented/configured)
- Current state (which part is working, what's in progress)
- Next concrete step (not just "continue")
- Key context (team concerns, technical decisions with rationale)
**After compaction**: `bd show issue-42` reconstructs the full context needed to continue work.
---
## Discovery and Issue Creation {#discovery}
**When encountering new work during implementation:**
```
Discovery Workflow:
- [ ] Notice bug, improvement, or follow-up work
- [ ] Assess: Can defer or is blocker?
- [ ] Create issue with bd create
- [ ] Add discovered-from dependency
- [ ] Create issue with bd create "Issue title"
- [ ] Add discovered-from dependency: bd dep add current-id new-id --type discovered-from
- [ ] If blocker: pause and switch; if not: continue current work
- [ ] Issue persists for future sessions
```
## Status Maintenance
**Pattern**: Proactively file issues as you discover work. Context captured immediately instead of lost when session ends.
**When to ask first**:
- Knowledge work with fuzzy scope
- User intent unclear
- Multiple valid approaches
**When to create directly**:
- Clear bug found
- Obvious follow-up work
- Technical debt with clear scope
---
## Status Maintenance {#status-maintenance}
**Throughout work on an issue:**
```
Issue Lifecycle:
@ -59,120 +128,421 @@ Issue Lifecycle:
- [ ] During: Add design notes as decisions made
- [ ] During: Update acceptance criteria if requirements clarify
- [ ] During: Add dependencies if blockers discovered
- [ ] Complete: Close with summary
- [ ] After: Check bd ready for unblocked work
- [ ] Complete: Close with summary of what was done
- [ ] After: Check bd ready to see what unblocked
```
## Epic Planning
**Pattern**: Keep bd status current so project state is always accurate.
**Status transitions**:
- `open` → `in_progress` when starting work
- `in_progress` → `blocked` if blocker discovered
- `blocked` → `in_progress` when unblocked
- `in_progress` → `closed` when complete
---
## Epic Planning {#epic-planning}
**For complex multi-step features:**
```
Epic Planning Workflow:
- [ ] Create epic issue for high-level goal
- [ ] Break down into child task issues
- [ ] Add parent-child dependencies
- [ ] Add blocks dependencies between children if order matters
- [ ] Use bd ready to work through tasks
- [ ] Create each child task
- [ ] Add parent-child dependencies from epic to each child
- [ ] Add blocks dependencies between children if needed
- [ ] Use bd ready to work through tasks in dependency order
```
## Side Quest Handling
**Example**: OAuth Integration Epic
```bash
1. Create epic:
bd create "Implement OAuth integration" -t epic -d "OAuth with Google and GitHub"
design: "Support Google and GitHub providers"
2. Create child tasks:
bd create "Set up OAuth client credentials" -t task
bd create "Implement authorization code flow" -t task
bd create "Add token storage and refresh" -t task
bd create "Create login/logout endpoints" -t task
3. Link children to parent:
bd dep add oauth-epic oauth-setup --type parent-child
bd dep add oauth-epic oauth-flow --type parent-child
bd dep add oauth-epic oauth-storage --type parent-child
bd dep add oauth-epic oauth-endpoints --type parent-child
4. Add blocks between children:
bd dep add oauth-setup oauth-flow
# Setup blocks flow implementation
```
---
## Side Quest Handling {#side-quests}
**When discovering work that pauses main task:**
```
Side Quest Workflow:
- [ ] During main work, discover problem
- [ ] During main work, discover problem or opportunity
- [ ] Create issue for side quest
- [ ] Add discovered-from dependency
- [ ] Assess: blocker or deferrable?
- [ ] If blocker: mark main work blocked, switch
- [ ] Add discovered-from dependency linking to main work
- [ ] Assess: blocker or can defer?
- [ ] If blocker: mark main work blocked, switch to side quest
- [ ] If deferrable: note in issue, continue main work
- [ ] Update statuses to reflect current focus
```
## Session Handoff
### At Session Start
**Example**: During feature implementation, discover architectural issue
```
- [ ] Run bd list --status in_progress
- [ ] For each: bd show <id>
- [ ] Read notes field for context
- [ ] Report to user with context
- [ ] Wait for confirmation
Main task: Adding user profiles
Discovery: Notice auth system should use role-based access
Actions:
1. Create issue: "Implement role-based access control"
2. Link: discovered-from "user-profiles-feature"
3. Assess: Blocker for profiles feature
4. Mark profiles as blocked
5. Switch to RBAC implementation
6. Complete RBAC, unblocks profiles
7. Resume profiles work
```
### At Session End
---
```
- [ ] Notice work reaching stopping point
- [ ] Prompt user about updating notes
- [ ] Craft note with COMPLETED/IN_PROGRESS/NEXT
- [ ] Execute bd update command
- [ ] Run bd sync
```
## Multi-Session Resume {#resume}
## Multi-Session Resume
**Starting work after days/weeks away:**
```
Resume Workflow:
- [ ] Run bd ready for available work
- [ ] Run bd ready to see available work
- [ ] Run bd stats for project overview
- [ ] List recent closed issues for context
- [ ] Show details on issue to work on
- [ ] Review design notes and acceptance criteria
- [ ] Update status to in_progress
- [ ] Begin work with full context
```
## Unblocking Work
**Why this works**: bd preserves design decisions, acceptance criteria, and dependency context. No scrolling conversation history or reconstructing from markdown.
---
## Session Handoff Workflow {#session-handoff}
**Collaborative handoff between sessions using notes field:**
This workflow enables smooth work resumption by updating beads notes when stopping, then reading them when resuming. Works in conjunction with compaction survival - creates continuity even after conversation history is deleted.
### At Session Start (Claude's responsibility)
```
Session Start with in_progress issues:
- [ ] Run bd list --status in_progress
- [ ] For each in_progress issue: bd show <issue-id>
- [ ] Read notes field to understand: COMPLETED, IN PROGRESS, NEXT
- [ ] Report to user with context from notes field
- [ ] Example: "workspace-mcp-server-2 is in_progress. Last session:
completed tidying. No code written yet. Next step: create
markdown_to_docs.py. Should I continue with that?"
- [ ] Wait for user confirmation or direction
```
**Pattern**: Notes field is the "read me first" guide for resuming work.
### At Session End (Claude prompts user)
When wrapping up work on an issue:
```
Session End Handoff:
- [ ] Notice work reaching a stopping point
- [ ] Prompt user: "We just completed X and started Y on <issue-id>.
Should I update the beads notes for next session?"
- [ ] If yes, suggest command:
bd update <issue-id> --notes "COMPLETED: X. IN PROGRESS: Y. NEXT: Z"
- [ ] User reviews and confirms
- [ ] Claude executes the update
- [ ] Notes saved for next session's resumption
```
**Pattern**: Update notes at logical stopping points, not after every keystroke.
### Notes Format (Current State, Not Cumulative)
```
Good handoff note (current state):
COMPLETED: Parsed markdown into structured format
IN PROGRESS: Implementing Docs API insertion
NEXT: Debug batchUpdate call - getting 400 error on formatting
BLOCKER: None
KEY DECISION: Using two-phase approach (insert text, then apply formatting) based on reference implementation
Bad handoff note (not useful):
Updated some stuff. Will continue later.
```
**Rules for handoff notes:**
- Current state only (overwrite previous notes, not append)
- Specific accomplishments (not vague progress)
- Concrete next step (not "continue working")
- Optional: Blockers, key decisions, references
- Written for someone with zero conversation context
### Session Handoff Checklist
For Claude at session end:
```
Session End Checklist:
- [ ] Work reaching logical stopping point
- [ ] Prompt user about updating notes
- [ ] If approved:
- [ ] Craft note with COMPLETED/IN_PROGRESS/NEXT
- [ ] Include blocker if stuck
- [ ] Include key decisions if relevant
- [ ] Suggest bd update command
- [ ] Execute approved update
- [ ] Confirm: "Saved handoff notes for next session"
```
For user (optional, but helpful):
```
User Tips:
- [ ] When stopping work: Let Claude suggest notes update
- [ ] When resuming: Let Claude read notes and report context
- [ ] Avoid: Trying to remember context manually (that's what notes are for!)
- [ ] Trust: Well-written notes will help next session pick up instantly
```
### Example: Real Session Handoff
**Scenario:** Implementing markdown→Docs feature (workspace-mcp-server-2)
**At End of Session 1:**
```bash
bd update workspace-mcp-server-2 --notes "COMPLETED: Set up skeleton with Docs
API connection verified. Markdown parsing logic 80% done (handles *, _ modifiers).
IN PROGRESS: Testing edge cases for nested formatting. NEXT: Implement
batchUpdate call structure for text insertion. REFERENCE: Reference pattern at
docs/markdown-to-docs-reference.md. No blockers, moving well."
```
**At Start of Session 2:**
```bash
bd show workspace-mcp-server-2
# Output includes notes field showing exactly where we left off
# Claude reports: "Markdown→Docs feature is 80% parsed. We were testing
# edge cases and need to implement batchUpdate next. Want to continue?"
```
Session resumes instantly with full context, no history scrolling needed.
---
## Unblocking Work {#unblocking}
**When ready list is empty:**
```
Unblocking Workflow:
- [ ] Run bd blocked --json
- [ ] Show details on blocked issues
- [ ] Run bd blocked --json to see what's stuck
- [ ] Show details on blocked issues: bd show issue-id
- [ ] Identify blocker issues
- [ ] Choose: work on blocker, or reassess dependency
- [ ] If reassess: remove incorrect dependency
- [ ] If work on blocker: close it, check ready again
- [ ] If work on blocker: close blocker, check ready again
- [ ] Blocked issues automatically become ready when blockers close
```
**Pattern**: bd automatically maintains ready state based on dependencies. Closing a blocker makes blocked work ready.
**Example**:
```
Situation: bd ready shows nothing
Actions:
1. bd blocked shows: "api-endpoint blocked by db-schema"
2. Show db-schema: "Create user table schema"
3. Work on db-schema issue
4. Close db-schema when done
5. bd ready now shows: "api-endpoint" (automatically unblocked)
```
---
## Integration with TodoWrite
**Using both tools in one session:**
```
Hybrid Workflow:
- [ ] Check bd for high-level context
- [ ] Choose bd issue to work on
- [ ] Mark bd issue in_progress
- [ ] Create TodoWrite from acceptance criteria
- [ ] Create TodoWrite from acceptance criteria for execution
- [ ] Work through TodoWrite items
- [ ] Update bd design notes as you learn
- [ ] When TodoWrite complete, close bd issue
```
## Common Patterns
**Why hybrid**: bd provides persistent structure, TodoWrite provides visible progress.
### Bug Investigation
---
## Common Workflow Patterns
### Pattern: Systematic Exploration
Research or investigation work:
```
1. Create research issue with question to answer
2. Update design field with findings as you go
3. Create new issues for discoveries
4. Link discoveries with discovered-from
5. Close research issue with conclusion
```
### Pattern: Bug Investigation
```
1. Create bug issue
2. Reproduce: note steps in description
3. Investigate: track hypotheses in design field
4. Fix: implement solution
5. Test: verify acceptance criteria
6. Close with root cause and fix explanation
5. Test: verify in acceptance criteria
6. Close with explanation of root cause and fix
```
### Refactoring with Dependencies
### Pattern: Refactoring with Dependencies
```
1. Create issues for each refactoring step
2. Add blocks dependencies for correct order
3. Work through in dependency order
4. bd ready automatically shows next step
5. Each completion unblocks next work
```
### Spike Investigation
### Pattern: Spike Investigation
```
1. Create spike issue
1. Create spike issue: "Investigate caching options"
2. Time-box exploration
3. Document findings in design field
4. Create follow-up issues with discovered-from
5. Close spike with recommendation
4. Create follow-up issues for chosen approach
5. Link follow-ups with discovered-from
6. Close spike with recommendation
```
---
## Checklist Templates
### Starting Any Work Session
```
- [ ] Check for .beads/ directory
- [ ] If exists: bd ready
- [ ] Report status to user
- [ ] Get user input on what to work on
- [ ] Show issue details
- [ ] Update to in_progress
- [ ] Begin work
```
### Creating Issues During Work
```
- [ ] Notice new work needed
- [ ] Create issue with clear title
- [ ] Add context in description
- [ ] Link with discovered-from to current work
- [ ] Assess blocker vs deferrable
- [ ] Update statuses appropriately
```
### Completing Work
```
- [ ] Implementation done
- [ ] Tests passing
- [ ] Close issue with summary
- [ ] Check bd ready for unblocked work
- [ ] Report completion and next available work
```
### Planning Complex Features
```
- [ ] Create epic for overall goal
- [ ] Break into child tasks
- [ ] Create all child issues
- [ ] Link with parent-child dependencies
- [ ] Add blocks between children if order matters
- [ ] Work through in dependency order
```
---
## Decision Points
**Should I create a bd issue or use TodoWrite?**
→ See [BOUNDARIES.md](BOUNDARIES.md) for decision matrix
**Should I ask user before creating issue?**
→ Ask if scope unclear; create if obvious follow-up work
**Should I mark work as blocked or just note dependency?**
→ Blocked = can't proceed; dependency = need to track relationship
**Should I create epic or just tasks?**
→ Epic if 5+ related tasks; tasks if simpler structure
**Should I update status frequently or just at start/end?**
→ Start and end minimum; during work if significant changes
---
## Troubleshooting Workflows
**"I can't find any ready work"**
1. Run bd blocked
2. Identify what's blocking progress
3. Either work on blockers or create new work
**"I created an issue but it's not showing in ready"**
1. Run bd show on the issue
2. Check dependencies field
3. If blocked, resolve blocker first
4. If incorrectly blocked, remove dependency
**"Work is more complex than expected"**
1. Transition from TodoWrite to bd mid-session
2. Create bd issue with current context
3. Note: "Discovered complexity during implementation"
4. Add dependencies as discovered
5. Continue with bd tracking
**"I closed an issue but work isn't done"**
1. Reopen with bd update status=open
2. Or create new issue linking to closed one
3. Note what's still needed
4. Closed issues can't be reopened in some systems, so create new if needed
**"Too many issues, can't find what matters"**
1. Use bd list with filters (priority, issue_type)
2. Use bd ready to focus on unblocked work
3. Consider closing old issues that no longer matter
4. Use labels for organization