gitlore/plans/plan-to-beads-v2-draft.md

# plan-to-beads v2 — Draft for Review

This is a draft of the improved skill. Review before applying to `~/.claude/skills/plan-to-beads/SKILL.md`.

---

```markdown
---
name: plan-to-beads
description: Transforms markdown implementation plans into granular, agent-ready beads with dependency graphs. Each bead is fully self-contained — an agent can execute it with zero external context. Triggers on "break down this plan", "create beads from", "convert to beads", "make issues from plan".
argument-hint: "[path/to/plan.md]"
---

# Plan to Beads Conversion

## The Prime Directive

**Every bead must be executable by an agent that has ONLY the bead description.** No plan document. No Slack context. No "see the PRD." The bead IS the spec. If an agent can't start coding within 60 seconds of reading the bead, it's not ready.

## Workflow

```
┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│ 1. PARSE │──▶│ 2. MINE  │──▶│ 3. BUILD │──▶│ 4. LINK  │──▶│ 5. AUDIT │
│ Structure│   │ Context  │   │ Beads    │   │ Deps     │   │ Quality  │
└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
```

### 1. Parse Structure

Read the plan document. Identify:
- **Epics**: Major sections / phases / milestones
- **Tasks**: Implementable units with clear outcomes (1-4 hour scope)
- **Subtasks**: Granular steps within tasks

### 2. Mine Context

This is the critical step. For EACH identified task, extract everything an implementing agent will need.

#### From the plan document:

| Extract | Where to look | Example |
|---------|--------------|---------|
| **Rationale** | Intro paragraphs, "why" sections | "We need this because the current approach causes N+1 queries" |
| **Approach details** | Implementation notes, code snippets, architecture decisions | "Use a 5-stage pipeline: SEED → HYDRATE → ..." |
| **Test requirements** | TDD sections, acceptance criteria, "verify by" notes | "Test that empty input returns empty vec" |
| **Edge cases & risks** | Warnings, gotchas, "watch out for" notes | "Multi-byte UTF-8 chars can cause panics at byte boundaries" |
| **Data shapes** | Type definitions, struct descriptions, API contracts | "TimelineEvent { kind: EventKind, timestamp: DateTime, ... }" |
| **File paths** | Explicit mentions or inferable from module structure | "src/core/timeline_seed.rs" |
| **Dependencies on other tasks** | "requires X", "after Y is done", "uses Z from step N" | "Consumes the TimelineEvent struct from the types task" |
| **Verification commands** | Test commands, CLI invocations, expected outputs | "cargo test timeline_seed -- --nocapture" |

#### From the codebase:

Search the codebase to supplement what the plan says:
- Find existing files mentioned or implied by the plan
- Discover patterns the task should follow (e.g., how existing similar modules are structured)
- Check test files for naming conventions and test infrastructure in use
- Confirm exact file paths rather than guessing

Use codebase search tools (WarpGrep, Explore agent, or targeted Grep/Glob) appropriate to the scope of what you need to find.

### 3. Build Beads

Use `br` exclusively.

| Type | Priority | Command |
|------|----------|---------|
| Epic | 1 | `br create "Epic: [Title]" -p 1` |
| Task | 2-3 | `br create "[Verb] [Object]" -p 2` |
| Subtask | 3-4 | `br q "[Verb] [Object]"` |

**Granularity target**: Each bead completable in 1-4 hours by one agent.

#### Description Templates

Use the **full template** for all task-level beads. Use the **light template** only for trivially small tasks (config change, single-line fix, add a re-export).

##### Full Template (default)

```
## Background
[WHY this exists. What problem it solves. How it fits into the larger system.
Include enough context that an agent unfamiliar with the project understands
the purpose. Reference architectural patterns in use.]

## Approach
[HOW to implement. Be specific:
- Data structures / types to create or use (include field names and types)
- Algorithms or patterns to follow
- Code snippets from the plan if available
- Which existing code to reference for patterns (exact file paths)]

## Acceptance Criteria

### Specified (from plan — implement as-is)
- [ ] <criteria explicitly stated in the plan>
- [ ] <criteria explicitly stated in the plan>

### Proposed (inferred — confirm with user before implementing) [?]
- [ ] [?] <criteria the agent inferred but the plan didn't specify>
- [ ] [?] <criteria the agent inferred but the plan didn't specify>

**ASSUMPTION RULE**: If proposed criteria exceed ~30% of total, STOP.
The bead needs human input before it's ready for implementation. Flag it
in the audit output and ask the user to refine the ACs.

## Files
[Exact paths to create or modify. Confirmed by searching the codebase.]
- CREATE: src/foo/bar.rs
- MODIFY: src/foo/mod.rs (add pub mod bar)
- MODIFY: tests/foo_tests.rs (add test module)

