pb-refine

Apply feedback to an existing spec. This closes the gap between one-shot planning and iterative refinement.

Workflow

1. Locate and load the spec

• List specs/, find the directory ending with -<feature-name>; on multiple matches take the latest date prefix; on no match, report and stop (/pb-plan first).
• Load design.md, tasks.md, AGENTS.md (read-only).

2. Apply feedback to design.md

• If behavior changes, update the TDD & Mutation Testing Strategy section first (type contracts, invariants, test matrix, mutation scope).
• Mutation stays OFF by default. Update a task's Mutation: targets only when the revision changes core logic covered by an existing mutation tool; remove the field when it no longer applies. Never add it just to "be safe".
• Precise edits only — never rewrite whole files, preserve unaffected sections verbatim.
• Update Status → Revised, add a ## Revision History table entry (| Date | Change | Reason |).

3. Cascade to tasks.md

• Reset invalidated tasks: 🔄 DCR → 🔴 TODO, checkboxes back to - [ ].
• Add new tasks with the next free Task ID; obsolete tasks → ⛔ OBSOLETE.
• Update Context, Verification, Test Coverage where affected; keep Mutation: consistent with the revised core-logic scope or drop it.
• Never modify completed tasks (🟢 DONE) unless explicitly requested; if a change invalidates them, flag as a warning instead.

4. Validate and report

• Check alignment: every design change has tasks, dependencies stay ordered, no orphaned tasks.
• Run uv run pb-spec validate --plan <spec-dir> and fix errors.
• Summarize: what changed in design.md / tasks.md, warnings, and next step (/pb-build <feature>).

Decision protocol

Apply given feedback as stated — no multi-turn probing. If the feedback admits two or more genuinely incomparable interpretations that change what gets built, ask the user and wait; otherwise adopt the most reasonable interpretation, record it in Revision History, and proceed.

Edge cases

• No feedback provided → report "No feedback detected."
• Feedback requires an entirely new design → recommend /pb-plan instead.
• Multiple conflicting feedback items → apply in order given, note conflicts in Revision History.

Constraints

• Only modify specs/<spec-dir>/design.md and tasks.md. Never source code. AGENTS.md is read-only.
• Incremental update only — never re-run the full planning process.