clarify

Files (3)

• SKILL.md
• worked-example-jig.md
• worked-example-saas.md

SKILL.md (first lines)

> 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 that orchestrates the loop.
Until then, the user re-runs the skill per document.

## Six-category taxonomy

For each category, the skill rates the target document Clear / Partial /
Missing. The scan is internal to the model — the rating is not shown
to the user unless an answer is sought. The categories below are aligned
with jig's slice template; spec-kit's nine-category taxonomy was slimmed
to six by dropping "Domain & Data Model" and "Interaction & UX Flow"
(which assume slots jig's slice template doesn't have) and folding
their substance into "Scope & Boundaries" where it applies.

### Scope & Boundaries

What is in-scope, what is out-of-scope, what is the boundary with
adjacent specs? Watch for unstated assumptions about which layer or
module the change touches.

What to check:

- Is the in-scope deliverable named in concrete terms (file paths,

From ramboz/jig, MIT.

More from ramboz/jig