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

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>
2025-12-03 20:19:56 -08:00 · 2025-12-03 20:19:56 -08:00 · 8902a4f4a6
parent a74d0a2f26
commit 8902a4f4a6
8 changed files with 2794 additions and 428 deletions
--- a/.beads/issues.jsonl
+++ b/.beads/issues.jsonl
@ -1,14 +1,23 @@
 {"id":"skills-20s","title":"Compare BOUNDARIES.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:53.585115099-08:00","updated_at":"2025-12-03T20:19:28.442646801-08:00","closed_at":"2025-12-03T20:19:28.442646801-08:00","dependencies":[{"issue_id":"skills-20s","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:53.586442134-08:00","created_by":"daemon"}]}
 {"id":"skills-25l","title":"Create orch skill for multi-model consensus","description":"Build a skill that exposes orch CLI capabilities to agents for querying multiple AI models","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-30T15:43:49.209528963-08:00","updated_at":"2025-11-30T15:47:36.608887453-08:00","closed_at":"2025-11-30T15:47:36.608887453-08:00"}
 {"id":"skills-2xo","title":"Add README.md for web-search skill","description":"web-search skill has SKILL.md and scripts but no README.md. AGENTS.md says README.md is for humans, contains installation instructions, usage examples, prerequisites.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.26066025-08:00","updated_at":"2025-11-30T12:00:25.561281052-08:00","dependencies":[{"issue_id":"skills-2xo","depends_on_id":"skills-vb5","type":"blocks","created_at":"2025-11-30T12:01:30.240439018-08:00","created_by":"daemon"}]}
 {"id":"skills-39g","title":"RFC: .skills manifest pattern for per-repo skill deployment","description":"Document the .skills file pattern where projects declare skills in a manifest, .envrc reads it, and agents can query/edit it.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-30T12:37:50.106992381-08:00","updated_at":"2025-11-30T12:43:04.155161727-08:00","closed_at":"2025-11-30T12:43:04.155161727-08:00"}
 {"id":"skills-3o7","title":"Fix ai-skills.nix missing sha256 hash","description":"modules/ai-skills.nix:16 has empty sha256 placeholder for opencode-skills npm package. Either get actual hash or remove/comment out the incomplete fetchFromNpm approach.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-30T11:58:24.404929863-08:00","updated_at":"2025-11-30T12:12:39.372107348-08:00","closed_at":"2025-11-30T12:12:39.372107348-08:00"}
 {"id":"skills-4yn","title":"Decide on screenshot-latest skill deployment","description":"DEPLOYED.md shows screenshot-latest as 'Not yet deployed - Pending decision'. Low risk skill that finds existing files. Need to decide whether to deploy or archive.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.099790809-08:00","updated_at":"2025-11-30T11:58:33.099790809-08:00"}
 {"id":"skills-5v8","title":"Replace SKILL.md with upstream version","description":"Upstream has 644 lines vs our 122. Missing: self-test questions, notes quality checks, token checkpointing, database selection, field usage table, lifecycle workflow, common patterns, troubleshooting","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-03T20:15:53.025829293-08:00","updated_at":"2025-12-03T20:16:20.470185004-08:00","closed_at":"2025-12-03T20:16:20.470185004-08:00","dependencies":[{"issue_id":"skills-5v8","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:53.027601712-08:00","created_by":"daemon"}]}
 {"id":"skills-7s0","title":"Compare STATIC_DATA.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:55.193704589-08:00","updated_at":"2025-12-03T20:19:29.659256809-08:00","closed_at":"2025-12-03T20:19:29.659256809-08:00","dependencies":[{"issue_id":"skills-7s0","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:55.195160705-08:00","created_by":"daemon"}]}
 {"id":"skills-7sh","title":"Set up bd-issue-tracking Claude Code skill from beads repo","description":"Install the beads Claude Code skill from https://github.com/steveyegge/beads/tree/main/examples/claude-code-skill\n\nThis skill teaches Claude how to effectively use beads for issue tracking across multi-session coding workflows. It provides strategic guidance on when/how to use beads, not just command syntax.\n\nFiles to install to ~/.claude/skills/bd-issue-tracking/:\n- SKILL.md - Core workflow patterns and decision criteria\n- BOUNDARIES.md - When to use beads vs markdown alternatives\n- CLI_REFERENCE.md - Complete command documentation\n- DEPENDENCIES.md - Relationship types and patterns\n- WORKFLOWS.md - Step-by-step procedures\n- ISSUE_CREATION.md - Quality guidelines\n- RESUMABILITY.md - Making work resumable across sessions\n- STATIC_DATA.md - Using beads as reference databases\n\nCan symlink or copy the files. Restart Claude Code after install.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T17:53:43.254007992-08:00","updated_at":"2025-12-03T20:04:53.416579381-08:00","closed_at":"2025-12-03T20:04:53.416579381-08:00"}
 {"id":"skills-8d4","title":"Compare CLI_REFERENCE.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:53.268324087-08:00","updated_at":"2025-12-03T20:17:26.552616779-08:00","closed_at":"2025-12-03T20:17:26.552616779-08:00","dependencies":[{"issue_id":"skills-8d4","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:53.27265681-08:00","created_by":"daemon"}]}
 {"id":"skills-a23","title":"Update main README to list all 9 skills","description":"Main README.md 'Skills Included' section only lists worklog and update-spec-kit. Repo actually has 9 skills: template, worklog, update-spec-kit, screenshot-latest, niri-window-capture, tufte-press, update-opencode, web-research, web-search.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.042397754-08:00","updated_at":"2025-11-30T12:00:18.916270858-08:00","dependencies":[{"issue_id":"skills-a23","depends_on_id":"skills-4yn","type":"blocks","created_at":"2025-11-30T12:01:30.306742184-08:00","created_by":"daemon"}]}
 {"id":"skills-cnc","title":"Add direnv helper for per-repo skill deployment","description":"Create sourceable helper script and documentation for the standard per-repo skill deployment pattern using direnv + nix build.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-30T12:19:20.71056749-08:00","updated_at":"2025-11-30T12:37:47.22638278-08:00","closed_at":"2025-11-30T12:37:47.22638278-08:00"}
 {"id":"skills-czz","title":"Research OpenCode agents for skill integration","description":"DEPLOYMENT.md:218 has TODO to research OpenCode agents. Need to understand how Build/Plan/custom agents work and whether skills need agent-specific handling.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:24.855701141-08:00","updated_at":"2025-11-30T11:58:24.855701141-08:00"}
 {"id":"skills-ebh","title":"Compare bd-issue-tracking skill files with upstream","description":"Fetch upstream beads skill files and compare with our condensed versions to identify differences","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:14:07.886535859-08:00","updated_at":"2025-12-03T20:19:37.579815337-08:00","closed_at":"2025-12-03T20:19:37.579815337-08:00"}
 {"id":"skills-fo3","title":"Compare WORKFLOWS.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.283175561-08:00","updated_at":"2025-12-03T20:19:28.897037199-08:00","closed_at":"2025-12-03T20:19:28.897037199-08:00","dependencies":[{"issue_id":"skills-fo3","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.286009672-08:00","created_by":"daemon"}]}
 {"id":"skills-kmj","title":"Orch skill: document or handle orch not in PATH","description":"Skill docs show 'orch consensus' but orch requires 'uv run' from ~/proj/orch. Either update skill to invoke correctly or document installation requirement.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-01T17:29:48.844997238-08:00","updated_at":"2025-12-01T18:28:11.374048504-08:00","closed_at":"2025-12-01T18:28:11.374048504-08:00"}
 {"id":"skills-lie","title":"Compare DEPENDENCIES.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:53.925914243-08:00","updated_at":"2025-12-03T20:19:28.665641809-08:00","closed_at":"2025-12-03T20:19:28.665641809-08:00","dependencies":[{"issue_id":"skills-lie","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:53.9275694-08:00","created_by":"daemon"}]}
 {"id":"skills-lvg","title":"Compare ISSUE_CREATION.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.609282051-08:00","updated_at":"2025-12-03T20:19:29.134966356-08:00","closed_at":"2025-12-03T20:19:29.134966356-08:00","dependencies":[{"issue_id":"skills-lvg","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.610717055-08:00","created_by":"daemon"}]}
 {"id":"skills-m21","title":"Apply niri-window-capture code review recommendations","description":"CODE-REVIEW-niri-window-capture.md identifies action items: add dependency checks to scripts, improve error handling for niri failures, add screenshot directory validation, implement rate limiting. See High/Medium priority sections.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:24.648846875-08:00","updated_at":"2025-11-30T11:58:24.648846875-08:00"}
 {"id":"skills-pu4","title":"Clean up stale beads.left.jsonl merge artifact","description":"bd doctor flagged multiple JSONL files. beads.left.jsonl is empty merge artifact that should be removed: git rm .beads/beads.left.jsonl","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.292221449-08:00","updated_at":"2025-11-30T12:37:49.916795223-08:00","closed_at":"2025-11-30T12:37:49.916795223-08:00"}
 {"id":"skills-qeh","title":"Add README.md for web-research skill","description":"web-research skill has SKILL.md and scripts but no README.md. AGENTS.md says README.md is for humans, contains installation instructions, usage examples, prerequisites.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.475647113-08:00","updated_at":"2025-11-30T12:00:30.309340468-08:00","dependencies":[{"issue_id":"skills-qeh","depends_on_id":"skills-vb5","type":"blocks","created_at":"2025-11-30T12:01:30.278784381-08:00","created_by":"daemon"}]}
 {"id":"skills-uz4","title":"Compare RESUMABILITY.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.897754095-08:00","updated_at":"2025-12-03T20:19:29.384645842-08:00","closed_at":"2025-12-03T20:19:29.384645842-08:00","dependencies":[{"issue_id":"skills-uz4","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.899671178-08:00","created_by":"daemon"}]}
 {"id":"skills-vb5","title":"Resolve web search design questions","description":"web_search_brainstorm.md has unanswered design questions: single smart skill vs explicit flags, specific sources priority, raw links vs summaries. Need user input to finalize web-search/web-research direction.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.482270742-08:00","updated_at":"2025-11-30T11:58:33.482270742-08:00"}
