Spec Check — Verify Code Against Plan

You are verifying that code matches a spec plan. "Audit" in this skill means a full review of code against a spec — it is unrelated to audit logging, audit context, or audit trails in the codebase.

Specs Folder Discovery

Run bun ~/.claude/tools/spec-edit/index.ts conf-get <cwd> where <cwd> is the current working directory. If it returns a path, use that as <specs-dir>. If it exits with no output, tell the user: "This project hasn't been set up yet — run /spec first to configure the specs folder."

No Arguments?

If invoked without arguments, run bun ~/.claude/tools/spec-edit/index.ts status <specs-dir> and present the output. Then ask:

• "What do you want to check?"
  • "A PR or branch diff against a spec"
  • "The current codebase against a spec (full audit)"

Using spec-edit for reading

Always use spec-edit to read specs — it's faster than the Read tool:

bun ~/.claude/tools/spec-edit/index.ts status <specs-dir>         # Quick summary of all specs
bun ~/.claude/tools/spec-edit/index.ts read <file> [heading]      # Print file or section to stdout
bun ~/.claude/tools/spec-edit/index.ts list <file>                # List sections with line counts

Steps

1. Find the spec. Based on the user's input, use spec-edit status to find it. If ambiguous, present the list and ask.
2. Determine check mode:
   • Diff mode: User provides a PR number/URL, or there are uncommitted/branch changes relevant to the spec → use gh pr diff or git diff against base branch
   • Audit mode (full spec review, NOT audit logging): No meaningful diff (code is already merged) → read the source files referenced in the spec and verify current state matches what the spec describes
   • Ask the user if unclear
3. Read the spec. Read the full spec (spec.md + detail files). Focus on Key Decisions and Current Approach.
4. Check linked ticket. If the spec has a linked issue tracker ticket (e.g. Jira) and an Atlassian MCP is available in the environment, pull the ticket context for additional verification context.

5. Propose parallel audit agents. For audit mode, identify the distinct areas the spec covers — each detail file, each major Key Decision, each described module or layer. If two or more distinct areas can be verified independently, propose spawning one audit agent per area. Each agent would read the relevant source files and check alignment with its slice of the spec, then report back findings.

   Present what each agent would own and verify. Then ask: "Want to run these checks in parallel, or work through them sequentially?"

   Do not spawn agents here. Wait for the user's decision. For diff mode, skip this step — a diff is already a bounded scope.

6. Verify.
   • Diff mode — check the diff against the spec:
     • Alignment: Do the changes follow the Key Decisions?
     • Completeness: Is anything from the spec missing?
     • Scope: Are there changes beyond what the spec describes?
     • Deviations: Differences from the planned approach?
   • Audit mode — read the actual source files referenced in the spec and check:
     • Do the files/modules exist where the spec says they do?
     • Do the implementations match the described patterns?
     • Are the Key Decisions reflected in the code?
     • What does the spec say should exist that doesn't?
     • What exists that the spec doesn't account for?
7. Report. Give a concise verdict:
   • Aligned — code matches the spec
   • Gaps — what's missing or not yet implemented
   • Deviations — what differs from the plan and whether it matters
   • Out of scope — code not covered by the spec
   • Spec outdated — spec doesn't reflect what the code actually does

Rules

• Be specific. Reference exact files and spec sections.
• Don't nitpick code style — focus on architectural alignment with the spec.
• This works for the user's own PRs and teammates' PRs alike.

$ARGUMENTS