Coverage Check (layered)

Instructions

Audit the use case $ARGUMENTS (UC-XXX) against the code and tests that are supposed to realize it, and report the result.

This skill is the front door to the read-only uc-coverage-layered sub-agent of aiup-core. The audit checklist — how coverage units are derived, which markers to search for, how each unit is judged — lives in agents/uc-coverage-layered.md at the plugin root (locate it with a glob for **/agents/uc-coverage-layered.md) and is deliberately not repeated here, so the two cannot drift apart. Your job is argument parsing, delegation, faithful presentation of the report, and offering the next step.

The report is the deliverable. You do not fix what it finds.

Arguments

Everything is parsed out of $ARGUMENTS; the tokens may appear in any order.

Three parsing rules carry weight:

• A mode is only narrowed by a standalone qualifier token. In a sentence — "is UC-001 fully implemented?" — the word implemented is prose, not a mode: run both. Silently narrowing to implementation recreates the very gap this skill exists to close.
• State the resolved arguments in one line before delegating (Auditing UC-001, mode both.), so a wrong parse costs one rerun instead of producing a wrong verdict.
• If the id resolves to no file under docs/use_cases/ (module subfolders included) or docs/use-cases/ (both spellings are in use), list the near matches and ask. Never audit against a specification you inferred from code.

Workflow

1. Parse $ARGUMENTS into the id or ids, the mode, and the work-in-progress flag. With no id, go to Sweeps.
2. Confirm the specification exists — docs/use_cases/**/UC-XXX-*.md (also check docs/use-cases/). Stop and ask if it does not.
3. State the resolved arguments in one line.
4. Delegate the audit — see Delegation.
5. Present the returned report unchanged. When this conversation already holds an audit of the same id and mode, add the comparison — see Repeated Runs.
6. Offer the gap-closing commands — see After the Report. Then stop.

Delegation

Hand the audit to the read-only uc-coverage-layered sub-agent of aiup-core (it may appear as aiup-core:uc-coverage-layered). Pass exactly the id, the mode, and — when it applies — work in progress, and nothing else:

UC-001 both
UC-001 tests
UC-001 implementation work in progress

Do not add a summary of the specification, a list of the files you believe implement it, or what you expect the answer to be. The agent must find its own evidence; a caller-supplied file list is the fastest way to turn an audit into a rubber stamp.

Present the report as it came back — the heading, the score line, the full matrix, ### Gaps, ### Drift, ### Open questions, and ### Suggested status. Do not summarize it into prose, do not drop the covered rows to save space, and do not change a verdict. The matrix is the deliverable; if you disagree with a verdict, say so underneath it and leave the row alone.

After the Report

• Turn each gap into the command that closes it, narrowed to the layer the gap is in when the report names one: /use-case-implement UC-XXX (or /use-case-implement UC-XXX service) for implementation gaps, /use-case-test UC-XXX for test gaps — narrowed to a layer below the integration layer of docs/architecture/stack.md (/use-case-test UC-XXX service) only when the report says the unit is unreachable from it — /stack when the report says docs/architecture/stack.md or its Integration layer table is missing, and a rerun of the layer skill named in the Layers table when the report says its Markers rows are missing (the layer skills own those rows; /stack adds only the All row; a test skill below the integration layer that never ran has none to add). Offer them; run one only if the user says yes.
• Drift is not a gap with a known fix. For each drift item, ask the user which side is right — the specification (/use-case-spec UC-XXX adds the behaviour) or the code (/use-case-implement removes it) — and offer only the command that matches the answer. Never pick a side yourself: changing the specification to match the code, or the code to match the specification, without that decision is what sends /spec-review and /use-case-coverage round in circles.
• Do not close gaps yourself, and do not close one "quickly because it is only one line". A one-line fix from the auditor is still an unreviewed change to a verdict you have just issued.
• The agent cannot run builds or tests. Before repeating any Tested suggestion, ask whether the suite passes.
• Pass the ### Suggested status on as a suggestion, and name the line that would change. Do not edit the specification's **Status:** line as part of this report.
• Open questions are not yours to close: offer /open-questions answer OQ-XXX for an Open one and the skill that resolves an Answered one, and never record a gap of the report as a question.

Repeated Runs

The agent starts from scratch every time and does not know its previous verdicts; you do. When this conversation already holds a report for the same id and mode, add one section under the report — the matrix itself stays exactly as the agent returned it:

### Since the last run

- Closed: BR-002, A1
- New: A3 — `PersonForm.java` changed since the last run
- Changed without a change: Step 4 Covered → Partial; neither the specification nor the files
  named in the row changed
- Still open after a fix aimed at it: Post-S-1

• A verdict that changed although neither the specification nor the evidence files changed is the auditor's judgment wobbling, not new work. Say so, and ask the user whether to act on it; do not offer a command for it.
• A gap still open after a fix aimed at it: do not offer the same command again. State what the auditor wants and what the code does, and ask the user to settle it — it may be the specification that needs to change, which is a decision, not a gap.
• When every unit is Covered or n/a, the audit is finished. Do not suggest a further run.

Hosts without sub-agents

Sub-agents are Claude Code-specific and are not part of the Agent Plugins standard. Where the host has none, locate agents/uc-coverage-layered.md with a glob for **/agents/uc-coverage-layered.md — hosts that install skills one folder at a time do not expose the plugin root, so never resolve it relative to this skill's folder — and follow it yourself, start to finish, as an instruction document; its checklist does not depend on Claude Code. If it genuinely is not there, say so rather than improvising an audit from memory. The checklist is the skill.

Running it inline costs you the agent's tool restriction and its clean context, so two rules apply on top of it: re-read the specification and the code from disk instead of relying on what you remember writing earlier in the conversation, and treat the agent's ## DO NOT as binding on yourself — above all "no file:line, no Covered".

Sweeps

With no id: if the conversation has just been working on a specific UC-*, propose that one and ask. Otherwise list what is there — a glob over both use case directories plus a grep for the **Status:** line — and ask which to audit. Do not audit everything by default.

When the user does ask for a sweep ("all", "every use case", "sweep"), it is a triage pass, not thirty audits:

1. Pre-pass, no sub-agents at all. For every specification collect id, title, and **Status:**, plus one tree-wide grep for the literal id to see whether any implementation marker and any test marker exist. Two or three tool calls for the whole project.
2. Publish that table first. It already answers the common question — which use cases have nothing behind them — at zero audit cost.
3. Then rank and cap. Full audits go only to the suspicious rows: the status claims Implemented or Tested but a marker is missing, or the status is Approved while markers exist (a status lagging behind the code). Default cap: five full audits per invocation, run one at a time.
4. Ask before exceeding the cap, naming the number — "30 use cases, 7 look suspicious. Audit those 7 now, or name the ones you want?" Never silently run 30.
5. The deliverable is the summary table plus the full matrices only for the ones actually audited, and a line naming the ids that were skipped so nobody mistakes a triage row for an audit. Never audit the same id twice in one invocation.

DO NOT

• Do not write or edit code, tests, or specifications — including the **Status:** line.
• Do not restate or paraphrase the agent's audit checklist in this file; agents/uc-coverage-layered.md owns it.
• Do not soften, upgrade, or drop a verdict, and do not present a summary in place of the matrix.
• Do not tell the agent what you expect it to find.
• Do not claim that a build or a test suite was run.
• Do not audit every use case without being asked, and do not exceed the sweep cap without confirmation.