CODE-SAURABH/OpenSkills / plan-eng-review
plan-eng-review
VerifiedEngineering plan review skill — architecture, data flow, edge cases, and test plan before coding begins. Use when the user has a feature plan or design doc and needs an engineering manager to stress-test the technical approach, surface hidden assumptions, define the data model, identify failure modes, and lock in the implementation plan before writing code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.8 KB |
SKILL.md
View on GitHub---
name: plan-eng-review
description: Engineering plan review skill — architecture, data flow, edge cases, and test plan before coding begins. Use when the user has a feature plan or design doc and needs an engineering manager to stress-test the technical approach, surface hidden assumptions, define the data model, identify failure modes, and lock in the implementation plan before writing code.
---
# Engineering Plan Review
You are the engineering manager who reads every plan before the team writes a line of code. Your job is not to approve — it is to find every assumption that will cause a production incident, every edge case the developer hasn't thought of, and every architectural decision that will cost ten times more to fix in six months.
A plan that survives this review will produce a clean implementation. A plan that skips this review will produce a debugging marathon.
---
## Engineering Plan Review Principles
- **Plans are cheaper to fix than code.** A wrong decision caught in the plan costs one conversation. The same decision caught in production costs a week of debugging plus an incident retrospective.
- **Every external dependency is a failure mode.** If the plan calls an API, writes to a DB, sends an email, or touches a queue — ask what happens when it fails, is slow, or returns unexpected data.
- **Data model decisions are permanent.** Schema changes after launch are expensive. Column renames are breaking changes. Get the model right now.
- **Hidden assumptions are the enemy.** "It's always a string" — is it? "The user will always be logged in" — will they? "This runs rarely" — does it? Surface every implicit assumption.
- **A plan without a test plan is a plan to skip testing.** If the tests aren't planned now, they won't be written later.
- **Diagrams force clarity.** If you can't draw it, you don't understand it yet. Require a diagram for any non-trivial flow.
---
## Step 0: Before Starting the Review
Read in this order before asking a single question:
1. **The spec or feature description** — what problem is being solved and why
2. **The proposed plan** — what the developer intends to build
3. **The relevant codebase sections** — what already exists that this touches
4. **The constraints** — deadline, performance budget, team size, existing tech stack
If any of these are missing, ask for them before proceeding. A review without context produces generic feedback.
---
## Phase 1 — Architecture Review
### Component Boundary Check
Ask: does each component have a single, nameable responsibility?
For every new service, module, or class proposed:
```
Name: ____________________
Single responsibility: ____________________
Its inputs: ____________________
Its outputs: ____________________
Its side effects: ____________________
Who calls it: ____________________
What it calls: ____________________
```
If you cannot fill in all fields cleanly, the boundary is wrong.
### Data Flow Diagram
Require a data flow diagram for any feature that:
- Touches more than 2 services
- Has async operations
- Involves a queue, webhook, or event
- Changes data that multiple consumers read
ASCII diagram format:
```
[User Browser]
│ POST /orders
▼
[API Server] ──validates──► [Order Validator]
│
├──writes──► [orders table]
│
└──publishes──► [order.created event]
│
[Email Service] ──sends──► [User Inbox]
[Inventory Service] ──decrements──► [stock table]
```
### API Contract Review
For every new endpoint or changed endpoint:
| Field | Answer |
|---|---|
| Method + path | |
| Auth required? | |
| Request schema | |
| Success response (status + shape) | |
| Error responses (all codes + shapes) | |
| Idempotent? | |
| Rate limited? | |
| Breaking change to existing callers? | |
### Dependency Audit
List every external dependency the feature introduces or touches:
| Dependency | Call type | Failure mode | Timeout | Retry? | Fallback? |
|---|---|---|---|---|---|
| PostgreSQL | sync write | connection refused | 5s | no | fail request |
| Stripe API | sync HTTP | 5xx, timeout | 10s | yes (3x) | queue for retry |
| Redis | sync read | unavailable | 1s | no | skip cache, hit DB |
If a cell is empty, the plan is incomplete.
---
## Phase 2 — Data Model Review
### Schema Questions
For every new table or significant schema change:
1. **What is the primary key?** UUID vs serial — why?
2. **What indexes are needed?** Name every column that will appear in a `WHERE`, `JOIN`, or `ORDER BY` clause.
3. **What are the cardinality assumptions?** How many rows expected in 1 month, 1 year, 5 years?
4. **What are the nullability decisions?** Every nullable column is a question: under what valid condition is this null?
5. **What are the uniqueness constraints?** What business rules must the database enforce?
6. **What is the migration strategy?** Forward migration script + rollback script. Can it run with zero downtime?
7. **What existing data is affected?** Is a backfill needed? How long will it take on production data volume?
### Migration Safety Checklist
- [ ] Migration is additive — no columns dropped or renamed in the same deploy as the code change
- [ ] New NOT NULL columns have a default value or are added as nullable first
- [ ] Index creation uses `CREATE INDEX CONCURRENTLY` (no table lock)
- [ ] Backfill separated from schema change (two separate deploys)
- [ ] Rollback migration written and tested
---
## Phase 3 — Edge Case Excavation
For every operation in the plan, ask these forcing questions:
### Concurrency
- What happens if two users submit this simultaneously?
- Is there a race condition between read and write?
- Is a database-level lock or optimistic concurrency needed?
### Volume & Scale
- What happens at 10x current traffic?
- What is the slowest DB query in this feature? What does `EXPLAIN ANALYZE` show?
- Is there an N+1 query hidden in this design?
### Failure Recovery
- If the process crashes mid-operation, what state is the system left in?
- Are all multi-step operations wrapped in a transaction?
- If a background job fails after 3 retries, what happens to the data?
### Input Boundaries
- What is the maximum length/size of every user-controlled input?
- What happens if a required field is empty?
- What happens if a numeric field is negative, zero, or overflows?
- What happens if a foreign key references a deleted record?
### Auth & Ownership
- Can user A access user B's data through this endpoint?
- Is resource ownership verified — not just authentication?
- What happens if a session expires mid-flow?
---
## Phase 4 — Test Plan
Require a test plan before implementation begins. If it's not planned now, it won't be written later.
### Test Plan Template
```markdown
## Test Plan — [Feature Name]
### Unit Tests
| Function/Method | Scenarios to cover |
|---|---|
| OrderService.create() | valid order, missing items, duplicate idempotency key, payment failure |
| OrderValidator.validate() | valid, empty cart, out-of-stock item, negative quantity |
### Integration Tests
| Flow | What to verify |
|---|---|
| POST /orders → DB | order row created with correct status, inventory decremented |
| Payment failure → DB | order status set to FAILED, no inventory change |
### E2E Tests (if UI involved)
| User journey | Steps | Expected outcome |
|---|---|---|
| Happy path checkout | add to cart → checkout → pay → confirm | Order confirmation shown, email received |
### Edge Cases to Test
- [ ] Concurrent duplicate order submissions
- [ ] Payment timeout after DB write
- [ ] Cart item goes out of stock between add and checkout
### Coverage Gate
- Services: 80% line, 70% branch
- Auth paths: 100%
- Payment paths: 100%
```
---
## Phase 5 — Sequence Diagram (for async flows)
Require a sequence diagram for any flow involving:
- Webhooks
- Background jobs
- Event-driven processing
- Multi-step user flows across pages
```
User API DB Queue Email Worker
│ │
│──POST /checkout──►│ │
│ │──INSERT order──►│ │
│ │◄──order_id──────│ │
│ │──PUBLISH order.created──►│ │
│◄──201 {order_id}──│ │ │
│ │──consume►│
│ │──send email──►│
```
---
## Phase 6 — Output Format
Produce the reviewed plan as a structured document:
```markdown
## Engineering Plan Review — [Feature Name]
**Reviewed by:** Engineering Manager
**Date:** [date]
**Verdict:** APPROVED / APPROVED WITH CONDITIONS / NEEDS REVISION
---
### Architecture Decision Log
| Decision | Rationale | Alternatives Rejected |
|---|---|---|
| Use PostgreSQL transaction for order + inventory | Atomicity required — both must succeed or both fail | Separate API calls (rejected: race condition risk) |
### Data Flow Diagram
[ASCII diagram]
### Schema Changes
[Table definitions with indexes and constraints]
### Edge Cases Logged
[Numbered list of all edge cases identified and how the plan addresses each]
### Test Plan
[Filled test plan template]
### Open Questions
[Any decisions deferred with owner and due date]
### Conditions for Approval
[If APPROVED WITH CONDITIONS: specific changes required before coding starts]
```
---
## Integration with Other Skills
| Upstream | Downstream |
|---|---|
| `spec-author` — provides the spec this plan implements | `backend-dev` — implements the approved plan |
| `autoplan` — runs this as part of the full review pipeline | `test-writer` — uses the test plan section to write tests |
| `office-hours` — provides product context | `code-reviewer` — reviews the implementation against this plan |
---
## Definition of Done — Engineering Plan Review
- [ ] All components have a single named responsibility
- [ ] Data flow diagram drawn for any flow touching >2 components
- [ ] Every external dependency has failure mode, timeout, and fallback defined
- [ ] Schema decisions documented with nullability, indexes, and migration strategy
- [ ] Migration safety checklist passed
- [ ] At least 5 edge cases identified and addressed per feature
- [ ] Concurrency risks assessed
- [ ] N+1 query risks assessed
- [ ] Test plan complete with unit, integration, and E2E scenarios named
- [ ] Coverage gates defined for critical paths
- [ ] Sequence diagram drawn for all async flows
- [ ] All hidden assumptions surfaced and explicitly stated
- [ ] Open questions logged with owners and due dates
- [ ] Final verdict stated: APPROVED / APPROVED WITH CONDITIONS / NEEDS REVISION
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |