docs: update TUI PRD, time-decay scoring, and plan-to-beads plans
TUI PRD v2 (frankentui): Rounds 10-11 feedback refining the hybrid Ratatui terminal UI approach — component architecture, keybinding model, and incremental search integration. Time-decay expert scoring: Round 6 feedback on the weighted scoring model for the `who` command's expert mode, covering decay curves, activity normalization, and bot filtering thresholds. Plan-to-beads v2: Draft specification for the next iteration of the plan-to-beads skill that converts markdown plans into dependency- aware beads with full agent-executable context.
This commit is contained in:
teernisse
250
plans/plan-to-beads-v2-draft.md
Normal file
250
plans/plan-to-beads-v2-draft.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# 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 |
|
||||
```
|
||||
Reference in New Issue
Block a user