feat(skills): add tracing-acceptance-criteria skill

[katspaugh]

Who is submitting this PR?

Field	Value
Your model + version	Claude Opus 4.8 (1M context), claude-opus-4-8
Harness + version	Claude Code
All plugins installed	superpowers 6.1.1, chrome-devtools-mcp, figma, github, linear
Human partner who reviewed this diff	@katspaugh (PR author) — review in progress; draft until complete

What problem are you trying to solve?

The flow produces a spec with acceptance criteria and a plan, but nothing links a
criterion to the test that proves it. At verification-before-completion there is
no cheap way to answer "which criteria are actually demonstrated by a test, and are
any of my requirement references stale?" In practice a criterion silently goes
unproven, or a code comment references a requirement ID that no longer exists in any
spec, and nobody notices until review.

What does this PR change?

Adds a tracing-acceptance-criteria skill: give each acceptance criterion a stable
COMPONENT-N ID in its docs/superpowers/specs/ design doc, tag the proving test
with an @ac <ID> marker during TDD, and run an ad-hoc rg check at verification
that reports uncovered (defined ID with no test marker), orphan (marker
whose ID is in no spec), and duplicate (same ID across specs) IDs. No tooling to
install. Also adds one catalog line to the README.

Is this change appropriate for the core library?

• Useful on a completely different project? Yes — requirement→test traceability is
  domain-agnostic; the check is a plain ripgrep over any test suite.
• Project/team/tool-specific? No. It stores criteria in the library's own
  docs/superpowers/specs/ artifact and integrates with the existing
  brainstorming → writing-plans → TDD → verification skills. No third-party service.
• The mechanism (stable IDs + @ac markers + coverage scan) is the piece missing
  from the current flow; it's adapted from acai.sh's "specsmaxxing".

What alternatives did you consider?

1. Fold it into #1112 / the AC-authoring step — rejected as a bundle. feat: add acceptance-criteria skill #1112 is
   about writing good criteria (Given/When/Then, SMART). This is the orthogonal
   traceability half. Keeping them separate lets either land on its own; this skill
   is deliberately named tracing-acceptance-criteria to avoid colliding with feat: add acceptance-criteria skill #1112.
2. A committed executable / CI gate — rejected (YAGNI). The check is two rg
   commands the agent runs and reasons about; a script adds install/maintenance
   surface for no judgment the agent can't do inline. It is report-only, not a gate.
3. Reference IDs in production code instead of tests — rejected. This library is
   test-first, so "covered" must mean a test proves it; the coverage scan is scoped
   to test files and a production-only marker never counts as covered.

Does this PR contain multiple unrelated changes?

No. One skill (skills/tracing-acceptance-criteria/SKILL.md) plus its one-line
README catalog entry.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs:
  • feat: add acceptance-criteria skill #1112 (open) — complementary, not a duplicate. feat: add acceptance-criteria skill #1112 adds an
    acceptance-criteria skill for authoring criteria (GWT/SMART). This PR is the
    traceability half (IDs + @ac markers + rg coverage scan) and uses a distinct
    name/path to avoid collision. The two compose: author with feat: add acceptance-criteria skill #1112, trace with this.
  • feat: add writing-test-scenario-specs skill #966 (open, writing-test-scenario-specs) — about test scenarios for skills, not
    feature ACs. Different problem.
  • Add verifying-plan-coverage skill: prove a plan covers 100% of its spec before execution #1704 (open, verifying-plan-coverage) — proves a plan covers a spec before
    execution; this proves tests cover criteria after implementation. Adjacent, not
    overlapping.

Environment tested

Harness	Harness version	Model	Model version/ID
Claude Code	current	Claude Opus	claude-opus-4-8 (1M context)

Evaluation

Followed superpowers:writing-skills. Three layers of testing, honestly scoped:

1. Command correctness (dry-run). Ran the Check commands against a scratch fixture
(a test file with @ac AUTH-1/AUTH-2/AUTH-9, a spec defining AUTH-1/2/3, a
production-only @ac AUTH-4). Confirmed: covered = {AUTH-1, AUTH-2}, UNCOVERED =
AUTH-3, ORPHAN = AUTH-9, production-only AUTH-4 not counted. Also confirmed the ID
regex [A-Z]+-\d+ rejects malformed IDs (1AUTH-2) and that the tree-wide scan does
surface an @ac ID quoted inside a string literal — which is why the skill calls the
scan a text match, not a parser.

2. RED/GREEN behavioral eval (paired subagents, 5 reps per arm). Built a fixture
where the discriminating case is AUTH-3: marked with @ac on production code only,
no test (correct answer: UNCOVERED, coverage 2/3). Ten fresh agents got the same
natural-language question ("which acceptance criteria are covered by tests?"); the
skill arm additionally had the SKILL.md available.

• Baseline (no skill), 5/5: every rep counted AUTH-3 as covered off the
  production marker and reported 3/3 — the exact failure the skill's test-scoping
  rule targets. (Several noted AUTH-3 "has no test" as a caveat, yet still counted it.)
• With the skill, 5/5: every rep reported AUTH-3 UNCOVERED for the right reason,
  AUTH-9 orphan, no duplicates, 2/3. Two reps reproduced the skill's example report
  format; one explicitly confirmed the markers weren't string false-positives.

Fully separated distributions, zero variance on the verdict: 3/3 (wrong) → 2/3 (right).

3. Drill scenario authored (not yet executed). I wrote a
applying-tracing-acceptance-criteria scenario (story.md / setup.sh /
checks.sh) in the superpowers-evals format, encoding the same discriminator as
verifier acceptance criteria. I could not execute the official evals/ drill harness
in my environment (no ANTHROPIC_API_KEY, no uv; it runs real multi-minute agent
sessions). The scenario is ready for a follow-up PR to superpowers-evals and a
multi-rep run by anyone with a key.

Still a draft because: the human diff review below is pending, and the official
multi-backend drill run (Codex/Gemini as well as Claude) hasn't been executed —
the subagent eval above covers the Claude backend only.

Rigor

• If this is a skills change: I used superpowers:writing-skills
• This change was tested adversarially, not just on the happy path — baseline vs.
  skill on the production-only-marker trap, 5 reps per arm: 5/5 baseline wrong (3/3),
  5/5 skill correct (2/3), fully separated. Edge cases covered (production-only
  marker, malformed ID, string-literal false positive). Caveat: Claude backend only;
  the official multi-backend drill run is pending (scenario authored).
• I did not modify carefully-tuned content (Red Flags tables, rationalizations,
  "human partner" language, or any existing skill)

Human review

• A human has reviewed the COMPLETE proposed diff before submission