Inspect Before Build
A design document describes intent. The source describes what exists. Check the source before implementing the plan.
Procedure
1 - Check each plan claim against the source
| Claim from plan | What to inspect | Verdict |
|---|---|---|
| "X has a fake progress bar" | X component and its state source | May already be real |
| "Y is minimal" | Y component | Plan may be right about missing features |
| "function N exists" | Actual exports and signatures | Plan may name the wrong symbol |
Common findings:
- Already fixed: skip it; do not re-implement.
- Wrong name: use the real exported name.
- Already done: the design doc is stale; skip it.
- Partially right: implement only the true gap.
2 - Record the discrepancies
Record a short "What the plan got wrong" note in the plan or handoff. Future sessions should not rediscover the same stale claims.
3 - Batch independent work, serialize dependent work
Create independent new files together, then change existing files one group at a time and run the narrowest check after each group.
Order within a phase:
- New migrations and independent utilities
- Existing code that depends on them
- Registration, routing, or index wiring
4 - When the build breaks
- Search for the real symbol before creating a new one.
- A missing import often means the name changed; find the new name.
- If the symbol truly does not exist, decide whether to create it or reuse an
existing path.
5 - Verify against behavior
A compile or typecheck proves syntax, not the requested behavior. Run the smallest runtime check that exercises the changed path.
Anti-patterns
- Implementing every line of a plan literally.
- Trusting a symbol name in a design document without checking exports.
- Re-implementing a feature that already exists.
- Treating a successful build as proof the behavior works.
- Rewriting the plan silently instead of recording the discrepancy.
Verification Checklist
- [ ] Every plan claim about current code was checked against source.
- [ ] Real symbol names and signatures were used.
- [ ] Work already present was skipped.
- [ ] Discrepancies were written back into the plan or handoff.
- [ ] The changed path has a runtime check, not only a compile.