## TDD Anchor
[The first test to write. This grounds the agent's work.]
RED: Write `test_<name>` in `<test_file>` that asserts <specific behavior>.
GREEN: Implement the minimal code to make it pass.
VERIFY: <project's test command> <pattern>

[If the plan specifies additional tests, list them all:]
- test_empty_input_returns_empty_vec
- test_single_issue_produces_one_event
- test_handles_missing_fields_gracefully

## Edge Cases
[Gotchas, risks, things that aren't obvious. Pulled from the plan's warnings,
known issues, or your analysis of the approach.]
- <edge case 1>
- <edge case 2>

## Dependency Context
[For each dependency, explain WHAT it provides that this bead consumes.
Not just "depends on bd-xyz" but "uses the `TimelineEvent` struct and
`SeedConfig` type defined in bd-xyz".]
```

##### Light Template (trivially small tasks only)

Use this ONLY when the task is a one-liner or pure mechanical change (add a re-export, flip a config flag, rename a constant). If there's any ambiguity about approach, use the full template.

```
## What
[One sentence: what to do and where.]

## Acceptance Criteria
- [ ] <single binary criterion>

## Files
- MODIFY: <exact path>
```

### 4. Link Dependencies

```bash
br dep add [blocker-id] [blocked-id]
```

Dependency patterns:
- Types/structs → code that uses them
- Infrastructure (DB, config) → features that need them
- Core logic → extensions/enhancements
- Tests may depend on test helpers

**Critical**: When linking deps, update the "Dependency Context" section in the blocked bead to describe exactly what it receives from the blocker.

### 5. Audit Quality

Before reporting, review EVERY bead against this checklist:

| Check | Pass criteria |
|-------|--------------|
| **Self-contained?** | Agent can start coding in 60 seconds with ONLY this description |
| **TDD anchor?** | First test to write is named and described |
| **Binary criteria?** | Every acceptance criterion is pass/fail, not subjective |
| **Exact paths?** | File paths verified against codebase, not guessed |
| **Edge cases?** | At least 1 non-obvious gotcha identified |
| **Dep context?** | Each dependency explains WHAT it provides, not just its ID |
| **Approach specifics?** | Types, field names, patterns — not "implement the thing" |
| **Assumption budget?** | Proposed [?] criteria are <30% of total ACs |

If a bead fails any check, fix it before moving on. If the assumption budget is exceeded, flag the bead for human review rather than inventing more ACs.

## Assumption & AC Guidance

Agents filling in beads will inevitably encounter gaps in the plan. The rules:

1. **Never silently fill gaps.** If the plan doesn't specify a behavior, don't assume one and bury it in the ACs. Mark it `[?]` so the implementing agent knows to ask.

2. **Specify provenance on every AC.** Specified = from the plan. Proposed = your inference. The implementing agent treats these differently:
   - **Specified**: implement without question
   - **Proposed [?]**: pause and confirm with the user before implementing

3. **The 30% rule.** If more than ~30% of ACs on a bead are proposed/inferred, the plan was too vague for this task. Don't create the bead as-is. Instead:
   - Create it with status noting "needs AC refinement"
   - List the open questions explicitly
   - Flag it in the output report under "Beads Needing Human Input"

4. **Prefer smaller scope over more assumptions.** If you're unsure whether a task should handle edge case X, make the bead's scope explicitly exclude it and note it as a potential follow-up. A bead that does less but does it right beats one that guesses wrong.

5. **Implementing agents: honor the markers.** When you encounter `[?]` on an AC, you MUST ask the user before implementing that behavior. Do not silently resolve it in either direction.

## Output Format

After completion, report:

```
## Beads Created: N total (X epics, Y tasks, Z subtasks)

### Quality Audit
- Beads scoring 4+: N/N (target: 100%)
- [list any beads that needed extra attention and why]

### Beads Needing Human Input
[List any beads where proposed ACs exceeded 30%, or where significant
ambiguity in the plan made self-contained descriptions impossible.
Include the specific open questions for each.]

### Critical Path
[blocker] → [blocked] → [blocked]

### Ready to Start
- bd-xxx: [Title] — [one-line summary of what agent will do]
- bd-yyy: [Title] — [one-line summary of what agent will do]

### Dependency Graph
[Brief visualization or description of the dep structure]
```

## Risk Tiers

| Operation | Tier | Behavior |
|-----------|------|----------|
| `br create` | SAFE | Auto-proceed |
| `br dep add` | SAFE | Auto-proceed |
| `br update --description` | CAUTION | Verify content |
| Bulk creation (>20 beads) | CAUTION | Confirm count first |

## Anti-Patterns

| Anti-Pattern | Why it's bad | Fix |
|-------------|-------------|-----|
| "Implement the pipeline stage" | Agent doesn't know WHAT to implement | Name the types, the function signatures, the test |
| "See plan for details" | Plan isn't available to the agent | Copy the relevant details INTO the bead |
| "Files: probably src/foo/" | Agent wastes time finding the right file | Search the codebase, confirm exact paths |
| "Should work correctly" | Not binary, not testable | "test_x passes" or "output matches Y" |
| No TDD anchor | Agent doesn't know where to start | Always specify the first test to write |
| "Depends on bd-xyz" (without context) | Agent doesn't know what bd-xyz provides | "Uses FooStruct and bar() function from bd-xyz" |
| Single-line description | Score 1 bead, agent is stuck | Use the full template, every section |
| Silently invented ACs | User surprised by implementation choices | Mark inferred ACs with [?], honor the 30% rule |
```