/spec-check

Reads a corpus of specs/tickets (text files) and finds contradictions, gaps, ambiguities, silent assumptions and untestable statements - each finding with quote, location, severity and a concrete clarification question.

What this is for

• Check a requirements corpus for internal consistency BEFORE development starts, instead of discovering contradictions in sprint review or in production.
• Humans overlook contradictions 40 pages apart - an LLM checks the entire corpus in one pass.
• Read-only skill. Does not evaluate domain correctness, only internal consistency, gaps and testability. No access to live ticket systems, no PDF/Word conversion.

PROTECTION RULE - never ~/.claude/

Read-only skill. Guard required if write mode added later.

What You Must Do When Invoked

If /spec-check -help or /spec-check -h (without further arguments) is invoked: output the ## Usage section unchanged and stop.

Otherwise follow these steps in order, skipping none.

Step 1 - Help check

If invoked with -help or -h, output the ## Usage section unchanged and stop.

Step 2 - Clarify source

Clarify: either -SpecDir (a directory, recursively searched for .md/.txt) or an explicit file list. If both missing, ask. Show what was detected:

Source: <directory or file list>
Continue? (yes/no)

Only continue after confirmation.

Step 3 - Create inventory

& "<SKILL_DIR>/scripts/intake.ps1" -SpecDir "<path>"
# or: -Files "<file1>","<file2>"

Read the JSON output. If the script aborts with Exit-Code != 0: show message, stop. If count: 0: inform the user that no matching files were found, stop (do not guess).

If > 30 files in the inventory: show the inventory first (paths + sizes), user selects a subset or confirms the full run.

Step 4 - Read and analyze all files

Read each inventoried file (not excluded) fully with the Read tool (for oversized: true read section-wise via offset/limit). Then actively search for each of the 5 finding categories, do not just note what happens to catch your eye:

1. Contradiction - two places demand incompatible things (quote both, name both locations).
2. Gap - a referenced case is nowhere defined (error cases, edge values, permissions, empty states are the usual suspects).
3. Ambiguity - ambiguous wording that allows >= 2 implementations (write out both interpretations).
4. Silent assumption - the spec only works if something unstated holds true.
5. Untestable - statement without measurable criterion ("fast", "user-friendly").

Per finding: category, severity (high = wrong product risk, medium = rework risk, low = style issue), verbatim quote + file:line (for contradictions: both locations), one concrete, closed-form clarification question.

Standard confidence levels apply: a "contradiction" at level suspected goes into "Open questions", not into the findings list.

Step 5 - Write report

Report structure (Markdown), file spec-check-report.md in the current working directory (not into the checked directory):

1. Summary - finding count per category and severity.
2. Findings - sorted by severity (high -> low), per finding: category, quote(s)
   • location(s), clarification question.
3. Clarification questions (copy-ready for the PO) - only the questions, without context, directly copyable.
4. Open questions - everything at confidence level suspected.

Step 6 - Summarize

Tell the user the report path. Summarize the 3 most important clarification questions first, then the total number of findings per severity.

Usage

/spec-check                    # interactive: ask for spec directory
/spec-check <dir>              # check all text files under <dir>
/spec-check <file1> <file2>    # check explicit files
/spec-check -help              # show usage, stop