--- a/skills/bd-issue-tracking/SKILL.md
+++ b/skills/bd-issue-tracking/SKILL.md
@ -1,122 +1,644 @@
 ---
 name: bd-issue-tracking
-description: Guide for effective beads (bd) issue tracking across multi-session coding workflows. Use when working on complex features, bug investigations, or any work spanning multiple sessions. Teaches temporal layering with TodoWrite for single-session tasks and bd for persistent strategic work.
+description: Track complex, multi-session work with dependency graphs using bd (beads) issue tracker. Use when work spans multiple sessions, has complex dependencies, or requires persistent context across compaction cycles. For simple single-session linear tasks, TodoWrite remains appropriate.
 ---
-# bd Issue Tracking Skill
+# bd Issue Tracking
-Guide for using bd (beads) for persistent issue tracking across coding sessions.
+## Overview
-## When to Use
+bd is a graph-based issue tracker for persistent memory across sessions. Use for multi-session work with complex dependencies; use TodoWrite for simple single-session tasks.
-This skill activates when:
+## When to Use bd vs TodoWrite
 - 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
-## 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 |
+**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.
 |------|----------|-------------|
 | **TodoWrite** | Single-session micro-tasks | Ephemeral (conversation only) |
 | **bd** | Multi-session strategic work | Persistent (survives compaction) |
-**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
+**At session start, always check for bd availability and run ready check.**
 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
