implementation-plan-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# Implementation Plan Review Skill
## Goal
Review implementation plans like a senior engineer responsible for deploying the system in production at 2am.
This skill reviews:
- Claude Code plans
- Codex execution plans
- Engineering rollout plans
- Multi-phase implementation plans
This skill does NOT:
- Review code quality
- Re-review the original spec
- Nitpick naming/style
- Suggest architecture redesign unless execution is unsafe
Core question:
> "Is this implementation plan safe, complete, correctly ordered, and realistic before code changes begin?"
Focus on:
- rollout safety
- dependency sequencing
- migration safety
- operational risk
- missing execution steps
- production compatibility
- implementation realism
---
# Core Principles
- Order matters more than completeness
- Ambiguous steps become production outages
- Missing rollback = production risk
- Incremental rollout is safer than big-bang deploys
- DB changes are highest-risk
- Never assume undocumented behavior
- Validate against the actual repository structure
- Plans must be executable, not theoretical
---
# Review Flow
Review in this order:
1. Spec coverage
2. Execution phases
3. Dependency sequencing
4. Migration safety
5. Rollback strategy
6. Operational readiness
7. Testing strategy
8. Repository realism
---
# Step 1 — Validate Spec Coverage
Read the approved spec first.
Build a checklist of:
- schema changes
- endpoints
- UI changes
- background jobs
- migrations
- configs
- done criteria
Then verify every item exists in the implementation plan.
## Required Checks
- [ ] Every schema change has a plan step
- [ ] Every endpoint has a plan step
- [ ] Every frontend change has a plan step
- [ ] Every migration/backfill is included
- [ ] Every operational/config change included
- [ ] Every done criterion addressed
## Missing Coverage Detection
Flag:
- missing endpoints
- missing migrations
- missing cleanup
- missing deployment steps
- missing startup hooks
- missing monitoring/logging
- missing test updates
If no spec exists:
> "No approved spec provided. Coverage validation limited."
---
# Step 2 — Validate Execution Phases
Safe rollout order:
```
Phase 1 — additive DB changes
Phase 2 — backend compatibility
Phase 3 — frontend rollout
Phase 4 — migration/backfill
Phase 5 — cleanup/removal
```
Check:
- [ ] DB schema changes before backend code that depends on them
- [ ] Backend endpoints exist before frontend calls them
- [ ] Backfill runs before NOT NULL constraints added
- [ ] Startup hooks added before features that depend on them
- [ ] Old code remains functional during transition
- [ ] Cleanup/removal is last, never first
- [ ] No step assumes a future step has already run
---
# Step 3 — Validate Dependency Sequencing
For each step ask:
- What does this step depend on?
- Is that dependency already completed at this point?
- Does anything else depend on this step?
Check:
- [ ] No circular dependencies
- [ ] Each step's prerequisites are explicit
- [ ] Parallel steps are truly independent
- [ ] Shared utilities modified safely without breaking existing callers
- [ ] API contract changes backward compatible during transition
---
# Step 4 — Migration Safety
Highest-risk area. Check every migration step:
- [ ] Additive only — ADD COLUMN not DROP + RECREATE
- [ ] Idempotent — safe to run twice
- [ ] Backfill before constraints
- [ ] No NOT NULL without default or backfill first
- [ ] CASCADE DELETE intentional and documented
- [ ] FK columns indexed after creation
- [ ] Large table migrations flagged (locking risk)
- [ ] Rollback SQL provided
- [ ] Location specified (Supabase editor, migration file, startup script)
Common failure patterns to detect:
- Adding NOT NULL before backfill
- Forgetting to index new FK columns
- Running app code before migration completes

From zoharp/claude-skills, MIT.

More from zoharp/claude-skills