clarity-gate

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

1. Read the spec to be gated.
2. Apply the 13-item checklist (7 foundation + 6 document-architecture) — see references/clarity-gate-checklist.md for the full checklist and scoring rubric.
3. Score against the 6 criteria: actionability, specificity, consistency, structure, disambiguation, reference clarity.
4. 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.