-## 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
+Session Start:
- Obvious follow-up work identified
+- [ ] Run bd ready --json to see available work
- Technical debt with clear scope
+- [ ] Run bd list --status in_progress --json for active work
-
+- [ ] If in_progress exists: bd show <issue-id> to read notes
-**Ask first** (get user input):
+- [ ] Report context to user: "X items ready: [summary]"
- Knowledge work with fuzzy boundaries
+- [ ] If using global ~/.beads, mention this in report
- Multiple valid approaches exist
+- [ ] If nothing ready: bd blocked --json to check blockers
 - User's intent needs clarification
 ### Status Maintenance
 - `open` → `in_progress` when starting work
 - Update notes field with progress
 - Add dependencies as blockers discovered
 - Close with summary when complete
 ### Discovery Pattern
 When finding new work during implementation:
 ```bash
 # Create and link in one command
 bd create "Found issue" -t bug -p 1 --deps discovered-from:<current-id> --json
 ```
-## Session End Protocol
+**Pattern**: Always check both `bd ready` AND `bd list --status in_progress`. Read notes field first to understand where previous session left off.
-Before ending a session:
+**Report format**:
 - "I can see X items ready to work on: [summary]"
 - "Issue Y is in_progress. Last session: [summary from notes]. Next: [from notes]. Should I continue with that?"
-1. Update notes field with current state:
+This establishes immediate shared context about available and active work without requiring user prompting.
   ```
   COMPLETED: What was finished
   IN PROGRESS: Current state
   NEXT: Concrete next step
   KEY DECISION: Important choices made (with rationale)
   ```
-2. Run `bd sync` to ensure changes are committed
+**For detailed collaborative handoff process, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-handoff)
-## Compaction Survival
+**Note**: bd auto-discovers the database:
 - Uses `.beads/*.db` in current project if exists
 - Falls back to `~/.beads/default.db` otherwise
 - No configuration needed
