Clarity Gate
Overview
A document is only as good as the assumptions it hides. The Clarity Gate is an
epistemic check run before a specification (EPIC, design, requirements) is allowed
to drive code generation. It verifies that every claim is grounded, every assumption is
made visible, and every requirement is specific enough to generate unambiguous output.
The primary failure mode it catches: a spec that reads fine but smuggles unstated
assumptions which compound into defects downstream. Passing a readability check is not
enough — the gate is designed to surface what the prose quietly assumes.
Quick Start
- Read the spec to be gated.
- Apply the 13-item checklist (7 foundation + 6 document-architecture) — see
references/clarity-gate-checklist.md for the full checklist and scoring rubric.
- Score against the 6 criteria: actionability, specificity, consistency, structure,
disambiguation, reference clarity.
- The spec must score ≥ 9/10 to proceed. Below 9: list the specific gaps, revise,
re-score.
Full vs. lightweight
- Full gate (specs/EPICs): the complete 13-item checklist + scoring; gate at ≥9/10.
Used before an EPIC proceeds to implementation.
- Lightweight check (routine docs): actionable? current (not aspirational)? specific
references (no vague "see elsewhere")? planned-vs-present clearly marked? single source
(link, don't copy)? Use for docstrings, READMEs, summaries — no numeric score required.
Boundary & Related Skills
Owns: the readiness check for specs/docs — the checklist, the scoring, the ≥9/10 bar.
Does NOT own: producing the spec (that is epic-planning + the external stream-coding
method), writing code (cosmic-python), or writing the docs themselves (technical-writing).
The gate judges; it does not author.
Related: epic-planning (produces the EPIC the gate scores), bdd-gherkin (authors the
design-phase .feature coverage the gate scores), spec-stewardship (lifecycle after gating),
guardrails (behaviour gate alongside this content gate), stream-coding (the doc-first method this
gate sits inside), technical-writing (applies the lightweight check).
Tips
- Score honestly: a 9/10 that hides one critical assumption is a failed gate, not a pass.
- When you fail a spec, return the specific missing items, not a vague "needs work".
- Apply MECE as a completeness lens: roles, permissions, states, and edge cases should be
mutually exclusive (no overlap) and collectively exhaustive (no gaps). Overlaps hide
conflicting rules; gaps are the unstated cases that become defects.
Limitations
- The gate measures spec readiness, not downstream correctness; tests and review remain.
1---2name: clarity-gate3description: Pre-ingestion quality gate for specifications and documents before they drive implementation. Use to score a spec/EPIC against a 13-item checklist (6-criterion rubric, must reach ≥9/10), surfacing hidden assumptions and ungrounded claims. Trigger on "score this spec", "is this spec ready", "run the clarity gate", "check this EPIC before implementation". A lightweight variant applies to routine docs.4license: Apache 2.05---67# Clarity Gate89## Overview1011A document is only as good as the assumptions it hides. The **Clarity Gate** is an12*epistemic* check run **before** a specification (EPIC, design, requirements) is allowed13to drive code generation. It verifies that every claim is grounded, every assumption is14made visible, and every requirement is specific enough to generate unambiguous output.1516The primary failure mode it catches: a spec that *reads* fine but smuggles unstated17assumptions which compound into defects downstream. Passing a readability check is not18enough — the gate is designed to surface what the prose quietly assumes.1920## Quick Start21221. Read the spec to be gated.232. Apply the 13-item checklist (7 foundation + 6 document-architecture) — see24 `references/clarity-gate-checklist.md` for the full checklist and scoring rubric.253. Score against the 6 criteria: actionability, specificity, consistency, structure,26 disambiguation, reference clarity.274. The spec must score **≥ 9/10** to proceed. Below 9: list the specific gaps, revise,28 re-score.2930## Full vs. lightweight3132- **Full gate (specs/EPICs):** the complete 13-item checklist + scoring; gate at ≥9/10.33 Used before an EPIC proceeds to implementation.34- **Lightweight check (routine docs):** actionable? current (not aspirational)? specific35 references (no vague "see elsewhere")? planned-vs-present clearly marked? single source36 (link, don't copy)? Use for docstrings, READMEs, summaries — no numeric score required.3738## Boundary & Related Skills3940**Owns:** the readiness check for specs/docs — the checklist, the scoring, the ≥9/10 bar.4142**Does NOT own:** producing the spec (that is `epic-planning` + the external `stream-coding`43method), writing code (`cosmic-python`), or writing the docs themselves (`technical-writing`).44The gate *judges*; it does not author.4546**Related:** `epic-planning` (produces the EPIC the gate scores), `bdd-gherkin` (authors the47design-phase `.feature` coverage the gate scores), `spec-stewardship` (lifecycle after gating),48`guardrails` (behaviour gate alongside this content gate), `stream-coding` (the doc-first method this49gate sits inside), `technical-writing` (applies the lightweight check).5051## Tips5253- Score honestly: a 9/10 that hides one critical assumption is a failed gate, not a pass.54- When you fail a spec, return the *specific* missing items, not a vague "needs work".55- Apply **MECE** as a completeness lens: roles, permissions, states, and edge cases should be56 **mutually exclusive** (no overlap) and **collectively exhaustive** (no gaps). Overlaps hide57 conflicting rules; gaps are the unstated cases that become defects.5859## Limitations6061- The gate measures spec readiness, not downstream correctness; tests and review remain.
meaningfy-ws