Use when brainstorming/discovery phase is winding down, design document exists but confidence is low, finding new issues on every review cycle, or user micromanaging review process. Auto-triggers when brainstorming stalls. Also available via explicit /plan-hardening call.
Systematically validate a draft design until convergence (0 must-fix, 0 should-fix). Creates temporary tracker file during hardening; at finalization, all content migrates to main doc and tracker is deleted.
Entry: Brainstorming produced a draft design document Exit: Convergence achieved, tracker content merged to main doc, tracker deleted
digraph when_to_use {
"Design document exists?" [shape=diamond];
"Still discovering requirements?" [shape=diamond];
"Finding new issues each review?" [shape=diamond];
"Use brainstorming" [shape=box];
"Use plan-hardening" [shape=box];
"Ready for writing-plans" [shape=box];
"Design document exists?" -> "Use brainstorming" [label="no"];
"Design document exists?" -> "Still discovering requirements?" [label="yes"];
"Still discovering requirements?" -> "Use brainstorming" [label="yes"];
"Still discovering requirements?" -> "Finding new issues each review?" [label="no"];
"Finding new issues each review?" -> "Use plan-hardening" [label="yes"];
"Finding new issues each review?" -> "Ready for writing-plans" [label="no"];
}
Auto-trigger symptoms:
| # | Category | Focus |
|---|---|---|
| 1 | Gaps | Missing pieces, undefined behaviors, incomplete flows |
| 2 | Edge Cases | Boundary conditions, failure modes, error scenarios |
| 3 | Duplication | Code/data redundancy, maintainability concerns |
| 4 | Defensive Design | Optimistic assumptions, insufficient error handling |
| 5 | Resource Awareness | Memory, cost, quotas, limits, scalability |
| 6 | Impact Analysis | Existing features, models, tests, external dependencies |
| 7 | Best Practices | Market solutions, alternatives, code clarity, maintainability |
| 8 | Documentation | Inline docs needed, .md file consistency, stale context |
| 9 | Testing | E2E, integration, unit per project standards |
| 10 | Observability | Logging strategy, error tracking, debugging support |
| # | Category | When to Include |
|---|---|---|
| 11 | Security | Auth, permissions, user data, input validation, compliance |
| 12 | UX Best Practices | Frontend-heavy plans (includes i18n, accessibility) |
| 13 | Migration | Production-deployed features, data/schema/API changes |
| 14 | API Design | Building/modifying APIs (versioning, conventions, pagination) |
| 15 | Concurrency | Multi-threaded code, concurrent access, race conditions |
| 16 | Third-Party Integrations | External service dependencies (fallbacks, retries, circuits) |
| 17 | Caching Strategy | Systems with caching layers (invalidation, TTL, stale data) |
| 18 | Performance / Benchmarking | Performance-critical features (load testing, bottlenecks) |
At round start: Detect context, include relevant optional categories.
digraph dispatch {
"Initial round" [shape=box];
"All categories dirty" [shape=box];
"Dispatch dirty categories" [shape=box];
"Category found issues?" [shape=diamond];
"Mark passed" [shape=box];
"Keep dirty" [shape=box];
"Plan changed?" [shape=diamond];
"All categories -> dirty" [shape=box];
"Convergence?" [shape=diamond];
"Final pass (all categories)" [shape=box];
"Initial round" -> "All categories dirty";
"All categories dirty" -> "Dispatch dirty categories";
"Dispatch dirty categories" -> "Category found issues?";
"Category found issues?" -> "Mark passed" [label="no"];
"Category found issues?" -> "Keep dirty" [label="yes"];
"Mark passed" -> "Plan changed?";
"Keep dirty" -> "Plan changed?";
"Plan changed?" -> "All categories -> dirty" [label="yes"];
"Plan changed?" -> "Convergence?" [label="no"];
"All categories -> dirty" -> "Dispatch dirty categories";
"Convergence?" -> "Final pass (all categories)" [label="yes"];
"Convergence?" -> "Dispatch dirty categories" [label="no"];
}
Token optimization: Categories with 0 findings marked passed, skip subsequent rounds unless plan changes.
Create docs/plans/{plan-name}-tracker.md alongside design document:
## Category Status
| Category | State | Last Run | Findings |
|----------|-------|----------|----------|
## Open Issues
| ID | Severity | Category | Description | Status |
## Resolved
| ID | Severity | Category | Description | Resolution |
## Won't Do
| ID | Severity | Category | Description | Rationale |
## Deferred
| ID | Severity | Category | Description | Why Deferred |
## Future Work
| ID | Category | Description | Prerequisites |
Tracker is temporary scaffolding. At finalization: content migrates to main doc, tracker file deleted.
Rules:
won't_do requires documented rationaledeferred requires documented reasonfuture requires prerequisites| Severity | Meaning | Gate |
|---|---|---|
| must-fix | Blocks implementation | Must be 0 to converge |
| should-fix | Important but not blocking | Must be 0 to converge |
| nice-to-have | Improvement opportunity | Move to Future Work |
| Round | Expected |
|---|---|
| 1 | Many issues (normal) |
| 2 | Fewer (root causes fixed) |
| 3 | Should be clean |
| 3+ with must/should-fix | Design flaw, revisit architecture |
Convergence = Round with 0 new must-fix AND 0 new should-fix
Before writing final document version:
Memory Sweep - Review full conversation, compaction summary, look for leftover definitions, unsolved questions
Tracker Audit - Verify 0 open issues, all won't_do/deferred/future have required fields
Document Completeness - Has all required sections including Future Work, Deferred, Won't Do, Key Decisions?
Final Agent Pass - All categories (core + applicable optional), must find 0 must-fix/should-fix
Finalization Mindset - Internal state: "Session closes after commit, everything not written is lost forever"
Merge & Delete Tracker - Move all tracker content to main doc sections, delete tracker file
# [Feature] - Design Document
## Status: FINAL
## Problem Statement
## Data Model
## Implementation Flow
## Edge Cases
## Testing Plan
## Files to Change
## Key Decisions Made (with rationale)
## Deferred (with reasons)
## Future Work (with prerequisites)
## Out of Scope / Won't Do (with rationale)
| Behavior | Block |
|---|---|
| "Ready to finish?" before convergence | Gate: 0 must-fix, 0 should-fix |
| Lost issues | Persistent tracker during hardening |
| Ad-hoc agent dispatch | Defined category set |
| Undocumented "won't do" | Required rationale field |
| Discarded nice-to-haves | Must go to Future Work |
| Re-raising resolved issues | In tracker/doc with resolution |
| Rushing to code | Pre-finalization ritual enforced |
| Orphan tracker file | Deleted at finalization |