-After compaction events, conversation history is deleted but bd state persists.
+### When No Work is Ready
-**Recovery checklist:**
+If `bd ready` returns empty but issues exist:
 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
 ## Reference Documentation
 For detailed guidance, see the references/ subdirectory:
 - **BOUNDARIES.md** - Decision criteria: bd vs TodoWrite
 - **CLI_REFERENCE.md** - Complete command documentation
 - **DEPENDENCIES.md** - Dependency types and patterns
 - **WORKFLOWS.md** - Step-by-step procedures with checklists
 - **ISSUE_CREATION.md** - Quality guidelines for creating issues
 - **RESUMABILITY.md** - Making work resumable across sessions
 - **STATIC_DATA.md** - Using bd as reference database
 ## Quick Command Reference
 ```bash
-# Find work
+bd blocked --json
 bd ready --json              # Unblocked issues
 bd blocked --json            # See what's stuck
 # 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
 ```
 Report blockers and suggest next steps.
 ---
 ## Progress Checkpointing
 Update bd notes at these checkpoints (don't wait for session end):
 **Critical triggers:**
 - ⚠️ **Context running low** - User says "running out of context" / "approaching compaction" / "close to token limit"
 - 📊 **Token budget > 70%** - Proactively checkpoint when approaching limits
 - 🎯 **Major milestone reached** - Completed significant piece of work
 - 🚧 **Hit a blocker** - Can't proceed, need to capture what was tried
 - 🔄 **Task transition** - Switching issues or about to close this one
 - ❓ **Before user input** - About to ask decision that might change direction
 **Proactive monitoring during session:**
 - At 70% token usage: "We're at 70% token usage - good time to checkpoint bd notes?"
 - At 85% token usage: "Approaching token limit (85%) - checkpointing current state to bd"
 - At 90% token usage: Automatically checkpoint without asking
 **Current token usage**: Check `<system-warning>Token usage:` messages to monitor proactively.
 **Checkpoint checklist:**
 ```
 Progress Checkpoint:
 - [ ] Update notes with COMPLETED/IN_PROGRESS/NEXT format
 - [ ] Document KEY DECISIONS or BLOCKERS since last update
 - [ ] Mark current status (in_progress/blocked/closed)
 - [ ] If discovered new work: create issues with discovered-from
 - [ ] Verify notes are self-explanatory for post-compaction resume
 ```
 **Most important**: When user says "running out of context" OR when you see >70% token usage - checkpoint immediately, even if mid-task.
 **Test yourself**: "If compaction happened right now, could future-me resume from these notes?"
 ---
 ### Database Selection
 bd automatically selects the appropriate database:
 - **Project-local** (`.beads/` in project): Used for project-specific work
 - **Global fallback** (`~/.beads/`): Used when no project-local database exists
 **Use case for global database**: Cross-project tracking, personal task management, knowledge work that doesn't belong to a specific project.
 **When to use --db flag explicitly:**
 - Accessing a specific database outside current directory
 - Working with multiple databases (e.g., project database + reference database)
 - Example: `bd --db /path/to/reference/terms.db list`
 **Database discovery rules:**
 - bd looks for `.beads/*.db` in current working directory
 - If not found, uses `~/.beads/default.db`
 - Shell cwd can reset between commands - use absolute paths with --db when operating on non-local databases
 **For complete session start workflows, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-start)
 ## Core Operations
 All bd commands support `--json` flag for structured output when needed for programmatic parsing.
 ### Essential Operations
 **Check ready work:**
 ```bash
 bd ready
 bd ready --json              # For structured output
 bd ready --priority 0        # Filter by priority
 bd ready --assignee alice    # Filter by assignee
 ```
 **Create new issue:**
 **IMPORTANT**: Always quote title and description arguments with double quotes, especially when containing spaces or special characters.
 ```bash
 bd create "Fix login bug"
 bd create "Add OAuth" -p 0 -t feature
 bd create "Write tests" -d "Unit tests for auth module" --assignee alice
 bd create "Research caching" --design "Evaluate Redis vs Memcached"
 # Examples with special characters (requires quoting):
 bd create "Fix: auth doesn't handle edge cases" -p 1
 bd create "Refactor auth module" -d "Split auth.go into separate files (handlers, middleware, utils)"
 ```
 **Update issue status:**
 ```bash
 bd update issue-123 --status in_progress
 bd update issue-123 --priority 0
 bd update issue-123 --assignee bob
 bd update issue-123 --design "Decided to use Redis for persistence support"
 ```
 **Close completed work:**
 ```bash
 bd close issue-123
 bd close issue-123 --reason "Implemented in PR #42"
 bd close issue-1 issue-2 issue-3 --reason "Bulk close related work"
 ```
 **Show issue details:**
 ```bash
 bd show issue-123
 bd show issue-123 --json
 ```
 **List issues:**
 ```bash
 bd list
 bd list --status open
 bd list --priority 0
 bd list --type bug
 bd list --assignee alice
 ```
 **For complete CLI reference with all flags and examples, read:** [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md)
 ## Field Usage Reference
 Quick guide for when and how to use each bd field:
 | Field | Purpose | When to Set | Update Frequency |
 |-------|---------|-------------|------------------|
 | **description** | Immutable problem statement | At creation | Never (fixed forever) |
 | **design** | Initial approach, architecture, decisions | During planning | Rarely (only if approach changes) |
 | **acceptance-criteria** | Concrete deliverables checklist (`- [ ]` syntax) | When design is clear | Mark `- [x]` as items complete |
 | **notes** | Session handoff (COMPLETED/IN_PROGRESS/NEXT) | During work | At session end, major milestones |
 | **status** | Workflow state (open→in_progress→closed) | As work progresses | When changing phases |
 | **priority** | Urgency level (0=highest, 3=lowest) | At creation | Adjust if priorities shift |
 **Key pattern**: Notes field is your "read me first" at session start. See [WORKFLOWS.md](references/WORKFLOWS.md#session-handoff) for session handoff details.
 ---
 ## Issue Lifecycle Workflow
 ### 1. Discovery Phase (Proactive Issue Creation)
 **During exploration or implementation, proactively file issues for:**
 - Bugs or problems discovered
 - Potential improvements noticed
 - Follow-up work identified
 - Technical debt encountered
 - Questions requiring research
 **Pattern:**
 ```bash
 # When encountering new work during a task:
 bd create "Found: auth doesn't handle profile permissions"
 bd dep add current-task-id new-issue-id --type discovered-from
 # Continue with original task - issue persists for later
 ```
 **Key benefit**: Capture context immediately instead of losing it when conversation ends.
 ### 2. Execution Phase (Status Maintenance)
 **Mark issues in_progress when starting work:**
 ```bash
 bd update issue-123 --status in_progress
 ```
 **Update throughout work:**
 ```bash
 # Add design notes as implementation progresses
 bd update issue-123 --design "Using JWT with RS256 algorithm"
 # Update acceptance criteria if requirements clarify
 bd update issue-123 --acceptance "- JWT validation works\n- Tests pass\n- Error handling returns 401"
 ```
 **Close when complete:**
 ```bash
 bd close issue-123 --reason "Implemented JWT validation with tests passing"
 ```
 **Important**: Closed issues remain in database - they're not deleted, just marked complete for project history.
 ### 3. Planning Phase (Dependency Graphs)
 For complex multi-step work, structure issues with dependencies before starting:
 **Create parent epic:**
 ```bash
 bd create "Implement user authentication" -t epic -d "OAuth integration with JWT tokens"
 ```
 **Create subtasks:**
 ```bash
 bd create "Set up OAuth credentials" -t task
 bd create "Implement authorization flow" -t task
 bd create "Add token refresh" -t task
 ```
 **Link with dependencies:**
 ```bash
 # parent-child for epic structure
 bd dep add auth-epic auth-setup --type parent-child
 bd dep add auth-epic auth-flow --type parent-child
 # blocks for ordering
 bd dep add auth-setup auth-flow
 ```
 **For detailed dependency patterns and types, read:** [references/DEPENDENCIES.md](references/DEPENDENCIES.md)
 ## Dependency Types Reference
 bd supports four dependency types:
 1. **blocks** - Hard blocker (issue A blocks issue B from starting)
 2. **related** - Soft link (issues are related but not blocking)
 3. **parent-child** - Hierarchical (epic/subtask relationship)
 4. **discovered-from** - Provenance (issue B discovered while working on A)
 **For complete guide on when to use each type with examples and patterns, read:** [references/DEPENDENCIES.md](references/DEPENDENCIES.md)
 ## Integration with TodoWrite
 **Both tools complement each other at different timescales:**
 ### Temporal Layering Pattern
 **TodoWrite** (short-term working memory - this hour):
 - Tactical execution: "Review Section 3", "Expand Q&A answers"
 - Marked completed as you go
 - Present/future tense ("Review", "Expand", "Create")
 - Ephemeral: Disappears when session ends
 **Beads** (long-term episodic memory - this week/month):
 - Strategic objectives: "Continue work on strategic planning document"
 - Key decisions and outcomes in notes field
 - Past tense in notes ("COMPLETED", "Discovered", "Blocked by")
 - Persistent: Survives compaction and session boundaries
 ### The Handoff Pattern
 1. **Session start**: Read bead → Create TodoWrite items for immediate actions
 2. **During work**: Mark TodoWrite items completed as you go
 3. **Reach milestone**: Update bead notes with outcomes + context
 4. **Session end**: TodoWrite disappears, bead survives with enriched notes
 **After compaction**: TodoWrite is gone forever, but bead notes reconstruct what happened.
 ### Example: TodoWrite tracks execution, Beads capture meaning
 **TodoWrite:**
 ```
 [completed] Implement login endpoint
 [in_progress] Add password hashing with bcrypt
 [pending] Create session middleware
 ```
 **Corresponding bead notes:**
 ```
 bd update issue-123 --notes "COMPLETED: Login endpoint with bcrypt password
 hashing (12 rounds). KEY DECISION: Using JWT tokens (not sessions) for stateless
 auth - simplifies horizontal scaling. IN PROGRESS: Session middleware implementation.
 NEXT: Need user input on token expiry time (1hr vs 24hr trade-off)."
 ```
 **Don't duplicate**: TodoWrite tracks execution, Beads captures meaning and context.
 **For patterns on transitioning between tools mid-session, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md#integration-patterns)
 ## Common Patterns
 ### Pattern 1: Knowledge Work Session
 **Scenario**: User asks "Help me write a proposal for expanding the analytics platform"
 **What you see**:
 ```bash
 $ bd ready
 # Returns: bd-42 "Research analytics platform expansion proposal" (in_progress)
 $ bd show bd-42
 Notes: "COMPLETED: Reviewed current stack (Mixpanel, Amplitude)
 IN PROGRESS: Drafting cost-benefit analysis section
 NEXT: Need user input on budget constraints before finalizing recommendations"
 ```
 **What you do**:
 1. Read notes to understand current state
 2. Create TodoWrite for immediate work:
   ```
   - [ ] Draft cost-benefit analysis
   - [ ] Ask user about budget constraints
   - [ ] Finalize recommendations
   ```
 3. Work on tasks, mark TodoWrite items completed
 4. At milestone, update bd notes:
   ```bash
   bd update bd-42 --notes "COMPLETED: Cost-benefit analysis drafted.
   KEY DECISION: User confirmed $50k budget cap - ruled out enterprise options.
   IN PROGRESS: Finalizing recommendations (Posthog + custom ETL).
   NEXT: Get user review of draft before closing issue."
   ```
 **Outcome**: TodoWrite disappears at session end, but bd notes preserve context for next session.
 ### Pattern 2: Side Quest Handling
 During main task, discover a problem:
 1. Create issue: `bd create "Found: inventory system needs refactoring"`
 2. Link using discovered-from: `bd dep add main-task new-issue --type discovered-from`
 3. Assess: blocker or can defer?
 4. If blocker: `bd update main-task --status blocked`, work on new issue
 5. If deferrable: note in issue, continue main task
 ### Pattern 3: Multi-Session Project Resume
 Starting work after time away:
 1. Run `bd ready` to see available work
 2. Run `bd blocked` to understand what's stuck
 3. Run `bd list --status closed --limit 10` to see recent completions
 4. Run `bd show issue-id` on issue to work on
 5. Update status and begin work
 **For complete workflow walkthroughs with checklists, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md)
 ## Issue Creation
 **Quick guidelines:**
 - Ask user first for knowledge work with fuzzy boundaries
 - Create directly for clear bugs, technical debt, or discovered work
 - Use clear titles, sufficient context in descriptions
 - Design field: HOW to build (can change during implementation)
 - Acceptance criteria: WHAT success looks like (should remain stable)
 ### Issue Creation Checklist
 Copy when creating new issues:
 ```
 Creating Issue:
 - [ ] Title: Clear, specific, action-oriented
 - [ ] Description: Problem statement (WHY this matters) - immutable
 - [ ] Design: HOW to build (can change during work)
 - [ ] Acceptance: WHAT success looks like (stays stable)
 - [ ] Priority: 0=critical, 1=high, 2=normal, 3=low
 - [ ] Type: bug/feature/task/epic/chore
 ```
 **Self-check for acceptance criteria:**
 ❓ "If I changed the implementation approach, would these criteria still apply?"
 - → **Yes** = Good criteria (outcome-focused)
 - → **No** = Move to design field (implementation-focused)
 **Example:**
 - ✅ Acceptance: "User tokens persist across sessions and refresh automatically"
 - ❌ Wrong: "Use JWT tokens with 1-hour expiry" (that's design, not acceptance)
 **For detailed guidance on when to ask vs create, issue quality, resumability patterns, and design vs acceptance criteria, read:** [references/ISSUE_CREATION.md](references/ISSUE_CREATION.md)
 ## Alternative Use Cases
 bd is primarily for work tracking, but can also serve as queryable database for static reference data (glossaries, terminology) with adaptations.
 **For guidance on using bd for reference databases and static data, read:** [references/STATIC_DATA.md](references/STATIC_DATA.md)
 ## Statistics and Monitoring
 **Check project health:**
 ```bash
 bd stats
 bd stats --json
 ```
 Returns: total issues, open, in_progress, closed, blocked, ready, avg lead time
 **Find blocked work:**
 ```bash
 bd blocked
 bd blocked --json
 ```
 Use stats to:
 - Report progress to user
 - Identify bottlenecks
 - Understand project velocity
 ## Advanced Features
 ### Issue Types
 ```bash
 bd create "Title" -t task        # Standard work item (default)
 bd create "Title" -t bug         # Defect or problem
 bd create "Title" -t feature     # New functionality
 bd create "Title" -t epic        # Large work with subtasks
 bd create "Title" -t chore       # Maintenance or cleanup
 ```
 ### Priority Levels
 ```bash
 bd create "Title" -p 0    # Highest priority (critical)
 bd create "Title" -p 1    # High priority
 bd create "Title" -p 2    # Normal priority (default)
 bd create "Title" -p 3    # Low priority
 ```
 ### Bulk Operations
 ```bash
 # Close multiple issues at once
 bd close issue-1 issue-2 issue-3 --reason "Completed in sprint 5"
 # Create multiple issues from markdown file
 bd create --file issues.md
 ```
 ### Dependency Visualization
 ```bash
 # Show full dependency tree for an issue
 bd dep tree issue-123
 # Check for circular dependencies
 bd dep cycles
 ```
 ### Built-in Help
 ```bash
 # Quick start guide (comprehensive built-in reference)
 bd quickstart
 # Command-specific help
 bd create --help
 bd dep --help
 ```
 ## JSON Output
 All bd commands support `--json` flag for structured output:
 ```bash
 bd ready --json
 bd show issue-123 --json
 bd list --status open --json
 bd stats --json
 ```
 Use JSON output when you need to parse results programmatically or extract specific fields.
 ## Troubleshooting
 **If bd command not found:**
 - Check installation: `bd version`
 - Verify PATH includes bd binary location
 **If issues seem lost:**
 - Use `bd list` to see all issues
 - Filter by status: `bd list --status closed`
 - Closed issues remain in database permanently
 **If bd show can't find issue by name:**
 - `bd show` requires issue IDs, not issue titles
 - Workaround: `bd list | grep -i "search term"` to find ID first
 - Then: `bd show issue-id` with the discovered ID
 - For glossaries/reference databases where names matter more than IDs, consider using markdown format alongside the database
 **If dependencies seem wrong:**
 - Use `bd show issue-id` to see full dependency tree
 - Use `bd dep tree issue-id` for visualization
 - Dependencies are directional: `bd dep add from-id to-id` means from-id blocks to-id
 - See [references/DEPENDENCIES.md](references/DEPENDENCIES.md#common-mistakes)
 **If database seems out of sync:**
 - bd auto-syncs JSONL after each operation (5s debounce)
 - bd auto-imports JSONL when newer than DB (after git pull)
 - Manual operations: `bd export`, `bd import`
 ## Reference Files
 Detailed information organized by topic:
 | Reference | Read When |
 |-----------|-----------|
 | [references/BOUNDARIES.md](references/BOUNDARIES.md) | Need detailed decision criteria for bd vs TodoWrite, or integration patterns |
 | [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md) | Need complete command reference, flag details, or examples |
 | [references/WORKFLOWS.md](references/WORKFLOWS.md) | Need step-by-step workflows with checklists for common scenarios |
 | [references/DEPENDENCIES.md](references/DEPENDENCIES.md) | Need deep understanding of dependency types or relationship patterns |
 | [references/ISSUE_CREATION.md](references/ISSUE_CREATION.md) | Need guidance on when to ask vs create issues, issue quality, or design vs acceptance criteria |
 | [references/STATIC_DATA.md](references/STATIC_DATA.md) | Want to use bd for reference databases, glossaries, or static data instead of work tracking |
--- a/skills/bd-issue-tracking/references/BOUNDARIES.md
+++ b/skills/bd-issue-tracking/references/BOUNDARIES.md
@ -1,6 +1,24 @@
 # Boundaries: When to Use bd vs TodoWrite
-Decision criteria for choosing between bd issue tracking and TodoWrite.
+This reference provides detailed decision criteria for choosing between bd issue tracking and TodoWrite for task management.
 ## Contents
 - [The Core Question](#the-core-question)
 - [Decision Matrix](#decision-matrix)
  - [Use bd for](#use-bd-for): Multi-Session Work, Complex Dependencies, Knowledge Work, Side Quests, Project Memory
  - [Use TodoWrite for](#use-todowrite-for): Single-Session Tasks, Linear Execution, Immediate Context, Simple Tracking
 - [Detailed Comparison](#detailed-comparison)
 - [Integration Patterns](#integration-patterns)
  - Pattern 1: bd as Strategic, TodoWrite as Tactical
  - Pattern 2: TodoWrite as Working Copy of bd
  - Pattern 3: Transition Mid-Session
 - [Real-World Examples](#real-world-examples)
  - Strategic Document Development, Simple Feature Implementation, Bug Investigation, Refactoring with Dependencies
 - [Common Mistakes](#common-mistakes)
  - Using TodoWrite for multi-session work, using bd for simple tasks, not transitioning when complexity emerges, creating too many bd issues, never using bd
 - [The Transition Point](#the-transition-point)
 - [Summary Heuristics](#summary-heuristics)
 ## The Core Question
@ -9,74 +27,443 @@ Decision criteria for choosing between bd issue tracking and TodoWrite.
 - If bd would help you resume → **use bd**
 - If markdown skim would suffice → **TodoWrite is fine**
 This heuristic captures the essential difference: bd provides structured context that persists across long gaps, while TodoWrite excels at immediate session tracking.
 ## Decision Matrix
 ### Use bd for:
-| Scenario | Why |
+#### Multi-Session Work
-|----------|-----|
+Work spanning multiple compaction cycles or days where context needs to persist.
-| **Multi-session work** | Issues capture context that survives compaction |
+
-| **Complex dependencies** | Dependency graph shows blockers, `bd ready` surfaces work |
+**Examples:**
-| **Knowledge work** | Design notes capture evolving understanding |
+- Strategic document development requiring research across multiple sessions
-| **Side quests** | `discovered-from` preserves context for both tracks |
+- Feature implementation split across several coding sessions
-| **Project memory** | Git-backed database persists indefinitely |
+- 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
-|----------|-----|
+Work that completes within current conversation.
-| **Single-session tasks** | Simple checklist for linear execution |
+
-| **Linear execution** | Steps are predetermined and sequential |
+**Examples:**
-| **Immediate context** | All information already in conversation |
+- Implementing a single function based on clear spec
-| **Simple tracking** | Just need visible progress for user |
+- 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 |
+| **Persistence** | Git-backed, survives compaction | Session-only, lost after conversation |
-| **Dependencies** | Graph-based, automatic ready detection | Manual |
+| **Dependencies** | Graph-based, automatic ready detection | Manual, no automatic tracking |
-| **Visibility** | Background structure | Visible in conversation |
+| **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
+TodoWrite (for JWT validation):
-2. Create TodoWrite from acceptance criteria
+- [ ] Install JWT library
-3. Update bd as TodoWrite items complete
+- [ ] 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
+### Mistake 1: Using TodoWrite for Multi-Session Work
-2. **bd for simple linear tasks** - Overhead not justified
+
-3. **Not transitioning when complexity emerges** - Keep TodoWrite despite poor fit
+**What happens**:
-4. **Creating too many bd issues** - Reserve bd for work needing persistence
+- 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 |
+Quick decision guides:
-|--------|-----------|-----|
+
-| **Time horizon** | Same session | Multiple sessions |
+**Time horizon:**
-| **Dependencies** | Linear steps | Blockers/prerequisites |
+- Same session → TodoWrite
-| **Scope** | Well-defined | Exploratory |
+- Multiple sessions → bd
-| **Resume difficulty** | Easy | Need structured history |
+
 **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.
--- a/skills/bd-issue-tracking/references/CLI_REFERENCE.md
+++ b/skills/bd-issue-tracking/references/CLI_REFERENCE.md
@ -1,15 +1,44 @@
 # CLI Command Reference
-Complete bd command-line interface documentation.
+**For:** AI agents and developers using bd command-line interface
 **Version:** 0.21.0+
 ## Quick Navigation
 - [Basic Operations](#basic-operations)
 - [Issue Management](#issue-management)
 - [Dependencies & Labels](#dependencies--labels)
 - [Filtering & Search](#filtering--search)
 - [Advanced Operations](#advanced-operations)
 - [Database Management](#database-management)
 ## Basic Operations
 ### Check Status
 ```bash
-bd info --json                    # Database path, daemon status
+# Check database path and daemon status
-bd ready --json                   # Find ready work (no blockers)
+bd info --json
-bd stale --days 30 --json         # Find stale issues
+
 # 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
+# Examples with special characters (all require quoting):
-bd create "Found bug" -t bug -p 1 --deps discovered-from:<parent-id> --json
+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
+# Update one or more issues
-bd update <id> --priority 1 --json
+bd update <id> [<id>...] --status in_progress --json
-bd update <id> --notes "COMPLETED: X. IN PROGRESS: Y. NEXT: Z"
+bd update <id> [<id>...] --priority 1 --json
-bd update <id> --design "Implementation approach notes"
+
 # 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
+# Show dependency tree
-bd dep tree <id>                  # 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
+# Link discovered work (old way - two commands)
-bd dep add <id> <parent> --type discovered-from         # Provenance link
+bd dep add <discovered-id> <parent-id> --type discovered-from
-bd dep add <child> <parent> --type parent-child         # Hierarchy
+
-bd dep add <id1> <id2> --type related                   # Soft link
+# 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
+# Label management (supports multiple IDs)
-bd label remove <id> <label> --json
+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
+### Basic Filters
 # By status, priority, type
 bd list --status open --priority 1 --json
 bd list --type bug --json
-# 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
+# Pattern matching (case-insensitive substring)
-bd list --created-after 2024-01-01 --json
+bd list --title-contains "auth" --json                  # Search in title
-bd list --updated-after 2024-06-01 --json
+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
+Global flags work with any bd command and must appear **before** the subcommand.
 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
 ```
-## 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
+# Explicitly enable sandbox mode
-# Does: export → commit → pull → import → push
+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
+- `task` - Work item (tests, docs, refactoring)
- `epic` - Large feature with children
+- `epic` - Large feature composed of multiple issues (supports hierarchical children)
- `chore` - Maintenance work
+- `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)
+- `2` - Medium (nice-to-have features, minor bugs)
- `3` - Low (polish)
+- `3` - Low (polish, optimization)
 - `4` - Backlog (future ideas)
 ## Dependency Types
- `blocks` - Hard dependency (affects `bd ready`)
+- `blocks` - Hard dependency (issue X blocks issue Y)
- `related` - Soft link (informational only)
+- `related` - Soft relationship (issues are connected)
- `parent-child` - Epic/subtask hierarchy
+- `parent-child` - Epic/subtask relationship
- `discovered-from` - Track provenance
+- `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
+# 1. Find available work
-bd update bd-42 --status in_progress --json   # Claim
+bd ready --json
-# ... work ...
+
-bd close bd-42 --reason "Done" --json         # Complete
+# 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
--- a/skills/bd-issue-tracking/references/DEPENDENCIES.md
+++ b/skills/bd-issue-tracking/references/DEPENDENCIES.md
@ -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 |
+| **blocks** | Hard blocker | Yes - blocked issues excluded | Sequential work, prerequisites |
-| **related** | Soft link | No | Context, related work |
+| **related** | Soft link | No - just informational | Context, related work |
-| **parent-child** | Hierarchy | No | Epics and subtasks |
+| **parent-child** | Hierarchy | No - structural only | Epics and subtasks |
-| **discovered-from** | Provenance | No | Side quests, research findings |
+| **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
+Use `blocks` when work literally cannot proceed:
- **Sequential steps**: Migration step 1 before step 2
+
- **Build order**: Foundation before building on top
+- **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")
+Don't use `blocks` for:
 - Parallel work
 - Information links
-### 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
+bd dep add prerequisite-issue blocked-issue
-# Direction: from_id blocks to_id
+# 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
+Use `related` for context and discoverability:
 - Shared context
 - Alternative approaches
 - Complementary features
-### 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
+Use `parent-child` for breaking down large work:
 - Hierarchical organization
 - Progress tracking
 - Work breakdown structure
-### 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
+bd dep add child-task-id parent-epic-id --type parent-child
 # Child depends on parent
 ```
 **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
+Use `discovered-from` to preserve discovery context:
- Research findings
+
- Bug found during feature work
+- **Side quests**: Found new work during implementation
- Follow-up work
+- **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
+### Mistake 1: Using blocks for Preferences
-2. **Using discovered-from for planning** - Use parent-child instead
+
-3. **Not using dependencies** - Add structure with dependencies
+**Wrong**:
-4. **Over-using blocks** - Allow parallel work where possible
+```
-5. **Wrong direction** - "from_id blocks to_id"
+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.
--- a/skills/bd-issue-tracking/references/ISSUE_CREATION.md
+++ b/skills/bd-issue-tracking/references/ISSUE_CREATION.md
@ -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
+**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.
 - **Obvious follow-up work** identified
 - **Technical debt** with clear scope
 - **Dependency or blocker** found
-### Ask first when:
+## Issue Quality {#quality}
- Knowledge work with **fuzzy boundaries**
+Use clear, specific titles and include sufficient context in descriptions to resume work later.
 - **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
 ### Field Usage
-**Title**: Clear, specific, action-oriented
+**Use --design flag for:**
- Good: "Fix: auth token expires before refresh"
+- Implementation approach decisions
- Bad: "Fix bug"
+- Architecture notes
 **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
 - Trade-offs considered
 - Can change during implementation
-**Acceptance criteria** (--acceptance): Definition of done
+**Use --acceptance flag for:**
- Outcomes, not implementation steps
+- Definition of done
- Should remain stable across sessions
+- Testing requirements
- Each criterion should be verifiable
+- Success metrics
-**Notes field**: Session handoffs, implementation details
+## Making Issues Resumable (Complex Technical Work) {#resumable}
 - COMPLETED/IN_PROGRESS/NEXT format
 - Evolves over time
-## 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:
-```
+```markdown
-"Use two-phase batchUpdate approach: insert text first, then apply formatting"
+bd update issue-9 --notes "IMPLEMENTATION GUIDE:
-"Parse with regex to find markers"
+WORKING CODE: service.about().get(fields='importFormats')
-"Use JWT tokens with 1-hour expiry"
+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.
-```
+**For detailed patterns and examples, read:** [RESUMABILITY.md](RESUMABILITY.md)
-"Bold and italic formatting renders correctly"
+
-"User tokens persist across sessions"
+## Design vs Acceptance Criteria (Critical Distinction) {#design-vs-acceptance}
-"Returns doc_id and webViewLink to caller"
+
-```
+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
+### The pitfall
 - Acceptance criteria should remain stable
 - Criteria should be **outcome-focused** not **step-focused**
 - Each criterion should be **verifiable** (yes/no)
-### 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
+- [ ] Apply formatting in second batchUpdate 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
 ```
 ## Quick Reference
 **Creating good issues:**
 1. **Title**: Clear, specific, action-oriented
-2. **Description**: Problem statement, context
+2. **Description**: Problem statement, context, why it matters
-3. **Design**: Approach, trade-offs (can change)
+3. **Design**: Approach, architecture, trade-offs (can change)
-4. **Acceptance**: Outcomes (should be stable)
+4. **Acceptance**: Outcomes, success criteria (should be stable)
-5. **Notes**: Implementation details, session handoffs
+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"
--- a/skills/bd-issue-tracking/references/RESUMABILITY.md
+++ b/skills/bd-issue-tracking/references/RESUMABILITY.md
@ -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
+## Real Example: Before vs After
 ### Not Resumable
 ### ❌ 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:
+Acceptance Criteria:
- Query returns all formats including text/markdown
+- User queries workspace://capabilities/drive/import-formats
- Output is readable markdown
+- Response shows all 49 formats including text/markdown
- Queries live API
+- 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.
+**Problem:** Locks implementation. Should be in Design/Notes, not Acceptance.
 ### Raw JSON Dumps
 ### ❌ Raw JSON Dumps
 ```markdown
 API RESPONSE:
 {giant unformatted JSON blob spanning 100 lines}
 ```
-API RESPONSE: {giant unformatted blob}
+**Problem:** Hard to read. Extract relevant parts, show structure.
 ```
 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:**
+**During work (update notes):**
- Got API query working? Add to 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.
--- a/skills/bd-issue-tracking/references/WORKFLOWS.md
+++ b/skills/bd-issue-tracking/references/WORKFLOWS.md
@ -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:
+After Compaction:
- [ ] Run bd list --status in_progress
+- [ ] Run bd list --status in_progress to see active work
- [ ] Run bd show <id> for each in_progress issue
+- [ ] Run bd show <issue-id> for each in_progress issue
- [ ] Read notes field: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS
+- [ ] Read notes field to understand: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS
- [ ] Check dependencies: bd dep tree <id>
+- [ ] Check dependencies: bd dep tree <issue-id> for context
- [ ] Reconstruct context from issue data
+- [ ] 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.
+bd update issue-42 --notes "COMPLETED: User authentication - added JWT token
-IN PROGRESS: Password reset flow. Email service integration working.
+generation with 1hr expiry, implemented refresh token endpoint using rotating
-NEXT: Add rate limiting to reset endpoint.
+tokens pattern. IN PROGRESS: Password reset flow. Email service integration
-KEY DECISION: Using bcrypt with 12 rounds per OWASP recommendations.
+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
+- [ ] Create issue with bd create "Issue title"
- [ ] Add discovered-from dependency
+- [ ] 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
+- [ ] Complete: Close with summary of what was done
- [ ] After: Check bd ready for unblocked work
+- [ ] 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
+- [ ] Create each child task
- [ ] Add blocks dependencies between children if order matters
+- [ ] Add parent-child dependencies from epic to each child
- [ ] Use bd ready to work through tasks
+- [ ] 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
+- [ ] Add discovered-from dependency linking to main work
- [ ] Assess: blocker or deferrable?
+- [ ] Assess: blocker or can defer?
- [ ] If blocker: mark main work blocked, switch
+- [ ] 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
+**Example**: During feature implementation, discover architectural issue
 ### At Session Start
 ```
- [ ] Run bd list --status in_progress
+Main task: Adding user profiles
- [ ] For each: bd show <id>
+
- [ ] Read notes field for context
+Discovery: Notice auth system should use role-based access
- [ ] Report to user with context
+
- [ ] Wait for confirmation
+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
+---
-```
+## Multi-Session Resume {#resume}
 - [ ] 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
+**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
+- [ ] Run bd blocked --json to see what's stuck
- [ ] Show details on blocked issues
+- [ ] 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
+5. Test: verify in acceptance criteria
-6. Close with root cause and fix explanation
+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
+4. Create follow-up issues for chosen approach
-5. Close spike with recommendation
+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