Never spec-to-code — read the code, not just the spec
Never spec-to-code
Rule
Code IS truth. Specs align intent. Never invert.
Spec-to-code movement (rejected)
PRD/spec = source. Code = compiled output. Humans never read code. AI regenerates on every change.
Failure mode
| Stage | Symptom |
|---|---|
| 1. Adopt spec-as-source | Humans stop reading generated code |
| 2. Production bug | Nobody knows where logic lives |
| 3. Forced back to code | Discover spec ≠ code (doc-rot) |
| 4. Edit spec, regenerate | Overwrites hand-fixes from step 3 |
| 5. Cycle repeats | Codebase handle lost permanently |
Blocked tools (do NOT adopt)
| Tool | Vendor | Shape |
|---|---|---|
| Kiro | Amazon (2025) | Full spec-driven IDE |
| Spec-Kit | GitHub | Spec-first repo scaffold |
| BMAD | Business Analyst Modeling for AI Development | PRD → agent pipeline |
| GSD | Get Shit Done specs | Spec-as-ticket |
| Tessl | Tessl.io | Specs-as-source platform |
Correct model
- Specs = alignment doc, ephemeral
- Code = source of truth, read every time
- OKF decision files = why, not what
- Every agent reads files it modifies (per [[read-the-file-not-just-grep]])
- Every PR review reads CODE, not spec
Sources of truth in oriz
- OKF concept files (
knowledge/decisions/**) — durable why - Code — durable what
- No floating "spec" documents. No PRD.md. No requirements.md.
Why this matters
Handle on codebase = ability to debug, refactor, ship. Lose it once = permanent. Brooks's "conceptual integrity" (Mythical Man-Month) survives only when humans read code. HumanLayer's 75K-line agent-built codebase (Dex Horthy) works because humans read every diff. Geoffrey Huntley's Ralph pattern same discipline.
Source
Matt Pocock workshop 2026-07-03 — names Kiro/Spec-Kit/BMAD as target anti-patterns.
Cross-refs
- [[read-the-file-not-just-grep]] — enforcement mechanism
- [[knowledge-deletion-not-supersession]] — decision files die with implementation
- [[karpathy-guidelines]] — code is battleground