Code Plan Audit
Plan Completeness Scorecard
| # |
Check |
Severity |
| 1 |
Problem clearly stated with concrete requirements |
Critical |
| 2 |
Acceptance criteria are testable (not vague adjectives) |
Critical |
| 3 |
Error handling strategy defined (propagate, recover, or fail) |
Critical |
| 4 |
Key tradeoffs identified and documented |
Warning |
| 5 |
Testing strategy chosen (unit/integration/E2E proportions) |
Warning |
| 6 |
Dependencies and integration points identified |
Warning |
| 7 |
Naming conventions and readability approach consistent |
Warning |
| 8 |
Security boundaries identified (input validation, auth, data exposure) |
Warning |
| 9 |
Scope bounded — deferred items explicitly listed |
Note |
| 10 |
Existing solutions checked (libraries, shared code, prior art) |
Note |
Scoring: 10/10 = ready to build. 7-9 = minor gaps, address before starting. 4-6 = return to planning. <4 = needs fundamental design work.
Actionability Tests
Five tests every plan item must pass before implementation:
| Test |
Pass Criteria |
| Verb Test |
Active verbs (create, validate, transform), not vague ("handle", "manage", "deal with") |
| Scope Test |
Clear boundaries — you know when each task is done |
| Test Test |
Testable acceptance criteria, not adjectives ("fast", "clean", "robust") |
| Dependency Test |
Clear ordering — no hidden assumptions about what runs first |
| Edge Case Test |
At least: empty input, invalid input, concurrent access (if applicable) |
Code Quality Pre-Checks
Readability Pre-Check
| Signal |
Question |
If No |
| Naming intent |
Does the plan use domain-specific names? |
Clarify domain vocabulary before coding |
| Layer clarity |
Are abstraction layers described? |
Define boundaries before coding |
| Single responsibility |
Can each component be described in one sentence without "and"? |
Split components |
Error Handling Strategy Check
| Question |
If Missing |
| Which errors are expected vs. unexpected? |
Define: "not found" is expected; "DB down" is unexpected |
| Where are system boundaries? |
Map validation points |
| What's the recovery strategy for each failure mode? |
Decide: retry, fallback, propagate, or fail fast |
| Are error messages actionable for the caller? |
Plan error types and messages |
Modularity Pre-Check
| Signal |
Question |
If No |
| Single concern |
Does each module handle one distinct problem? |
Reassess responsibilities |
| Dependency direction |
Do dependencies flow one way? |
Identify circular risks |
| Interface boundaries |
Are public APIs defined separately from implementation? |
Design contracts first |
| Testability |
Can each component be tested without complex setup? |
Redesign for dependency injection |
Plan-Level Antipatterns
| Antipattern |
Symptom in Plan |
Severity |
| The Fog |
Adjectives without verbs ("robust auth", "clean API") |
Critical |
| The Wishlist |
Describes the final vision, no phased delivery |
Warning |
| The Monolith |
Everything in one component, no separation |
Warning |
| The Oracle |
Assumes perfect knowledge of future requirements |
Warning |
| The Clone |
"Like X but..." without understanding X's design decisions |
Warning |
| Missing Error Story |
Happy path only — no error handling, no edge cases |
Critical |
Implementation Risk Signals
| Plan Signal |
Predicts |
Prevention |
| No domain types mentioned |
Primitive obsession |
Plan dedicated types for constrained values |
| "Handle errors" without specifics |
Silent failure |
Define error categories and recovery per boundary |
| Single class/module for multiple concerns |
God object |
Split responsibilities before coding |
| "Optimize for performance" without metrics |
Premature optimization |
Define performance targets with measurement plan |
| Interface defined before second use case |
Premature abstraction |
Start concrete, extract interface when needed |
"Is This Plan Ready to Build?"
| # |
Question |
If No |
| 1 |
Can you state what the code does in one sentence? |
STOP — Define the problem and deliverable |
| 2 |
Do acceptance criteria pass the Test Test? |
STOP — Rewrite criteria as verifiable assertions |
| 3 |
Is error handling strategy defined for each system boundary? |
STOP — Map boundaries and failure modes |
| 4 |
Is the testing approach proportional to the risk? |
STOP — Define test levels and critical paths |
| 5 |
Is at least one design tradeoff documented with alternatives? |
STOP — Record reasoning for key decisions |
All five "Yes" -> READY TO BUILD. Start with the highest-risk component.
Quick Pre-Implementation Gate
Run this 60-second check before writing any code:
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: code-plan-audit3description: Plan quality auditing with completeness scorecard, antipattern risk detection, and readiness checks. Use when auditing implementation plans, evaluating plan completeness, checking error handling strategy, assessing naming and readability pre-checks, reviewing testing strategy, evaluating tradeoff documentation, or running plan-audit on a software project. Covers the 10-point completeness scorecard, code quality pre-checks, antipattern risk assessment, and build-readiness decision. Use when this capability is needed.4---56# Code Plan Audit78## Plan Completeness Scorecard910| # | Check | Severity |11|---|-------|----------|12| 1 | Problem clearly stated with concrete requirements | Critical |13| 2 | Acceptance criteria are testable (not vague adjectives) | Critical |14| 3 | Error handling strategy defined (propagate, recover, or fail) | Critical |15| 4 | Key tradeoffs identified and documented | Warning |16| 5 | Testing strategy chosen (unit/integration/E2E proportions) | Warning |17| 6 | Dependencies and integration points identified | Warning |18| 7 | Naming conventions and readability approach consistent | Warning |19| 8 | Security boundaries identified (input validation, auth, data exposure) | Warning |20| 9 | Scope bounded — deferred items explicitly listed | Note |21| 10 | Existing solutions checked (libraries, shared code, prior art) | Note |2223**Scoring:** 10/10 = ready to build. 7-9 = minor gaps, address before starting. 4-6 = return to planning. <4 = needs fundamental design work.2425## Actionability Tests2627Five tests every plan item must pass before implementation:2829| Test | Pass Criteria |30|------|---------------|31| **Verb Test** | Active verbs (create, validate, transform), not vague ("handle", "manage", "deal with") |32| **Scope Test** | Clear boundaries — you know when each task is done |33| **Test Test** | Testable acceptance criteria, not adjectives ("fast", "clean", "robust") |34| **Dependency Test** | Clear ordering — no hidden assumptions about what runs first |35| **Edge Case Test** | At least: empty input, invalid input, concurrent access (if applicable) |3637## Code Quality Pre-Checks3839### Readability Pre-Check4041| Signal | Question | If No |42|--------|----------|-------|43| Naming intent | Does the plan use domain-specific names? | Clarify domain vocabulary before coding |44| Layer clarity | Are abstraction layers described? | Define boundaries before coding |45| Single responsibility | Can each component be described in one sentence without "and"? | Split components |4647### Error Handling Strategy Check4849| Question | If Missing |50|----------|-----------|51| Which errors are expected vs. unexpected? | Define: "not found" is expected; "DB down" is unexpected |52| Where are system boundaries? | Map validation points |53| What's the recovery strategy for each failure mode? | Decide: retry, fallback, propagate, or fail fast |54| Are error messages actionable for the caller? | Plan error types and messages |5556### Modularity Pre-Check5758| Signal | Question | If No |59|--------|----------|-------|60| Single concern | Does each module handle one distinct problem? | Reassess responsibilities |61| Dependency direction | Do dependencies flow one way? | Identify circular risks |62| Interface boundaries | Are public APIs defined separately from implementation? | Design contracts first |63| Testability | Can each component be tested without complex setup? | Redesign for dependency injection |6465## Plan-Level Antipatterns6667| Antipattern | Symptom in Plan | Severity |68|-------------|----------------|----------|69| **The Fog** | Adjectives without verbs ("robust auth", "clean API") | Critical |70| **The Wishlist** | Describes the final vision, no phased delivery | Warning |71| **The Monolith** | Everything in one component, no separation | Warning |72| **The Oracle** | Assumes perfect knowledge of future requirements | Warning |73| **The Clone** | "Like X but..." without understanding X's design decisions | Warning |74| **Missing Error Story** | Happy path only — no error handling, no edge cases | Critical |7576## Implementation Risk Signals7778| Plan Signal | Predicts | Prevention |79|-------------|----------|------------|80| No domain types mentioned | Primitive obsession | Plan dedicated types for constrained values |81| "Handle errors" without specifics | Silent failure | Define error categories and recovery per boundary |82| Single class/module for multiple concerns | God object | Split responsibilities before coding |83| "Optimize for performance" without metrics | Premature optimization | Define performance targets with measurement plan |84| Interface defined before second use case | Premature abstraction | Start concrete, extract interface when needed |8586## "Is This Plan Ready to Build?"8788| # | Question | If No |89|---|----------|-------|90| 1 | Can you state what the code does in one sentence? | **STOP** — Define the problem and deliverable |91| 2 | Do acceptance criteria pass the Test Test? | **STOP** — Rewrite criteria as verifiable assertions |92| 3 | Is error handling strategy defined for each system boundary? | **STOP** — Map boundaries and failure modes |93| 4 | Is the testing approach proportional to the risk? | **STOP** — Define test levels and critical paths |94| 5 | Is at least one design tradeoff documented with alternatives? | **STOP** — Record reasoning for key decisions |9596All five "Yes" -> **READY TO BUILD.** Start with the highest-risk component.9798## Quick Pre-Implementation Gate99100Run this 60-second check before writing any code:101102- [ ] I can state the deliverable in one sentence103- [ ] I know the first test I'll write104- [ ] I know what errors I'll handle and how105- [ ] I know what I'm *not* building (scope boundary)106107---108> Converted and distributed by [TomeVault](https://tomevault.io/claim/smileynet) — claim your Tome and manage your conversions.109<!-- tomevault:4.0:skill_md:2026-04-14 -->
tomevault-io