Genesis 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"
```