/analyze

name: analyze
description: >
  Cross-artifact consistency report for jig specs — a non-destructive
  six-category audit at CRITICAL/HIGH/MEDIUM/LOW severity, covering
  duplication, ambiguity, underspecification, principle violations,
  coverage gaps, and terminology drift. Auto-triggers when you say
  analyze this spec, check for inconsistencies, audit ADR vs spec drift,
  check whether the decision records still agree with the spec,
  cross-artifact alignment, find drift in this spec, or audit this spec
  for principle violations. Do not use for: pre-DRAFT ambiguity scanning
  (use `/jig:clarify` instead); structural frontmatter or slice-numbering
  validation (use `spec_lint.py` instead); spec-compliance review
  of a finished slice (use `/jig:independent-review` instead).
user-invocable: true

> 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 sur