Why Spec-First Beats Vibe-Coding
The cost of ambiguous scope compounds silently — a spec written before the first line of code is the cheapest insurance you can buy.
The Default Mode Is Vibe-Coding
Most AI-assisted development starts the same way: you have an idea, you describe it to the agent, the agent starts building. No written requirements. No acceptance criteria. No explicit non-goals. The agent invents the scope — and you discover what it invented when the output arrives.
This is vibe-coding. It feels fast. It often produces something. And it consistently produces the wrong something.
The parallel-agent-dispatch track taught you to fan out work across agents simultaneously. This track is about what those agents receive before they start. An agent with a scoped, testable specification produces work that can be verified. An agent with a vague instruction produces work that must be redone.
The Seven Dimensions of Failure
The comparison between vibe-coding and spec-first development isn't philosophical — it shows up concretely across seven dimensions:
The most damaging dimension is multi-agent risk. When you dispatch multiple agents without explicit non-goals and consumer contracts, they will overlap. One agent adds the Discord channel announcement. Another adds per-user DMs because the description mentioned "notify users." Both write to the same webhook module. Neither knows what the other is doing. You converge to a collision instead of a feature.
The /ship meta-orchestrator skill prevents this by requiring the spec to exist before Phase C (Build) starts. The consumer-contract check at handoff ensures agents know what shape their output must be. This is spec-first discipline applied to agent orchestration.
The Rework Cost Multiplier
The economic argument for spec-first is brutal.
A spec review catch costs 15 minutes of focused writing. A design review catch costs an hour and a half. The same issue caught at the quality gate costs a full test cycle. Post-ship, it costs an incident report, a rollback, user impact, and the retro to understand what went wrong.
Knox's trading-bot calibration incident and the April 7th Semantic Memory Layer remediation session are real examples of this multiplier in action. Changes that were "verified" against localhost cost hours of rediscovery once the production server was involved. A spec that included "E2E verified on target machine (not just localhost)" would have caught both before merge.
What a Spec Is — and Is Not
A spec is not a design document. It is not a technical architecture description. It is not a user story. A spec, in the context of AI-assisted development, is a contract with the agent: the minimum set of information required for the agent to produce verifiable output.
That contract has five required components (covered in depth in the “Anatomy of a Good PRD” lesson):
- Context: Why this, why now
- Goals and success criteria: Testable, binary pass/fail
- Non-goals: What the agent must not do
- Consumer contracts: Who uses the output and what shape they expect
- Acceptance criteria: The conditions under which the agent may declare "done"
Without all five, the spec is incomplete. An incomplete spec is not better than no spec — it is worse, because it creates false confidence that the scope is defined.
The Agent as a Scope-Filling Machine
Here is the practical reality: agents do not say "I don't know what you mean." They fill gaps. They make assumptions. They build toward completeness as they understand it.
"Add user authentication" → agent adds Supabase SSR auth, custom JWT fallback, and session management. You wanted Supabase SSR only. The JWT fallback introduces a security surface. The session management conflicts with existing middleware. Three problems, zero specification.
"Improve performance" → agent adds caching, removes lazy loading, and restructures the data layer. You wanted one cache layer on a single API route. The data layer restructure breaks two other routes. Four hours of debugging, zero specification.
The non-goals section of a PRD exists precisely to prevent this. "Use Supabase SSR only — do not add custom JWT" is four words that eliminate a class of agentic overreach. The /prd-writer skill in Knox's stack generates this section automatically from context, but the thinking behind it is yours.
The Compound Learning Advantage
There is a second-order benefit to spec-first that becomes visible after six months: every spec you write makes the next one better.
The mechanism is the compounding loop: spec → build → retro → lessons.md → Semantic Memory Layer → next spec pre-improved. If you built with a spec, the retro can evaluate against it. "Did we hit acceptance criterion 3? No — why not? The consumer contract check missed the frontmatter parser." That lesson goes into lessons.md. Next session, it surfaces via memory_query("consumer contract") and prevents the same miss.
Vibe-coding produces no comparable loop. "It worked" or "it failed" are not extractable lessons. The difference in compound learning over 50 shipped features is enormous.
What's Next
The next lesson covers the journey from raw idea to structured PRD: how to run the research phase that surfaces existing infrastructure, the six questions that define scope, and how the /prd-writer skill automates the structure once you have the answers.
The spec is the foundation. Everything else in this track is built on it.