clarify

name	Clarify
description	Find and close holes in the master spec before the North Star — resolve ambiguity markers, run a coverage scan, ask high-impact questions, and optionally simulate usage scenarios.
argument-hint	<feature-name> [--markers-only|--scan-only|--simulate]

Clarify — Close the Holes

A post-spec review that finds and closes gaps before the North Star. Gate: the specify phase must be accepted (else "Accept the spec first").

Inputs

• .genesis/project-state.md (mode)
• .genesis/features/<feature>/spec.md (required), design.md (required)
• brainstorm-log.md (optional), the constitution
• approvals/master.json (verify specify accepted)
• dependencies.json for this feature and its peers (cross-feature coverage check)

Process

1. Resolve markers. Scan the spec for NEEDS_CLARIFICATION markers; resolve each one at a time (question → impact → suggested answer), updating the spec and removing the marker. (--markers-only stops here.)
2. Coverage scan across 11 categories, rating each Clear / Partial / Missing: Functional Scope · Domain/Data Model · Interaction/UX · Non-Functional Quality · Integration/Dependencies · Edge Cases · Constraints/Tradeoffs · Terminology · Completion Signals · Assumptions · Cross-Feature Dependencies. (--scan-only reports and stops.)
3. Ask at most 5 targeted questions per run, prioritized by impact, focused on Partial/Missing categories, each with a recommended answer.
4. Apply answers one at a time — update the spec immediately after each (refine requirements, add edge cases to FRs, document assumptions, strengthen/add ACs, remove resolved open questions).
5. (--simulate) Run 5–10 usage scenarios against the spec text — for each, trace FRs/ACs and mark PASS (spec handles it) or GAP (it doesn't). Gaps become new questions or amendments.
6. Re-run constitution compliance if scope changed (halt on violations).
7. Present a before/after coverage summary table (+ simulation table if used). Commit; update project-state.md.

Mode differences

Each category is mode-aware: greenfield checks completeness of new capability; brownfield checks new-vs-modified classification, preservation of existing behavior, and scope-boundary explicitness; lowfield checks pipeline-stage and artifact-schema completeness and measurable per-stage gates. Simulation likewise differs — greenfield = standard usage; brownfield = migration paths and backward compatibility; lowfield = pipeline at scale (50+ units), mid-stream entry, stage skipping.

Output

• Updated .genesis/features/<feature>/spec.md (resolved markers, tightened FRs/ACs, documented assumptions) and a coverage summary in the skill output.

Next step

Run /genesis-northstar.

Natural language triggers

- "clarify the spec"
- "find holes in the spec"
- "simulate the spec"