spec-coachlisted

# Spec Coach (Interactive Spec Design) > "A spec is a promise — a promise the system makes to its users and a promise > the team makes to themselves about what they will build." > — Adapted from Joel Spolsky, "Painless Functional Specifications" ## Core Philosophy A good spec for an AI agent is not documentation written after the fact. It is a design artifact that shapes behavior before a single line of code is written. **The spec IS the design.** Vague specs produce inconsistent agents. Inconsistent agents are discarded. **What this skill IS:** A structured coaching conversation that produces a complete, deployable spec. A design session, not a documentation exercise. **What this skill is NOT:** A template filler; a substitute for domain expertise; a code generator. **The Five O'Reilly Principles (source framework):** 1. High-level vision first, then details 2. Structure like a professional PRD — sections over prose, exact commands over approximations 3. Modular prompts over monolithic — one spec per agent, one agent per domain 4. Build self-checks and constraints in — three-tier boundaries: Always / Ask First / Never 5. Test, iterate, and evolve — a spec that has never been revised has never been used See [O'Reilly Framework](references/oreilly-framework.md) for the full principle analysis. The 10 domain principles, the mandatory KB-lookup map for GitHub Spec Kit, the anti-pattern catalog, a worked state-block example, and the facilitation-recovery playbook live in