From 257ed9bdae33388820e09067dff2111140af205b Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Thu, 25 Dec 2025 11:55:51 -0800 Subject: [PATCH] fix: Restore skill files accidentally deleted by bd sync (GH#738) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Files from PR #722 were inadvertently removed by a bd sync commit. Restoring: README.md, MOLECULES.md, PATTERNS.md, TROUBLESHOOTING.md, INTEGRATION_PATTERNS.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- skills/beads/README.md | 109 ++++ .../beads/references/INTEGRATION_PATTERNS.md | 407 +++++++++++++++ skills/beads/references/MOLECULES.md | 354 +++++++++++++ skills/beads/references/PATTERNS.md | 341 ++++++++++++ skills/beads/references/TROUBLESHOOTING.md | 489 ++++++++++++++++++ 5 files changed, 1700 insertions(+) create mode 100644 skills/beads/README.md create mode 100644 skills/beads/references/INTEGRATION_PATTERNS.md create mode 100644 skills/beads/references/MOLECULES.md create mode 100644 skills/beads/references/PATTERNS.md create mode 100644 skills/beads/references/TROUBLESHOOTING.md diff --git a/skills/beads/README.md b/skills/beads/README.md new file mode 100644 index 00000000..25a68484 --- /dev/null +++ b/skills/beads/README.md @@ -0,0 +1,109 @@ +# Beads Skill for Claude Code + +A comprehensive skill for using [beads](https://github.com/steveyegge/beads) (bd) issue tracking with Claude Code. + +## What This Skill Does + +This skill teaches Claude Code how to use bd effectively for: +- **Multi-session work tracking** - Persistent memory across conversation compactions +- **Dependency management** - Graph-based issue relationships +- **Session handoff** - Writing notes that survive context resets +- **Molecules and wisps** (v0.34.0+) - Reusable work templates and ephemeral workflows + +## Installation + +Copy the `beads/` directory to your Claude Code skills location: + +```bash +# Global installation +cp -r beads ~/.claude/skills/ + +# Or project-local +cp -r beads .claude/skills/ +``` + +## When Claude Uses This Skill + +The skill activates when conversations involve: +- "multi-session", "complex dependencies", "resume after weeks" +- "project memory", "persistent context", "side quest tracking" +- Work that spans multiple days or compaction cycles +- Tasks too complex for simple TodoWrite lists + +## File Structure + +``` +beads/ +├── SKILL.md # Main skill file (Claude reads this first) +├── README.md # This file (for humans) +└── references/ # Detailed documentation (loaded on demand) + ├── BOUNDARIES.md # When to use bd vs TodoWrite + ├── CLI_BOOTSTRAP_ADMIN.md # CLI command reference + ├── DEPENDENCIES.md # Dependency semantics (A blocks B vs B blocks A) + ├── INTEGRATION_PATTERNS.md # TodoWrite and other tool integration + ├── ISSUE_CREATION.md # When and how to create issues + ├── MOLECULES.md # Protos, mols, wisps (v0.34.0+) + ├── PATTERNS.md # Common usage patterns + ├── RESUMABILITY.md # Writing notes for post-compaction recovery + ├── STATIC_DATA.md # Using bd for reference databases + ├── TROUBLESHOOTING.md # Common issues and fixes + └── WORKFLOWS.md # Step-by-step workflow guides +``` + +## Key Concepts + +### bd vs TodoWrite + +| Use bd when... | Use TodoWrite when... | +|----------------|----------------------| +| Work spans multiple sessions | Single-session tasks | +| Complex dependencies exist | Linear step-by-step work | +| Need to resume after weeks | Just need a quick checklist | +| Knowledge work with fuzzy boundaries | Clear, immediate tasks | + +### The Dependency Direction Trap + +`bd dep add A B` means **"A depends on B"** (B must complete before A can start). + +```bash +# Want: "Setup must complete before Implementation" +bd dep add implementation setup # ✓ CORRECT +# NOT: bd dep add setup implementation # ✗ WRONG +``` + +### Surviving Compaction + +When Claude's context gets compacted, conversation history is lost but bd state survives. Write notes as if explaining to a future Claude with zero context: + +```bash +bd update issue-123 --notes "COMPLETED: JWT auth with RS256 +KEY DECISION: RS256 over HS256 for key rotation +IN PROGRESS: Password reset flow +NEXT: Implement rate limiting" +``` + +## Requirements + +- [bd CLI](https://github.com/steveyegge/beads) installed (`brew install steveyegge/beads/bd`) +- A git repository (bd requires git for sync) +- Initialized database (`bd init` in project root) + +## Version Compatibility + +- **v0.34.0+**: Full support including molecules, wisps, and cross-project dependencies +- **v0.15.0+**: Core functionality (dependencies, notes, status tracking) +- **Earlier versions**: Basic functionality but some features may be missing + +## Contributing + +This skill is maintained at [github.com/steveyegge/beads](https://github.com/steveyegge/beads) in the `skills/beads/` directory. + +Issues and PRs welcome for: +- Documentation improvements +- New workflow patterns +- Bug fixes in examples +- Additional troubleshooting scenarios + +## License + +MIT (same as beads) diff --git a/skills/beads/references/INTEGRATION_PATTERNS.md b/skills/beads/references/INTEGRATION_PATTERNS.md new file mode 100644 index 00000000..366493f0 --- /dev/null +++ b/skills/beads/references/INTEGRATION_PATTERNS.md @@ -0,0 +1,407 @@ +# Integration Patterns with Other Skills + +How bd-issue-tracking integrates with TodoWrite, writing-plans, and other skills for optimal workflow. + +## Contents + +- [TodoWrite Integration](#todowrite-integration) - Temporal layering pattern +- [writing-plans Integration](#writing-plans-integration) - Detailed implementation plans +- [Cross-Skill Workflows](#cross-skill-workflows) - Using multiple skills together +- [Decision Framework](#decision-framework) - When to use which tool + +--- + +## TodoWrite Integration + +**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 + +**Key insight**: TodoWrite = working copy for the current hour. Beads = project journal for the current month. + +### 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 (ephemeral execution view):** +``` +[completed] Implement login endpoint +[in_progress] Add password hashing with bcrypt +[pending] Create session middleware +``` + +**Corresponding bead notes (persistent context):** +```bash +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)." +``` + +**What's different**: +- TodoWrite: Task names (what to do) +- Beads: Outcomes and decisions (what was learned, why it matters) + +**Don't duplicate**: TodoWrite tracks execution, Beads captures meaning and context. + +### When to Update Each Tool + +**Update TodoWrite** (frequently): +- Mark task completed as you finish each one +- Add new tasks as you break down work +- Update in_progress when switching tasks + +**Update Beads** (at milestones): +- Completed a significant piece of work +- Made a key decision that needs documentation +- Hit a blocker that pauses progress +- About to ask user for input +- Session token usage > 70% +- End of session + +**Pattern**: TodoWrite changes every few minutes. Beads updates every hour or at natural breakpoints. + +### Full Workflow Example + +**Scenario**: Implement OAuth authentication (multi-session work) + +**Session 1 - Planning**: +```bash +# Create bd issue +bd create "Implement OAuth authentication" -t feature -p 0 --design " +JWT tokens with refresh rotation. +See BOUNDARIES.md for bd vs TodoWrite decision. +" + +# Mark in_progress +bd update oauth-1 --status in_progress + +# Create TodoWrite for today's work +TodoWrite: +- [ ] Research OAuth 2.0 refresh token flow +- [ ] Design token schema +- [ ] Set up test environment +``` + +**End of Session 1**: +```bash +# Update bd with outcomes +bd update oauth-1 --notes "COMPLETED: Researched OAuth2 refresh flow. Decided on 7-day refresh tokens. +KEY DECISION: RS256 over HS256 (enables key rotation per security review). +IN PROGRESS: Need to set up test OAuth provider. +NEXT: Configure test provider, then implement token endpoint." + +# TodoWrite disappears when session ends +``` + +**Session 2 - Implementation** (after compaction): +```bash +# Read bd to reconstruct context +bd show oauth-1 +# See: COMPLETED research, NEXT is configure test provider + +# Create fresh TodoWrite from NEXT +TodoWrite: +- [ ] Configure test OAuth provider +- [ ] Implement token endpoint +- [ ] Add basic tests + +# Work proceeds... + +# Update bd at milestone +bd update oauth-1 --notes "COMPLETED: Test provider configured, token endpoint implemented. +TESTS: 5 passing (token generation, validation, expiry). +IN PROGRESS: Adding refresh token rotation. +NEXT: Implement rotation, add rate limiting, security review." +``` + +**For complete decision criteria and boundaries, see:** [BOUNDARIES.md](BOUNDARIES.md) + +--- + +## writing-plans Integration + +**For complex multi-step features**, the design field in bd issues can link to detailed implementation plans that break work into bite-sized RED-GREEN-REFACTOR steps. + +### When to Create Detailed Plans + +**Use detailed plans for:** +- Complex features with multiple components +- Multi-session work requiring systematic breakdown +- Features where TDD discipline adds value (core logic, critical paths) +- Work that benefits from explicit task sequencing + +**Skip detailed plans for:** +- Simple features (single function, straightforward logic) +- Exploratory work (API testing, pattern discovery) +- Infrastructure setup (configuration, wiring) + +**The test:** If you can implement it in one session without a checklist, skip the detailed plan. + +### Using the writing-plans Skill + +When design field needs detailed breakdown, reference the **writing-plans** skill: + +**Pattern:** +```bash +# Create issue with high-level design +bd create "Implement OAuth token refresh" --design " +Add JWT refresh token flow with rotation. +See docs/plans/2025-10-23-oauth-refresh-design.md for detailed plan. +" + +# Then use writing-plans skill to create detailed plan +# The skill creates: docs/plans/YYYY-MM-DD-.md +``` + +**Detailed plan structure** (from writing-plans): +- Bite-sized tasks (2-5 minutes each) +- Explicit RED-GREEN-REFACTOR steps per task +- Exact file paths and complete code +- Verification commands with expected output +- Frequent commit points + +**Example task from detailed plan:** +```markdown +### Task 1: Token Refresh Endpoint + +**Files:** +- Create: `src/auth/refresh.py` +- Test: `tests/auth/test_refresh.py` + +**Step 1: Write failing test** +```python +def test_refresh_token_returns_new_access_token(): + refresh_token = create_valid_refresh_token() + response = refresh_endpoint(refresh_token) + assert response.status == 200 + assert response.access_token is not None +``` + +**Step 2: Run test to verify it fails** +Run: `pytest tests/auth/test_refresh.py::test_refresh_token_returns_new_access_token -v` +Expected: FAIL with "refresh_endpoint not defined" + +**Step 3: Implement minimal code** +[... exact implementation ...] + +**Step 4: Verify test passes** +[... verification ...] + +**Step 5: Commit** +```bash +git add tests/auth/test_refresh.py src/auth/refresh.py +git commit -m "feat: add token refresh endpoint" +``` +``` + +### Integration with bd Workflow + +**Three-layer structure**: +1. **bd issue**: Strategic objective + high-level design +2. **Detailed plan** (writing-plans): Step-by-step execution guide +3. **TodoWrite**: Current task within the plan + +**During planning phase:** +1. Create bd issue with high-level design +2. If complex: Use writing-plans skill to create detailed plan +3. Link plan in design field: `See docs/plans/YYYY-MM-DD-.md` + +**During execution phase:** +1. Open detailed plan (if exists) +2. Use TodoWrite to track current task within plan +3. Update bd notes at milestones, not per-task +4. Close bd issue when all plan tasks complete + +**Don't duplicate:** Detailed plan = execution steps. BD notes = outcomes and decisions. + +**Example bd notes after using detailed plan:** +```bash +bd update oauth-5 --notes "COMPLETED: Token refresh endpoint (5 tasks from plan: endpoint + rotation + tests) +KEY DECISION: 7-day refresh tokens (vs 30-day) - reduces risk of token theft +TESTS: All 12 tests passing (auth, rotation, expiry, error handling)" +``` + +### When NOT to Use Detailed Plans + +**Red flags:** +- Feature is simple enough to implement in one pass +- Work is exploratory (discovering patterns, testing APIs) +- Infrastructure work (OAuth setup, MCP configuration) +- Would spend more time planning than implementing + +**Rule of thumb:** Use detailed plans when systematic breakdown prevents mistakes, not for ceremony. + +**Pattern summary**: +- **Simple feature**: bd issue only +- **Complex feature**: bd issue + TodoWrite +- **Very complex feature**: bd issue + writing-plans + TodoWrite + +--- + +## Cross-Skill Workflows + +### Pattern: Research Document with Strategic Planning + +**Scenario**: User asks "Help me write a strategic planning document for Q4" + +**Tools used**: bd-issue-tracking + developing-strategic-documents skill + +**Workflow**: +1. Create bd issue for tracking: + ```bash + bd create "Q4 strategic planning document" -t task -p 0 + bd update strat-1 --status in_progress + ``` + +2. Use developing-strategic-documents skill for research and writing + +3. Update bd notes at milestones: + ```bash + bd update strat-1 --notes "COMPLETED: Research phase (reviewed 5 competitor docs, 3 internal reports) + KEY DECISION: Focus on market expansion over cost optimization per exec input + IN PROGRESS: Drafting recommendations section + NEXT: Get exec review of draft recommendations before finalizing" + ``` + +4. TodoWrite tracks immediate writing tasks: + ``` + - [ ] Draft recommendation 1: Market expansion + - [ ] Add supporting data from research + - [ ] Create budget estimates + ``` + +**Why this works**: bd preserves context across sessions (document might take days), skill provides writing framework, TodoWrite tracks current work. + +### Pattern: Multi-File Refactoring + +**Scenario**: Refactor authentication system across 8 files + +**Tools used**: bd-issue-tracking + systematic-debugging (if issues found) + +**Workflow**: +1. Create epic and subtasks: + ```bash + bd create "Refactor auth system to use JWT" -t epic -p 0 + bd create "Update login endpoint" -t task + bd create "Update token validation" -t task + bd create "Update middleware" -t task + bd create "Update tests" -t task + + # Link hierarchy + bd dep add auth-epic login-1 --type parent-child + bd dep add auth-epic validation-2 --type parent-child + bd dep add auth-epic middleware-3 --type parent-child + bd dep add auth-epic tests-4 --type parent-child + + # Add ordering + bd dep add validation-2 login-1 # validation depends on login + bd dep add middleware-3 validation-2 # middleware depends on validation + bd dep add tests-4 middleware-3 # tests depend on middleware + ``` + +2. Work through subtasks in order, using TodoWrite for each: + ``` + Current: login-1 + TodoWrite: + - [ ] Update login route signature + - [ ] Add JWT generation + - [ ] Update tests + - [ ] Verify backward compatibility + ``` + +3. Update bd notes as each completes: + ```bash + bd close login-1 --reason "Updated to JWT. Tests passing. Backward compatible with session auth." + ``` + +4. If issues discovered, use systematic-debugging skill + create blocker issues + +**Why this works**: bd tracks dependencies and progress across files, TodoWrite focuses on current file, skills provide specialized frameworks when needed. + +--- + +## Decision Framework + +### Which Tool for Which Purpose? + +| Need | Tool | Why | +|------|------|-----| +| Track today's execution | TodoWrite | Lightweight, shows current progress | +| Preserve context across sessions | bd | Survives compaction, persistent memory | +| Detailed implementation steps | writing-plans | RED-GREEN-REFACTOR breakdown | +| Research document structure | developing-strategic-documents | Domain-specific framework | +| Debug complex issue | systematic-debugging | Structured debugging protocol | + +### Decision Tree + +``` +Is this work done in this session? +├─ Yes → Use TodoWrite only +└─ No → Use bd + ├─ Simple feature → bd issue + TodoWrite + └─ Complex feature → bd issue + writing-plans + TodoWrite + +Will conversation history get compacted? +├─ Likely → Use bd (context survives) +└─ Unlikely → TodoWrite is sufficient + +Does work have dependencies or blockers? +├─ Yes → Use bd (tracks relationships) +└─ No → TodoWrite is sufficient + +Is this specialized domain work? +├─ Research/writing → developing-strategic-documents +├─ Complex debugging → systematic-debugging +├─ Detailed implementation → writing-plans +└─ General tracking → bd + TodoWrite +``` + +### Integration Anti-Patterns + +**Don't**: +- Duplicate TodoWrite tasks into bd notes (different purposes) +- Create bd issues for single-session linear work (use TodoWrite) +- Put detailed implementation steps in bd notes (use writing-plans) +- Update bd after every TodoWrite task (update at milestones) +- Use writing-plans for exploratory work (defeats the purpose) + +**Do**: +- Update bd when changing tools or reaching milestones +- Use TodoWrite as "working copy" of bd's NEXT section +- Link between tools (bd design field → writing-plans file path) +- Choose the right level of formality for the work complexity + +--- + +## Summary + +**Key principle**: Each tool operates at a different timescale and level of detail. + +- **TodoWrite**: Minutes to hours (current execution) +- **bd**: Hours to weeks (persistent context) +- **writing-plans**: Days to weeks (detailed breakdown) +- **Other skills**: As needed (domain frameworks) + +**Integration pattern**: Use the lightest tool sufficient for the task, add heavier tools only when complexity demands it. + +**For complete boundaries and decision criteria, see:** [BOUNDARIES.md](BOUNDARIES.md) diff --git a/skills/beads/references/MOLECULES.md b/skills/beads/references/MOLECULES.md new file mode 100644 index 00000000..9484b832 --- /dev/null +++ b/skills/beads/references/MOLECULES.md @@ -0,0 +1,354 @@ +# Molecules and Wisps Reference + +This reference covers bd's molecular chemistry system for reusable work templates and ephemeral workflows. + +## The Chemistry Metaphor + +bd v0.34.0 introduces a chemistry-inspired workflow system: + +| Phase | Name | Storage | Synced? | Use Case | +|-------|------|---------|---------|----------| +| **Solid** | Proto | `.beads/` | Yes | Reusable template (epic with `template` label) | +| **Liquid** | Mol | `.beads/` | Yes | Persistent instance (real issues from template) | +| **Vapor** | Wisp | `.beads-wisp/` | No | Ephemeral instance (operational work, no audit trail) | + +**Phase transitions:** +- `spawn` / `pour`: Solid (proto) → Liquid (mol) +- `wisp create`: Solid (proto) → Vapor (wisp) +- `squash`: Vapor (wisp) → Digest (permanent summary) +- `burn`: Vapor (wisp) → Nothing (deleted, no trace) +- `distill`: Liquid (ad-hoc epic) → Solid (proto) + +## When to Use Molecules + +### Use Protos/Mols When: +- **Repeatable patterns** - Same workflow structure used multiple times (releases, reviews, onboarding) +- **Team knowledge capture** - Encoding tribal knowledge as executable templates +- **Audit trail matters** - Work that needs to be tracked and reviewed later +- **Cross-session persistence** - Work spanning multiple days/sessions + +### Use Wisps When: +- **Operational loops** - Patrol cycles, health checks, routine monitoring +- **One-shot orchestration** - Temporary coordination that shouldn't clutter history +- **Diagnostic runs** - Debugging workflows with no archival value +- **High-frequency ephemeral work** - Would create noise in permanent database + +**Key insight:** Wisps prevent database bloat from routine operations while still providing structure during execution. + +--- + +## Proto Management + +### Creating a Proto + +Protos are epics with the `template` label. Create manually or distill from existing work: + +```bash +# Manual creation +bd create "Release Workflow" --type epic --label template +bd create "Run tests for {{component}}" --type task +bd dep add task-id epic-id --type parent-child + +# Distill from ad-hoc work (extracts template from existing epic) +bd mol distill bd-abc123 --as "Release Workflow" --var version=1.0.0 +``` + +**Proto naming convention:** Use `mol-` prefix for clarity (e.g., `mol-release`, `mol-patrol`). + +### Listing Protos + +```bash +bd mol catalog # List all protos +bd mol catalog --json # Machine-readable +``` + +### Viewing Proto Structure + +```bash +bd mol show mol-release # Show template structure and variables +bd mol show mol-release --json # Machine-readable +``` + +--- + +## Spawning Molecules + +### Basic Spawn (Creates Wisp by Default) + +```bash +bd mol spawn mol-patrol # Creates wisp (ephemeral) +bd mol spawn mol-feature --pour # Creates mol (persistent) +bd mol spawn mol-release --var version=2.0 # With variable substitution +``` + +**Chemistry shortcuts:** +```bash +bd pour mol-feature # Shortcut for spawn --pour +bd wisp create mol-patrol # Explicit wisp creation +``` + +### Spawn with Immediate Execution + +```bash +bd mol run mol-release --var version=2.0 +``` + +`bd mol run` does three things: +1. Spawns the molecule (persistent) +2. Assigns root issue to caller +3. Pins root issue for session recovery + +**Use `mol run` when:** Starting durable work that should survive crashes. The pin ensures `bd ready` shows the work after restart. + +### Spawn with Attachments + +Attach additional protos in a single command: + +```bash +bd mol spawn mol-feature --attach mol-testing --var name=auth +# Spawns mol-feature, then spawns mol-testing and bonds them +``` + +**Attach types:** +- `sequential` (default) - Attached runs after primary completes +- `parallel` - Attached runs alongside primary +- `conditional` - Attached runs only if primary fails + +```bash +bd mol spawn mol-deploy --attach mol-rollback --attach-type conditional +``` + +--- + +## Bonding Molecules + +### Bond Types + +```bash +bd mol bond A B # Sequential: B runs after A +bd mol bond A B --type parallel # Parallel: B runs alongside A +bd mol bond A B --type conditional # Conditional: B runs if A fails +``` + +### Operand Combinations + +| A | B | Result | +|---|---|--------| +| proto | proto | Compound proto (reusable template) | +| proto | mol | Spawn proto, attach to molecule | +| mol | proto | Spawn proto, attach to molecule | +| mol | mol | Join into compound molecule | + +### Phase Control in Bonds + +By default, spawned protos inherit target's phase. Override with flags: + +```bash +# Found bug during wisp patrol? Persist it: +bd mol bond mol-critical-bug wisp-patrol --pour + +# Need ephemeral diagnostic on persistent feature? +bd mol bond mol-temp-check bd-feature --wisp +``` + +### Custom Compound Names + +```bash +bd mol bond mol-feature mol-deploy --as "Feature with Deploy" +``` + +--- + +## Wisp Lifecycle + +### Creating Wisps + +```bash +bd wisp create mol-patrol # From proto +bd mol spawn mol-patrol # Same (spawn defaults to wisp) +bd mol spawn mol-check --var target=db # With variables +``` + +### Listing Wisps + +```bash +bd wisp list # List all wisps +bd wisp list --json # Machine-readable +``` + +### Ending Wisps + +**Option 1: Squash (compress to digest)** +```bash +bd mol squash wisp-abc123 # Auto-generate summary +bd mol squash wisp-abc123 --summary "Completed patrol" # Agent-provided summary +bd mol squash wisp-abc123 --keep-children # Keep children, just create digest +bd mol squash wisp-abc123 --dry-run # Preview +``` + +Squash creates a permanent digest issue summarizing the wisp's work, then deletes the wisp children. + +**Option 2: Burn (delete without trace)** +```bash +bd mol burn wisp-abc123 # Delete wisp, no digest +``` + +Use burn for routine work with no archival value. + +### Garbage Collection + +```bash +bd wisp gc # Clean up orphaned wisps +``` + +--- + +## Distilling Protos + +Extract a reusable template from ad-hoc work: + +```bash +bd mol distill bd-o5xe --as "Release Workflow" +bd mol distill bd-abc --var feature_name=auth-refactor --var version=1.0.0 +``` + +**What distill does:** +1. Loads existing epic and all children +2. Clones structure as new proto (adds `template` label) +3. Replaces concrete values with `{{variable}}` placeholders + +**Variable syntax (both work):** +```bash +--var branch=feature-auth # variable=value (recommended) +--var feature-auth=branch # value=variable (auto-detected) +``` + +**Use cases:** +- Team develops good workflow organically, wants to reuse it +- Capture tribal knowledge as executable templates +- Create starting point for similar future work + +--- + +## Cross-Project Dependencies + +### Concept + +Projects can depend on capabilities shipped by other projects: + +```bash +# Project A ships a capability +bd ship auth-api # Marks capability as available + +# Project B depends on it +bd dep add bd-123 external:project-a:auth-api +``` + +### Shipping Capabilities + +```bash +bd ship # Ship capability (requires closed issue) +bd ship --force # Ship even if issue not closed +bd ship --dry-run # Preview +``` + +**How it works:** +1. Find issue with `export:` label +2. Validate issue is closed +3. Add `provides:` label + +### Depending on External Capabilities + +```bash +bd dep add external:: +``` + +The dependency is satisfied when the external project has a closed issue with `provides:` label. + +**`bd ready` respects external deps:** Issues blocked by unsatisfied external dependencies won't appear in ready list. + +--- + +## Common Patterns + +### Pattern: Weekly Review Proto + +```bash +# Create proto +bd create "Weekly Review" --type epic --label template +bd create "Review open issues" --type task +bd create "Update priorities" --type task +bd create "Archive stale work" --type task +# Link as children... + +# Use each week +bd mol spawn mol-weekly-review --pour +``` + +### Pattern: Ephemeral Patrol Cycle + +```bash +# Patrol proto exists +bd wisp create mol-patrol + +# Execute patrol work... + +# End patrol +bd mol squash wisp-abc123 --summary "Patrol complete: 3 issues found, 2 resolved" +``` + +### Pattern: Feature with Rollback + +```bash +bd mol spawn mol-deploy --attach mol-rollback --attach-type conditional +# If deploy fails, rollback automatically becomes unblocked +``` + +### Pattern: Capture Tribal Knowledge + +```bash +# After completing a good workflow organically +bd mol distill bd-release-epic --as "Release Process" --var version=X.Y.Z +# Now team can: bd mol spawn mol-release-process --var version=2.0.0 +``` + +--- + +## CLI Quick Reference + +| Command | Purpose | +|---------|---------| +| `bd mol catalog` | List available protos | +| `bd mol show ` | Show proto/mol structure | +| `bd mol spawn ` | Create wisp from proto (default) | +| `bd mol spawn --pour` | Create persistent mol from proto | +| `bd mol run ` | Spawn + assign + pin (durable execution) | +| `bd mol bond ` | Combine protos or molecules | +| `bd mol distill ` | Extract proto from ad-hoc work | +| `bd mol squash ` | Compress wisp children to digest | +| `bd mol burn ` | Delete wisp without trace | +| `bd pour ` | Shortcut for `spawn --pour` | +| `bd wisp create ` | Create ephemeral wisp | +| `bd wisp list` | List all wisps | +| `bd wisp gc` | Garbage collect orphaned wisps | +| `bd ship ` | Publish capability for cross-project deps | + +--- + +## Troubleshooting + +**"Proto not found"** +- Check `bd mol catalog` for available protos +- Protos need `template` label on the epic + +**"Variable not substituted"** +- Use `--var key=value` syntax +- Check proto for `{{key}}` placeholders with `bd mol show` + +**"Wisp commands fail"** +- Wisps stored in `.beads-wisp/` (separate from `.beads/`) +- Check `bd wisp list` for active wisps + +**"External dependency not satisfied"** +- Target project must have closed issue with `provides:` label +- Use `bd ship ` in target project first diff --git a/skills/beads/references/PATTERNS.md b/skills/beads/references/PATTERNS.md new file mode 100644 index 00000000..fb1e0849 --- /dev/null +++ b/skills/beads/references/PATTERNS.md @@ -0,0 +1,341 @@ +# Common Usage Patterns + +Practical patterns for using bd effectively across different scenarios. + +## Contents + +- [Knowledge Work Session](#knowledge-work-session) - Resume long-running research or writing tasks +- [Side Quest Handling](#side-quest-handling) - Capture discovered work without losing context +- [Multi-Session Project Resume](#multi-session-project-resume) - Pick up work after time away +- [Status Transitions](#status-transitions) - When to change issue status +- [Compaction Recovery](#compaction-recovery) - Resume after conversation history is lost +- [Issue Closure](#issue-closure) - Documenting completion properly + +--- + +## 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. + +**Key insight**: Notes field captures the "why" and context, TodoWrite tracks the "doing" right now. + +--- + +## Side Quest Handling + +**Scenario**: During main task, discover a problem that needs attention. + +**Pattern**: +1. Create issue immediately: `bd create "Found: inventory system needs refactoring"` +2. Link provenance: `bd dep add main-task new-issue --type discovered-from` +3. Assess urgency: blocker or can defer? +4. **If blocker**: + - `bd update main-task --status blocked` + - `bd update new-issue --status in_progress` + - Work on the blocker +5. **If deferrable**: + - Note in new issue's design field + - Continue main task + - New issue persists for later + +**Why this works**: Captures context immediately (before forgetting), preserves relationship to main work, allows flexible prioritization. + +**Example (with MCP):** + +Working on "Implement checkout flow" (checkout-1), discover payment validation security hole: + +1. Create bug issue: `mcp__plugin_beads_beads__create` with `{title: "Fix: payment validation bypasses card expiry check", type: "bug", priority: 0}` +2. Link discovery: `mcp__plugin_beads_beads__dep` with `{from_issue: "checkout-1", to_issue: "payment-bug-2", type: "discovered-from"}` +3. Block current work: `mcp__plugin_beads_beads__update` with `{issue_id: "checkout-1", status: "blocked", notes: "Blocked by payment-bug-2: security hole in validation"}` +4. Start new work: `mcp__plugin_beads_beads__update` with `{issue_id: "payment-bug-2", status: "in_progress"}` + +(CLI: `bd create "Fix: payment validation..." -t bug -p 0` then `bd dep add` and `bd update` commands) + +--- + +## Multi-Session Project Resume + +**Scenario**: Starting work after days or weeks away from a project. + +**Pattern (with MCP)**: +1. **Check what's ready**: Use `mcp__plugin_beads_beads__ready` to see available work +2. **Check what's stuck**: Use `mcp__plugin_beads_beads__blocked` to understand blockers +3. **Check recent progress**: Use `mcp__plugin_beads_beads__list` with `status:"closed"` to see completions +4. **Read detailed context**: Use `mcp__plugin_beads_beads__show` for the issue you'll work on +5. **Update status**: Use `mcp__plugin_beads_beads__update` with `status:"in_progress"` +6. **Begin work**: Create TodoWrite from notes field's NEXT section + +(CLI: `bd ready`, `bd blocked`, `bd list --status closed`, `bd show `, `bd update --status in_progress`) + +**Example**: +```bash +$ bd ready +Ready to work on (3): + auth-5: "Add OAuth refresh token rotation" (priority: 0) + api-12: "Document REST API endpoints" (priority: 1) + test-8: "Add integration tests for payment flow" (priority: 2) + +$ bd show auth-5 +Title: Add OAuth refresh token rotation +Status: open +Priority: 0 (critical) + +Notes: +COMPLETED: Basic JWT auth working +IN PROGRESS: Need to add token refresh +NEXT: Implement rotation per OWASP guidelines (7-day refresh tokens) +BLOCKER: None - ready to proceed + +$ bd update auth-5 --status in_progress +# Now create TodoWrite based on NEXT section +``` + +**For complete session start workflow with checklist, see:** [WORKFLOWS.md](WORKFLOWS.md#session-start) + +--- + +## Status Transitions + +Understanding when to change issue status. + +### Status Lifecycle + +``` +open → in_progress → closed + ↓ ↓ +blocked blocked +``` + +### When to Use Each Status + +**open** (default): +- Issue created but not started +- Waiting for dependencies to clear +- Planned work not yet begun +- **Command**: Issues start as `open` by default + +**in_progress**: +- Actively working on this issue right now +- Has been read and understood +- Making commits or changes related to this +- **Command**: `bd update issue-id --status in_progress` +- **When**: Start of work session on this issue + +**blocked**: +- Cannot proceed due to external blocker +- Waiting for user input/decision +- Dependency not completed +- Technical blocker discovered +- **Command**: `bd update issue-id --status blocked` +- **When**: Hit a blocker, capture what blocks you in notes +- **Note**: Document blocker in notes field: "BLOCKER: Waiting for API key from ops team" + +**closed**: +- Work completed and verified +- Tests passing +- Acceptance criteria met +- **Command**: `bd close issue-id --reason "Implemented with tests passing"` +- **When**: All work done, ready to move on +- **Note**: Issues remain in database, just marked complete + +### Transition Examples + +**Starting work**: +```bash +bd ready # See what's available +bd update auth-5 --status in_progress +# Begin working +``` + +**Hit a blocker**: +```bash +bd update auth-5 --status blocked --notes "BLOCKER: Need OAuth client ID from product team. Emailed Jane on 2025-10-23." +# Switch to different issue or create new work +``` + +**Unblocking**: +```bash +# Once blocker resolved +bd update auth-5 --status in_progress --notes "UNBLOCKED: Received OAuth credentials. Resuming implementation." +``` + +**Completing**: +```bash +bd close auth-5 --reason "Implemented OAuth refresh with 7-day rotation. Tests passing. PR #42 merged." +``` + +--- + +## Compaction Recovery + +**Scenario**: Conversation history has been compacted. You need to resume work with zero conversation context. + +**What survives compaction**: +- All bd issues and notes +- Complete work history +- Dependencies and relationships + +**What's lost**: +- Conversation history +- TodoWrite lists +- Recent discussion + +### Recovery Pattern + +1. **Check in-progress work**: + ```bash + bd list --status in_progress + ``` + +2. **Read notes for context**: + ```bash + bd show issue-id + # Read notes field - should explain current state + ``` + +3. **Reconstruct TodoWrite from notes**: + - COMPLETED section: Done, skip + - IN PROGRESS section: Current state + - NEXT section: **This becomes your TodoWrite list** + +4. **Report to user**: + ``` + "From bd notes: [summary of COMPLETED]. Currently [IN PROGRESS]. + Next steps: [from NEXT]. Should I continue with that?" + ``` + +### Example Recovery + +**bd show returns**: +``` +Issue: bd-42 "OAuth refresh token implementation" +Status: in_progress +Notes: +COMPLETED: Basic JWT validation working (RS256, 1hr access tokens) +KEY DECISION: 7-day refresh tokens per security review +IN PROGRESS: Implementing token rotation endpoint +NEXT: Add rate limiting (5 refresh attempts per 15min), then write tests +BLOCKER: None +``` + +**Recovery actions**: +1. Read notes, understand context +2. Create TodoWrite: + ``` + - [ ] Implement rate limiting on refresh endpoint + - [ ] Write tests for token rotation + - [ ] Verify security guidelines met + ``` +3. Report: "From notes: JWT validation is done with 7-day refresh tokens. Currently implementing rotation endpoint. Next: add rate limiting and tests. Should I continue?" +4. Resume work based on user response + +**For complete compaction survival workflow, see:** [WORKFLOWS.md](WORKFLOWS.md#compaction-survival) + +--- + +## Issue Closure + +**Scenario**: Work is complete. How to close properly? + +### Closure Checklist + +Before closing, verify: +- [ ] **Acceptance criteria met**: All items checked off +- [ ] **Tests passing**: If applicable +- [ ] **Documentation updated**: If needed +- [ ] **Follow-up work filed**: New issues created for discovered work +- [ ] **Key decisions documented**: In notes field + +### Closure Pattern + +**Minimal closure** (simple tasks): +```bash +bd close task-123 --reason "Implemented feature X" +``` + +**Detailed closure** (complex work): +```bash +# Update notes with final state +bd update task-123 --notes "COMPLETED: OAuth refresh with 7-day rotation +KEY DECISION: RS256 over HS256 per security review +TESTS: 12 tests passing (auth, rotation, expiry, errors) +FOLLOW-UP: Filed perf-99 for token cleanup job" + +# Close with summary +bd close task-123 --reason "Implemented OAuth refresh token rotation with rate limiting. All security guidelines met. Tests passing." +``` + +### Documenting Resolution (Outcome vs Design) + +For issues where the outcome differed from initial design, use `--notes` to document what actually happened: + +```bash +# Initial design was hypothesis - document actual outcome in notes +bd update bug-456 --notes "RESOLUTION: Not a bug - behavior is correct per OAuth spec. Documentation was unclear. Filed docs-789 to clarify auth flow in user guide." + +bd close bug-456 --reason "Resolved: documentation issue, not bug" +``` + +**Pattern**: Design field = initial approach. Notes field = what actually happened (prefix with RESOLUTION: for clarity). + +### Discovering Follow-up Work + +When closing reveals new work: + +```bash +# While closing auth feature, realize performance needs work +bd create "Optimize token lookup query" -t task -p 2 + +# Link the provenance +bd dep add auth-5 perf-99 --type discovered-from + +# Now close original +bd close auth-5 --reason "OAuth refresh implemented. Discovered perf optimization needed (filed perf-99)." +``` + +**Why link with discovered-from**: Preserves the context of how you found the new work. Future you will appreciate knowing it came from the auth implementation. + +--- + +## Pattern Summary + +| Pattern | When to Use | Key Command | Preserves | +|---------|-------------|-------------|-----------| +| **Knowledge Work** | Long-running research, writing | `bd update --notes` | Context across sessions | +| **Side Quest** | Discovered during other work | `bd dep add --type discovered-from` | Relationship to original | +| **Multi-Session Resume** | Returning after time away | `bd ready`, `bd show` | Full project state | +| **Status Transitions** | Tracking work state | `bd update --status` | Current state | +| **Compaction Recovery** | History lost | Read notes field | All context in notes | +| **Issue Closure** | Completing work | `bd close --reason` | Decisions and outcomes | + +**For detailed workflows with step-by-step checklists, see:** [WORKFLOWS.md](WORKFLOWS.md) diff --git a/skills/beads/references/TROUBLESHOOTING.md b/skills/beads/references/TROUBLESHOOTING.md new file mode 100644 index 00000000..2043c9c7 --- /dev/null +++ b/skills/beads/references/TROUBLESHOOTING.md @@ -0,0 +1,489 @@ +# Troubleshooting Guide + +Common issues encountered when using bd and how to resolve them. + +## Interface-Specific Troubleshooting + +**MCP tools (local environment):** +- MCP tools require bd daemon running +- Check daemon status: `bd daemon --status` (CLI) +- If MCP tools fail, verify daemon is running and restart if needed +- MCP tools automatically use daemon mode (no --no-daemon option) + +**CLI (web environment or local):** +- CLI can use daemon mode (default) or direct mode (--no-daemon) +- Direct mode has 3-5 second sync delay +- Web environment: Install via `npm install -g @beads/cli` +- Web environment: Initialize via `bd init ` before first use + +**Most issues below apply to both interfaces** - the underlying database and daemon behavior is the same. + +## Contents + +- [Dependencies Not Persisting](#dependencies-not-persisting) +- [Status Updates Not Visible](#status-updates-not-visible) +- [Daemon Won't Start](#daemon-wont-start) +- [Database Errors on Cloud Storage](#database-errors-on-cloud-storage) +- [JSONL File Not Created](#jsonl-file-not-created) +- [Version Requirements](#version-requirements) + +--- + +## Dependencies Not Persisting + +### Symptom +```bash +bd dep add issue-2 issue-1 --type blocks +# Reports: ✓ Added dependency +bd show issue-2 +# Shows: No dependencies listed +``` + +### Root Cause (Fixed in v0.15.0+) +This was a **bug in bd** (GitHub issue #101) where the daemon ignored dependencies during issue creation. **Fixed in bd v0.15.0** (Oct 21, 2025). + +### Resolution + +**1. Check your bd version:** +```bash +bd version +``` + +**2. If version < 0.15.0, update bd:** +```bash +# Via Homebrew (macOS/Linux) +brew upgrade bd + +# Via go install +go install github.com/steveyegge/beads/cmd/bd@latest + +# Via package manager +# See https://github.com/steveyegge/beads#installing +``` + +**3. Restart daemon after upgrade:** +```bash +pkill -f "bd daemon" # Kill old daemon +bd daemon # Start new daemon with fix +``` + +**4. Test dependency creation:** +```bash +bd create "Test A" -t task +bd create "Test B" -t task +bd dep add --type blocks +bd show +# Should show: "Depends on (1): → " +``` + +### Still Not Working? + +If dependencies still don't persist after updating: + +1. **Check daemon is running:** + ```bash + ps aux | grep "bd daemon" + ``` + +2. **Try without --no-daemon flag:** + ```bash + # Instead of: bd --no-daemon dep add ... + # Use: bd dep add ... (let daemon handle it) + ``` + +3. **Check JSONL file:** + ```bash + cat .beads/issues.jsonl | jq '.dependencies' + # Should show dependency array + ``` + +4. **Report to beads GitHub** with: + - `bd version` output + - Operating system + - Reproducible test case + +--- + +## Status Updates Not Visible + +### Symptom +```bash +bd --no-daemon update issue-1 --status in_progress +# Reports: ✓ Updated issue: issue-1 +bd show issue-1 +# Shows: Status: open (not in_progress!) +``` + +### Root Cause +This is **expected behavior**, not a bug. Understanding requires knowing bd's architecture: + +**BD Architecture:** +- **JSONL files** (`.beads/issues.jsonl`): Human-readable export format +- **SQLite database** (`.beads/*.db`): Source of truth for queries +- **Daemon**: Syncs JSONL ↔ SQLite every 5 minutes + +**What `--no-daemon` actually does:** +- **Writes**: Go directly to JSONL file +- **Reads**: Still come from SQLite database +- **Sync delay**: Daemon imports JSONL → SQLite periodically + +### Resolution + +**Option 1: Use daemon mode (recommended)** +```bash +# Don't use --no-daemon for CRUD operations +bd update issue-1 --status in_progress +bd show issue-1 +# ✓ Status reflects immediately +``` + +**Option 2: Wait for sync (if using --no-daemon)** +```bash +bd --no-daemon update issue-1 --status in_progress +# Wait 3-5 seconds for daemon to sync +sleep 5 +bd show issue-1 +# ✓ Status should reflect now +``` + +**Option 3: Manual sync trigger** +```bash +bd --no-daemon update issue-1 --status in_progress +# Trigger sync by exporting/importing +bd export > /dev/null 2>&1 # Forces sync +bd show issue-1 +``` + +### When to Use `--no-daemon` + +**Use --no-daemon for:** +- Batch import scripts (performance) +- CI/CD environments (no persistent daemon) +- Testing/debugging + +**Don't use --no-daemon for:** +- Interactive development +- Real-time status checks +- When you need immediate query results + +--- + +## Daemon Won't Start + +### Symptom +```bash +bd daemon +# Error: not in a git repository +# Hint: run 'git init' to initialize a repository +``` + +### Root Cause +bd daemon requires a **git repository** because it uses git for: +- Syncing issues to git remote (optional) +- Version control of `.beads/*.jsonl` files +- Commit history of issue changes + +### Resolution + +**Initialize git repository:** +```bash +# In your project directory +git init +bd daemon +# ✓ Daemon should start now +``` + +**Prevent git remote operations:** +```bash +# If you don't want daemon to pull from remote +bd daemon --global=false +``` + +**Flags:** +- `--global=false`: Don't sync with git remote +- `--interval=10m`: Custom sync interval (default: 5m) +- `--auto-commit=true`: Auto-commit JSONL changes + +--- + +## Database Errors on Cloud Storage + +### Symptom +```bash +# In directory: /Users/name/Google Drive/... +bd init myproject +# Error: disk I/O error (522) +# OR: Error: database is locked +``` + +### Root Cause +**SQLite incompatibility with cloud sync filesystems.** + +Cloud services (Google Drive, Dropbox, OneDrive, iCloud) don't support: +- POSIX file locking (required by SQLite) +- Consistent file handles across sync operations +- Atomic write operations + +This is a **known SQLite limitation**, not a bd bug. + +### Resolution + +**Move bd database to local filesystem:** + +```bash +# Wrong location (cloud sync) +~/Google Drive/My Work/project/.beads/ # ✗ Will fail + +# Correct location (local disk) +~/Repos/project/.beads/ # ✓ Works reliably +~/Projects/project/.beads/ # ✓ Works reliably +``` + +**Migration steps:** + +1. **Move project to local disk:** + ```bash + mv ~/Google\ Drive/project ~/Repos/project + cd ~/Repos/project + ``` + +2. **Re-initialize bd (if needed):** + ```bash + bd init myproject + ``` + +3. **Import existing issues (if you had JSONL export):** + ```bash + bd import < issues-backup.jsonl + ``` + +**Alternative: Use global `~/.beads/` database** + +If you must keep work on cloud storage: +```bash +# Don't initialize bd in cloud-synced directory +# Use global database instead +cd ~/Google\ Drive/project +bd create "My task" +# Uses ~/.beads/default.db (on local disk) +``` + +**Workaround limitations:** +- No per-project database isolation +- All projects share same issue prefix +- Manual tracking of which issues belong to which project + +**Recommendation:** Keep code/projects on local disk, sync final deliverables to cloud. + +--- + +## JSONL File Not Created + +### Symptom +```bash +bd init myproject +bd --no-daemon create "Test" -t task +ls .beads/ +# Only shows: .gitignore, myproject.db +# Missing: issues.jsonl +``` + +### Root Cause +**JSONL initialization coupling.** The `issues.jsonl` file is created by daemon on first startup, not by `bd init`. + +### Resolution + +**Start daemon once to initialize JSONL:** +```bash +bd daemon --global=false & +# Wait for initialization +sleep 2 + +# Now JSONL file exists +ls .beads/issues.jsonl +# ✓ File created + +# Subsequent --no-daemon operations work +bd --no-daemon create "Task 1" -t task +cat .beads/issues.jsonl +# ✓ Shows task data +``` + +**Why this matters:** +- Daemon owns the JSONL export format +- First daemon run creates empty JSONL skeleton +- `--no-daemon` operations assume JSONL exists + +**Pattern for batch scripts:** +```bash +#!/bin/bash +# Batch import script + +bd init myproject +bd daemon --global=false & # Start daemon +sleep 3 # Wait for initialization + +# Now safe to use --no-daemon for performance +for item in "${items[@]}"; do + bd --no-daemon create "$item" -t feature +done + +# Daemon syncs JSONL → SQLite in background +sleep 5 # Wait for final sync + +# Query results +bd stats +``` + +--- + +## Version Requirements + +### Minimum Version for Dependency Persistence + +**Issue:** Dependencies created but don't appear in `bd show` or dependency tree. + +**Fix:** Upgrade to **bd v0.15.0+** (released Oct 2025) + +**Check version:** +```bash +bd version +# Should show: bd version 0.15.0 or higher +``` + +**If using MCP plugin:** +```bash +# Update Claude Code beads plugin +claude plugin update beads +``` + +### Breaking Changes + +**v0.15.0:** +- MCP parameter names changed from `from_id/to_id` to `issue_id/depends_on_id` +- Dependency creation now persists correctly in daemon mode + +**v0.14.0:** +- Daemon architecture changes +- Auto-sync JSONL behavior introduced + +--- + +## MCP-Specific Issues + +### Dependencies Created Backwards + +**Symptom:** +Using MCP tools, dependencies end up reversed from intended. + +**Example:** +```python +# Want: "task-2 depends on task-1" (task-1 blocks task-2) +beads_add_dependency(issue_id="task-1", depends_on_id="task-2") +# Wrong! This makes task-1 depend on task-2 +``` + +**Root Cause:** +Parameter confusion between old (`from_id/to_id`) and new (`issue_id/depends_on_id`) names. + +**Resolution:** + +**Correct MCP usage (bd v0.15.0+):** +```python +# Correct: task-2 depends on task-1 +beads_add_dependency( + issue_id="task-2", # Issue that has dependency + depends_on_id="task-1", # Issue that must complete first + dep_type="blocks" +) +``` + +**Mnemonic:** +- `issue_id`: The issue that **waits** +- `depends_on_id`: The issue that **must finish first** + +**Equivalent CLI:** +```bash +bd dep add task-2 task-1 --type blocks +# Meaning: task-2 depends on task-1 +``` + +**Verify dependency direction:** +```bash +bd show task-2 +# Should show: "Depends on: task-1" +# Not the other way around +``` + +--- + +## Getting Help + +### Debug Checklist + +Before reporting issues, collect this information: + +```bash +# 1. Version +bd version + +# 2. Daemon status +ps aux | grep "bd daemon" + +# 3. Database location +echo $PWD/.beads/*.db +ls -la .beads/ + +# 4. Git status +git status +git log --oneline -1 + +# 5. JSONL contents (for dependency issues) +cat .beads/issues.jsonl | jq '.' | head -50 +``` + +### Report to beads GitHub + +If problems persist: + +1. **Check existing issues:** https://github.com/steveyegge/beads/issues +2. **Create new issue** with: + - bd version (`bd version`) + - Operating system + - Debug checklist output (above) + - Minimal reproducible example + - Expected vs actual behavior + +### Claude Code Skill Issues + +If the **bd-issue-tracking skill** provides incorrect guidance: + +1. **Check skill version:** + ```bash + ls -la ~/.claude/skills/bd-issue-tracking/ + head -20 ~/.claude/skills/bd-issue-tracking/SKILL.md + ``` + +2. **Report via Claude Code feedback** or user's GitHub + +--- + +## Quick Reference: Common Fixes + +| Problem | Quick Fix | +|---------|-----------| +| Dependencies not saving | Upgrade to bd v0.15.0+ | +| Status updates lag | Use daemon mode (not `--no-daemon`) | +| Daemon won't start | Run `git init` first | +| Database errors on Google Drive | Move to local filesystem | +| JSONL file missing | Start daemon once: `bd daemon &` | +| Dependencies backwards (MCP) | Update to v0.15.0+, use `issue_id/depends_on_id` correctly | + +--- + +## Related Documentation + +- [CLI Reference](CLI_REFERENCE.md) - Complete command documentation +- [Dependencies Guide](DEPENDENCIES.md) - Understanding dependency types +- [Workflows](WORKFLOWS.md) - Step-by-step workflow guides +- [beads GitHub](https://github.com/steveyegge/beads) - Official documentation