/clarify

name: clarify
description: >
  Lightweight spec clarification scan for jig projects — a six-category
  ambiguity audit that asks up to five prioritized questions and appends
  them to the spec's `## Clarifications` section. Auto-triggers when you
  say clarify this spec, audit this spec for ambiguities, is this spec
  ready for review, find unknowns in this scope, surface what's still
  unclear or unspecified, scan for unanswered questions, or what's
  missing from this spec. Do not use for:
  spec-compliance review of a finished slice (use
  `/jig:independent-review` instead); cross-artifact consistency
  analysis or drift detection (use `/jig:analyze` instead); project-vision
  or architecture elicitation (use `/jig:vision-elicitation` instead).
user-invocable: true

> Spec 023 introduces this skill as jig's **pre-spec ambiguity scan**. It > is the sixth non-stub active jig skill that ships without a `.py` > helper — clarify is fundamentally a judgment skill, and the > determinism it needs (locate the target doc, find an existing > `## Clarifications` section if any, append new entries) Claude can > run inline via Read + Edit. The skill slots between > `workflow.py new <slug>` (stub reservation) and the > `READY_FOR_REVIEW` transition (spec body ready for first review). > > Per user direction on 2026-05-18, jig's clarify ships as a > **standalone baseline**, not a deferral surface. Power users who > want spec-kit's `/speckit.clarify` install spec-kit and invoke it > explicitly under `/speckit.*`. There is no category-based deferral > hint in this skill's description.

What this skill does

Runs a structured ambiguity scan against a DRAFT-state spec document across **six categories** aligned with jig's slice template (Scope & Boundaries / Acceptance Criteria Testability / Dependencies & Blockers / Non-functional Requirements / Edge Cases & Failure Modes / Terminology Consistency). The skill rates each category Clear / Partial / Missing, selects up to **five prioritized questions** (Partial/Missing weighted above Clear), asks them one at a time recording the user's verbatim answer, and appends a `## Clarifications` section to the target document with the Q/A entries plus a coverage summary table.

The skill is **breadth over depth**: catch the obvious unanswered questions across the six taxonomy categories in a few minutes, leave deep domain-specific clarification (legal review, regulatory edges, multi-stakeholder facilitation) to the dev's judgment or to a richer team process. The five-question budget exists to keep the scan lightweight enough to actually run before each `READY_FOR_REVIEW` transition — not so heavy it becomes a chore the team skips.

When to use vs. when to defer

There are four sibling skills people often confuse with this one. Pick the right one:

• **`/jig:spec-workflow`** — sibling skill for **state transitions**

(`workflow.py new`, `workflow.py transition`, status board regen). Spec-workflow moves a slice between DRAFT / READY_FOR_REVIEW / IN_PROGRESS / REVIEWED / RECONCILED / DONE; it does not elicit clarifications. Reach for `/jig:spec-workflow` when you want to reserve a new spec number or push a slice to the next state. Reach for this skill when the spec body has gaps you want surfaced *before* the next transition.

• **`/jig:analyze`** — sibling jig skill (spec 024, sequenced after

this one) for **cross-artifact consistency analysis**. Analyze reads multiple specs + ADRs + docs and surfaces drift between them. This skill scans **one document** for internal ambiguities. Reach for `/jig:analyze` when you suspect a spec disagrees with another spec or with an ADR. Reach for this skill when one spec's body has unanswered questions in isolation.

• **`/jig:vision-elicitation`** — sibling skill that fills slots in

`docs/product-vision.md` and `docs/architecture.md`. That's **project-scope elicitation**: who are the users, what's the problem, what's the architecture? This skill is **spec-scope elicitation**: what does this *one slice* mean, what are its ACs, what are its dependencies? Reach for vision-elicitation immediately after `scaffold-init`; reach for this skill when authoring or reviewing a single spec.

• **`/jig:independent-review`** — sibling skill that reviews a

finished slice against its spec.md. Independent-review **assumes the spec is clear** — it checks the implementation against the ACs. This skill helps make the spec clear in the first place, so independent-review has something specific to review against. Reach for `/jig:independent-review` after the slice is implemented; reach for this skill before the slice has transitioned to `READY_FOR_REVIEW`.

Rule of thumb: **draft a spec → this skill. Transition a spec → `/jig:spec-workflow`. Audit across specs → `/jig:analyze`. Review the implementation → `/jig:independent-review`. Set up the project → `/jig:vision-elicitation`.**

Inputs

Two input modes, both supported by the MVP:

1. **Single `spec.md` (overview-level scan).** The user names a spec directory (`docs/specs/023-clarify/`) or its `spec.md` file directly. The scan covers the spec body's Overview / Why now / Goals / Non-goals / Decomposition / Open questions sections. The `## Clarifications` section gets appended to that `spec.md`. 2. **One `slice-NN-*.md` (slice-level scan).** The user names a specific slice file (`docs/specs/023-clarify/slice-01-clarify-skill-md.md`). The scan covers the slice's Goal / DoR / Acceptance Criteria / DoD / Anti-horizontal-phasing check. The `## Clarifications` section gets appended to that slice file (not to the parent spec.md).

**Mixed-mode ("scan the spec AND every slice") is explicitly NOT supported by the MVP.** That requires per-doc bookkeeping and a re-entry/resume protocol that's out of scope for this slice. If the same friction surfaces three times across real usage, a future slice 023-02 can ship a `.py` helper