Invariant Principles
- Specification sufficiency determines implementation success. Underspecified designs force implementers to guess, causing divergent implementations and rework.
- Method names are suggestions, not contracts. Inferred behavior from naming is fabrication until verified against source.
- Vague language masks missing decisions. "Standard approach", "as needed", "TBD" defer design work to implementation phase where it costs 10x more.
- Complete != comprehensive. Document completeness means every item either specified or explicitly N/A with justification.
Inputs
| Input | Required | Description | |-------|----------|-------------| | Design document | Yes | Markdown/text file containing technical specification, architecture doc, or design proposal | | Source codebase | No | Existing code to verify interface claims against | | Implementation context | No | Target platform, constraints, prior decisions |
Outputs
| Output | Type | Description | |--------|------|-------------| | Findings report | Inline | Scored inventory with SPECIFIED/VAGUE/MISSING verdicts per category | | Remediation plan | Inline | Prioritized P1/P2/P3 fixes with acceptance criteria | | Factcheck escalations | Inline | Claims requiring verification before implementation |
Reasoning Schema
<analysis>
[Document section under review]
[Specific claim or specification]
[What implementation decision this enables or blocks]
</analysis>
<reflection>
[Could I code against this RIGHT NOW?]
[What would I have to invent/guess?]
[Verdict: SPECIFIED | VAGUE | MISSING]
</reflection>
Phase 1: Document Inventory
## Sections: [name] - lines X-Y
## Components: [name] - location
## Dependencies: [name] - version: Y/N
## Diagrams: [type] - line X
Phase 2: Completeness Checklist
Mark: SPECIFIED | VAGUE | MISSING | N/A (justify N/A)
| Category | Items |
|----------|-------|
| Architecture | System diagram, component boundaries, data flow, control flow, state management, sync/async boundaries |
| Data | Models with field specs, schema, validation rules, transformations, storage formats |
| API/Protocol | Endpoints, request/response schemas, error codes, auth, rate limits, versioning |
| Filesystem | Directory structure, module responsibilities, naming conventions, key classes, imports |
| Errors | Categories, propagation paths, recovery mechanisms, retry policies, failure modes |
| Edge Cases | Enumerated cases, boundary conditions, null handling, max limits, concurrency |
| Dependencies | All listed, version constraints, fallback behavior, API contracts |
| Migration | Steps, rollback, data migration, backwards compat (or N/A - BREAKING OK) |
REST API Design Checklist
<RULE> Apply this checklist when API/Protocol category is marked SPECIFIED or VAGUE. These items encode Richardson Maturity Model, Postel's Law, and Hyrum's Law considerations. </RULE>Richardson Maturity Model (Level 2+ required for "SPECIFIED"):
| Level | Requirement | Check |
|-------|-------------|-------|
| L0 | Single endpoint, POST everything | Reject as VAGUE |
| L1 | Resources identified by URIs | /users/123 not /getUser?id=123 |
| L2 | HTTP verbs used correctly | GET=read, POST=create, PUT=replace, PATCH=update, DELETE=remove |
| L3 | HATEOAS (hypermedia) | Optional but note if claimed |
Postel's Law Compliance:
"Be conservative in what you send, be liberal in what you accept"
| Aspect | Check | |--------|-------| | Request validation | Specified: required fields, optional fields, extra field handling | | Response structure | Specified: guaranteed fields, optional fields, extension points | | Versioning | Specified: how backwards compatibility maintained | | Deprecation | Specified: how deprecated fields/endpoints communicated |
Hyrum's Law Awareness:
"With sufficient users, all observable behaviors become dependencies"
Flag these as requiring explicit specification:
- Response field ordering (clients may depend on it)
- Error message text (clients may parse it)
- Timing/performance characteristics (clients may assume them)
- Default values (clients may rely on them)
API Specification Checklist:
[ ] HTTP methods match CRUD semantics
[ ] Resource URIs are nouns, not verbs
[ ] Versioning strategy specified (URL, header, or content-type)
[ ] Authentication mechanism documented
[ ] Rate limiting specified (limits, headers, retry-after)
[ ] Error response schema consistent across endpoints
[ ] Pagination strategy for list endpoints
[ ] Filtering/sorting parameters documented
[ ] Request size limits specified
[ ] Timeout expectations documented
[ ] Idempotency requirements for non-GET methods
[ ] CORS policy if browser-accessible
Error Response Standard:
Verify error responses specify:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable message",
"details": [{"field": "email", "issue": "invalid format"}]
}
}
Mark VAGUE if: error format varies by endpoint or leaves structure to implementation.
Phase 3: Hand-Waving Detection
Vague Language
Flag: "etc.", "as needed", "TBD", "implementation detail", "standard approach", "straightforward", "details omitted"
Format: **Vague #N** | Loc: [X] | Text: "[quote]" | Missing: [specific]
Assumed Knowledge
Unspecified: algorithm choices, data structures, config values, naming conventions
Magic Numbers
Unjustified: buffer sizes, timeouts, retry counts, rate limits, thresholds
Phase 4: Interface Verification
<analysis> INFERRED BEHAVIOR IS NOT VERIFIED BEHAVIOR. `assert_model_updated(model, field=value)` might assert only those fields, require ALL changes, or behave differently. </analysis> <reflection> YOU DO NOT KNOW until you READ THE SOURCE. </reflection>Fabrication Anti-Pattern
| Wrong | Right | |-------|-------| | Assume from name | Read docstring, source | | Code fails → invent parameter | Find usage examples | | Keep inventing | Write from VERIFIED behavior |
Verification Table
| Interface | Verified/Assumed | Source Read | Notes | |-----------|-----------------|-------------|-------|
Every ASSUMED = critical gap.
Factchecker Escalation
Trigger: security claims, performance claims, concurrency claims, numeric claims, external references
Format: **Escalate:** [claim] | Loc: [X] | Category: [Y] | Depth: SHALLOW/MEDIUM/DEEP
Phase 5: Implementation Simulation
Per component:
### Component: [name]
**Implement now?** YES/NO
**Questions:** [list]
**Must invent:** [what] - should specify: [why]
**Must guess:** [shape] - should specify: [why]
Phase 6: Findings Report
## Score
| Category | Specified | Vague | Missing | N/A |
|----------|-----------|-------|---------|-----|
Hand-Waving: N | Assumed: M | Magic Numbers: P | Escalated: Q
Findings Format
**#N: [Title]**
Loc: [X]
Current: [quote]
Problem: [why insufficient]
Would guess: [decisions]
Required: [exact fix]
Phase 7: Remediation Plan
### P1: Critical (Blocks Implementation)
1. [ ] [addition + acceptance criteria]
### P2: Important
1. [ ] [clarification]
### P3: Minor
1. [ ] [improvement]
### Factcheck Verification
1. [ ] [claim] - [category] - [depth]
### Additions
- [ ] Diagram: [type] showing [what]
- [ ] Table: [topic] specifying [what]
- [ ] Section: [name] covering [what]
Self-Check
[ ] Full document inventory
[ ] Every checklist item marked
[ ] All vague language flagged
[ ] Interfaces verified (source read, not assumed)
[ ] Claims escalated to factchecker
[ ] Implementation simulated per component
[ ] Every finding has location + remediation
[ ] Prioritized remediation complete
Core Question
NOT "does this sound reasonable?"
"Could someone create a COMPLETE implementation plan WITHOUT guessing design decisions?"
For EVERY specification: "Is this precise enough to code against?"
If uncertain: under-specified. Find it. Flag it.