---
name: spec-hardening
description: Stress-test a module/workflow spec for completeness, clarity, and consistency before building. Use at the end of Phase 3 (Specify) — after the spec is reconciled to the design and before the build sweep — as a pre-build quality gate.
allowed-tools: Read, Grep, Glob, Write
---

> **Specialization:** generic by design — bind every `<…>` and "per `CLAUDE.md`" reference from the project `CLAUDE.md` (the naming grammar, continuity invariants, design-system contract, domain compliance, and the spec conventions `<X>_MODULE.md` / `<X>_WORKFLOW.md` / `<X>_DB_SCHEMA.md`). See `SPECIALIZE.md`. If a needed value is missing, STOP-and-ask.

## What this skill is for
A **pre-build quality lens** on a slice's spec. It writes no code and changes no design; it interrogates the **reconciled spec** for gaps, ambiguity, and cross-artifact drift so the sweep starts from a sound spec. The technique is adapted from GitHub spec-kit's `clarify` / `checklist` / `analyze` commands, but expressed **natively** on this kit's own artifacts — it installs nothing from spec-kit and defines no second constitution.

It complements, not duplicates, the existing roles: `spec-architect` reconciles the spec **against the design**; `reviewer` audits **code against the constitution**; this skill audits the **spec itself** in the gap between them.

## When to use it
At the **Specify → Found/Build** boundary: after `spec-architect` has reconciled `<X>_MODULE.md` / `<X>_WORKFLOW.md` to the design and recorded `<X>_DB_SCHEMA.md`, and before `/build-workflow` dispatches slice agents. Run it per module/workflow about to be built.

## How to do it — three passes
1. **Clarify.** Read the spec against the rendered design (the contract). List the under-specified points as targeted questions: each screen state (loading / empty / error / permission-denied), each CTA destination, each guarded action's inline reason, each edge/failure path, each `PERM-*`, each acceptance criterion. Emit a short "Clarifications needed" block. Do **not** invent answers — they fold in through the approval gate (just-in-time reconciliation; the rendered design wins any conflict).
2. **Checklist** ("unit tests for English"). Generate a requirements-quality checklist from the kit's own laws and mark each pass/fail against the spec:
   - Every screen names all four states.
   - Every step→step transition has a CTA + destination; no dead-end, no orphan.
   - Every guarded CTA is disabled-with-inline-reason (never hidden, never silently allowed).
   - Every business rule is stated as a testable `BR-<X>-NNN` and enforced in the domain, not the UI.
   - Every `EVT-<X>-Name`, `PERM-<X>-Entity.Action`, `WF-<X>-NN` follows the naming grammar.
   - Every entity has persistence placement + a `<X>_DB_SCHEMA.md` entry.
   - Cross-module needs go through Contracts (events / DTOs), never a direct reference.
   - Compliance per `CLAUDE.md` is addressed (identity-safety, audit, RBAC, break-the-glass, config-gating, AI governance, irreversible-action safety).
   - A provenance header (design source ref, `last_synced`) is present.
   - **Gateless sensitive-write check:** if a sensitive-write CTA appears gateless in the design (no required-identity confirmation, no domain safety gate), do NOT invent the gate into the spec — flag it as a blocking clarification for human ruling (the rendered design is the contract; Law 1).
3. **Analyze** (cross-artifact consistency). Diff `<X>_MODULE.md` ↔ the design ↔ `<X>_WORKFLOW.md` ↔ `<X>_DB_SCHEMA.md` ↔ the registries. Flag contradictions, duplicated/forked definitions, and coverage gaps — a screen in the design with no spec, a workflow step with no owning module, an entity with no schema.

## Rules / guardrails
- **Advisory only.** Propose; never edit the design, and never silently change the spec. Findings reach the human through the approval gate.
- **The rendered design is the contract.** A spec-vs-design conflict is a finding to surface (resolved in favor of the design, or escalated), never decided here.
- **Right-size.** Flag what THIS slice needs; defer nice-to-haves to the backlog.

## Done when
A spec-readiness report exists with the clarifications-needed list, the checklist (pass/fail per item), and the cross-artifact findings, ending in a verdict:
- **READY** — no blocking gaps; the sweep may proceed.
- **NEEDS-WORK** — blocking items listed; the orchestrator routes them to the approval inbox / `spec-architect` before dispatching agents.