Thoroughly review an engineering plan before any code is written. Combines an engineering review (architecture, code quality, tests, performance) with mode selection for scope posture. Interactive: one issue per question, opinionated recommendations, required completion summary. ---
Install via CLI
openskills install SeongwoongCho/adaptive-harness# Plan Review Skill
Thoroughly review an engineering plan before any code is written. Combines an engineering review (architecture, code quality, tests, performance) with mode selection for scope posture. Interactive: one issue per question, opinionated recommendations, required completion summary.
---
## Steps
### Phase 0: Scope Challenge
1. **Before reviewing anything, answer these questions:**
- What existing code already partially or fully solves each sub-problem?
- What is the minimum set of changes that achieves the stated goal?
- Does the plan touch more than 8 files or introduce more than 2 new classes? Flag as a smell.
2. **Ask user to choose scope posture:**
- A) **SCOPE REDUCTION** — propose a minimal version; review that
- B) **HOLD SCOPE** — accept the plan's scope; make it bulletproof
- C) **SCOPE EXPANSION** — push scope up; ask what would make this 10x better
If user does not choose SCOPE REDUCTION: respect that decision fully. Do not re-argue for less scope in later sections.
---
### Phase 1: Four Review Sections
For each section: find issues, then for each issue call a separate question. Never batch.
Each issue question format:
- Describe problem concretely with file/line references
- Present 2-3 options (A, B, C); label with issue number + option letter (e.g., "1A", "1B")
- Lead with your recommendation: "We recommend B. Here's why..."
- Map reasoning to engineering preferences (DRY, explicit > clever, minimal diff)
**Stop after each section.** Move to next only after all issues in current section are resolved.
3. **Architecture review**
- System design and component boundaries
- Dependency graph and coupling
- Data flow and bottlenecks
- Security architecture (auth, data access, API boundaries)
- One realistic production failure scenario per new codepath
4. **Code quality review**
- DRY violations — be aggressive
- Error handling and missing edge cases
- Over-engineered or under-engineered areas
- Naming, coupling, magic values
5. **Test review**
- Diagram all new UX flows, codepaths, and branching logic
- For each new item in the diagram: confirm a test exists or flag the gap
- Acceptance: every new codepath has at least one test covering the happy path and one covering failure
6. **Performance review**
- N+1 queries and database access patterns
- Memory usage concerns
- Caching opportunities
- Slow or high-complexity code paths
---
### Phase 2: Required Outputs
7. **"NOT in scope" section**
- List every item considered and explicitly deferred
- One-line rationale per item
8. **"What already exists" section**
- List existing code that partially solves sub-problems in this plan
- Note whether the plan reuses or unnecessarily rebuilds each
9. **TODOS.md proposals**
- Present each potential TODO as a separate question — never batch
- For each: What, Why, Pros, Cons, Context, Depends on
- Options: A) Add to TODOS.md, B) Skip, C) Build now in this PR
10. **Failure mode analysis**
- For each new codepath: one realistic production failure (timeout, nil reference, race condition)
- Flag as critical gap if: no test AND no error handling AND would be silent failure
11. **Completion summary**
```
Step 0: Scope Challenge (user chose: ___)
Architecture Review: ___ issues found
Code Quality Review: ___ issues found
Test Review: diagram produced, ___ gaps identified
Performance Review: ___ issues found
NOT in scope: written
What already exists: written
TODOS.md updates: ___ items proposed
Failure modes: ___ critical gaps flagged
```
---
## Rules
- Read-only — never modify any files
- One issue = one question — never batch multiple issues
- Lead with your recommendation — be opinionated ("Do B. Here's why:")
- If a section has no issues: say so and move on
- After scope posture is agreed: commit to making that scope succeed
- Unresolved decisions: list at end as "Decisions left unresolved that may bite you later"
No comments yet. Be the first to comment!