analyze

Files (3)

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

SKILL.md (first lines)

> Spec 024 introduces this skill as jig's **cross-artifact consistency
> auditor**. It is the seventh non-stub active jig skill that ships
> without a `.py` helper — analyze is fundamentally a judgment skill,
> and the determinism it needs (locate the spec, walk siblings, read
> the principles list, sort findings by severity) Claude can run inline
> via Read + Glob. The skill slots between `READY_FOR_REVIEW` (spec body
> ready for first review) and `IN_PROGRESS` (slice already in flight),
> giving the spec author one more pass to catch cross-artifact drift
> before the first review verdict.
>
> Per user direction on 2026-05-18, jig's analyze ships as a
> **standalone baseline**, not a deferral surface. Power users who
> want spec-kit's richer `/speckit.analyze` 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

Produces a **non-destructive** cross-artifact consistency report for a
single spec across the six-category taxonomy at CRITICAL/HIGH/MEDIUM/LOW
severity. **Reporter only — no file writes.** The skill reads one
`spec.md` plus its sibling `slice-NN-*.md` files, plus a small set of
read-only cross-reference docs (`docs/product-vision.md` for principles,
`docs/decisions/*.md` for ADR resolution, `docs/memory/glossary.md` for
terminology, `docs/architecture.md` for architecture-drift checks), and
emits a markdown report to stdout: a findings table sorted by severity,
a per-category coverage summary, and actionable next steps.

The skill is **breadth over depth**: surface the obvious cross-artifact
drift within a few minutes, leave deep manual auditing to the spec
author's judgment or to a richer downstream tool. The 50-findings
ceiling exists to keep the scan scannable; if a spec generates more
than 50 findings, the spec needs structural surgery, not a longer
report.

## When to use vs. when to defer

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

- **`/jig:clarify`** — sibling skill for **pre-DRAFT ambiguity scans**.
  Clarify asks questions to the user and appends a `## Clarifications`
  section to the target doc. It is prospective: "what's unanswered in
  this spec?" Analyze is retrospective: "where do these artifacts
  disagree?" Reach for `/jig:clarify` before the spec hits
  READY_FOR_REVIEW; reach for this skill once the spec body is stable
  enough to cross-check against ADRs, architecture.md, and the
  principles list.
- **`spec_lint.py`** — structural linter (frontmatter shape,
  slice numbering, file naming). Lint is **structural**; this skill is
  **semantic**. Lint catches "slice file missing `status:` frontmatter";
  this skill catches "slice contradicts ADR-0003" or "spec proposes a
  fourth subagent type". The two layers are complementary — run
  `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/spec_lint.py"` first to fix
  structural issues, then run this skill to find semantic drift.
- **`/jig:independent-review`** — sibling skill for **spec-vs-implementation
  reviews**. Independent-review reads a finished slice's deliverables
  and verifies they meet the ACs. This skill reads the spec body and
  ADRs/architecture and surfaces intra-spec drift. Different axis:
  independent-review evaluates implementation against spec; this skill
  evaluates spec against the project's other artifacts. Reach for
  `/jig:independent-review` after the slice is implemented; reach for
  this skill while the spec body is being finalized.
- **`/jig:pr-review`** — sibling skill for **diff-shape reviews**. PR
  review reads a git diff and surfaces blockers / nits / strengths.
  This skill reads a spec doc, not a diff. Different artifact shape:
  PR review evaluates a code change; this skill evaluates a spec
  document. Reach for `/jig:pr-review` after the slice's PR is open;
  reach for this skill while the spec body is being authored or
  refined.

Rule of thumb: **draft a spec → `/jig:clarify`. Structural lint → `spec_lint.py`.
Cross-artifact drift → this skill. Review the implementation → `/jig:independent-review`.
Review the PR diff → `/jig:pr-review`.**

## Inputs

The MVP scans **one spec at a time**.

**Primary input:**

- One `spec.md` (e.g., `docs/specs/024-analyze/spec.md`) **plus all
  sibling `slice-NN-*.md` files** in the same directory. The skill
  walks the spec directory and treats every `slice-*.md` file as
  part of the audit scope.

**Read-only secondary inputs** (for cross-referencing):

- `docs/product-vision.md` — the seven principles for the Principle
  Violations finding category.
- `docs/decisions/*.md` — accepted ADRs for resolving `ADR-NNNN`
  references in the spec body.
- `docs/memory/glossary.md` — canonical glossary terms for the
  Terminology Drift finding category.
- `docs/architecture.md` — declared architectural decisions for
  architecture-drift checks.

**Cross-spec input is explicitly NOT supported by the MVP.** Auditing
all of `docs/specs/` for drift (e.g. "spec 010's ADR-0003 reference
resolves to an ADR that's been superseded") is the territory of a
future slice 024-02 if signal emerges. If the same friction surfaces
three times across real usage, that slice can land. Until then, the
user re-runs the skill per spec.

## Six finding categories

The skill scans the target spec across six categories. Each finding
gets a severity (CRITICAL / HIGH / MEDIUM / LOW). All findings are
collected, sorted by severity, and rendered in the output. If a
category produces zero findings, it still appears in the coverage
summary table with `0` so the reader can verify the scan ran.

### Duplication

Two or more places in the spec body (or across sibling slice files)
say the same thing in subtly different ways. Watch for near-duplicate
ACs, repeated constraints with conflicting phrasing, and ADR-NNNN
restatements that re-declare a decision already captured in an ADR.

From ramboz/jig, MIT.

More from ramboz/jig