/audit-repo

name: audit-repo
description: >
  Weekly read-only repository audit. Grades one rotating rubric from .claude/audit-rubrics/, files between zero and five GitHub issues for what it finds, and changes no files. Use when the user asks to audit the repo, or when the audit-weekly workflow invokes it. It never edits, commits, branches, or opens pull requests.
argument-hint: "[focus area: skills | tooling | automation]"

/audit-repo

Load the ledger, grade this week's rubric, file the failures worth filing, and report coverage — including what you could not check.

**This skill is read-only.** No edits, no commits, no branches, no pull requests. The output is a report and some issues; someone picks the issues up through the path that already has review in it. An auditor that also merges its own findings has no adversary. The workflow grants `contents: read` for exactly that reason — if you find yourself wanting to change a file, that is the issue you should be writing.

Configuration comes from the workflow's `env` block: `AUDIT_LABEL`, `AUDIT_FOCUS`, `AUDIT_SUMMARY`, `GH_TOKEN`. Running this by hand, accept the defaults named below.

Step 1 — preflight

gh auth status

If that fails, stop and say so. Do not audit anyway. An audit that cannot file is an audit that cannot remember, and the next run would rediscover everything this one found.

Step 2 — read the ledger before you read any repository file

gh issue list --repo "$GITHUB_REPOSITORY" \
  --label "${AUDIT_LABEL:-repo-audit}" --state all --limit 500 \
  --json number,title,state,stateReason,labels,body,url \
  > "${RUNNER_TEMP:-/tmp}/ledger.json"

Every issue ever filed under the label, in every state. Read all of it and sort each entry:

| Bucket | How to tell | What it means | | --- | --- | --- | | Open | `state` is `OPEN` | Filed and waiting. Never refile. | | Fixed | `state` is `CLOSED`, `stateReason` is `COMPLETED` | Shipped. Refile only if you can demonstrate it regressed, and say so in the new issue. | | Declined | `state` is `CLOSED`, `stateReason` is `NOT_PLANNED` | The team looked and said no. **Permanent skip.** |

Declined is permanent, and permanent means in any wording. Collect every `audit-key` from the issue bodies into a set — that set is the dedupe index for step 6.

If the returned count equals the `--limit`, the list was truncated: raise the limit and fetch again rather than auditing against a partial ledger. This step is graded by `AUD-RUN-01`. Record the entry count and the distinct-key count.

Step 3 — pick this week's rubric

week=$(date -u +%V)
case $(( 10#$week % 3 )) in
  0) focus=skills ;;
  1) focus=tooling ;;
  2) focus=automation ;;
esac

Two things in that snippet are load-bearing. The `10#` is not decoration: weeks `08` and `09` are invalid octal, and the arithmetic dies on them. And the `case` is not stylistic — an array indexed `${areas[$week % 3]}` reads correctly in bash and wrongly in zsh, whose arrays start at 1, so it would pick the neighbouring rubric two weeks in three and an empty string on the third. CI runs bash; a person running this on macOS does not.

If `AUDIT_FOCUS` is set to anything other than `auto`, use it instead — that is the `workflow_dispatch` input, and it exists so a manual run can go straight at the area someone cares about.

Read four files, in full, before looking at any repository file:

• [`.claude/audit-rubrics/audit-integrity.md`](../../audit-rubrics/audit-integrity.md) —

graded every week regardless of focus

• `.claude/audit-rubrics/<focus>.md` — this week's rubric
• [`docs/authoring-skills.md`](../../../docs/authoring-skills.md) — the conventions the

rubrics grade against. Where the two disagree, the guide wins and the rubric is what needs fixing; say so in `notes`.

• [`AGENTS.md`](../../../AGENTS.md) — the short tour. If it disagrees with the guide, that

is `AUD-GEN-05`, whichever rubric is in rotation.

[`.claude/audit-rubrics/README.md`](../../audit-rubrics/README.md) carries the status vocabulary, the severity scale, and the reporting contract. Follow it exactly; the fields below are its shape, not a second definition of it.

Rotation is what keeps this sustainable. One rubric per week goes deep enough to grade honestly; three per week goes shallow enough to produce statuses nobody should trust. Grade **only** this week's rubric plus audit integrity. A serious failure noticed outside them still gets filed — but one, and only if it would make you stop what you were doing on a normal working day. Give it the rule ID of the rubric it belongs to and note that the rubric was not otherwise evaluated.

Step 4 — grade every rule

Walk the rubric rule by rule, in order. For each one, record:

{
  "rule_id": "AUD-SKL-02",
  "status": "pass | fail | n/a | not-evaluated",
  "evidence": ["plugins/narrative-common/skills/profile-dataset/SKILL.md:140"],
  "note": "one sentence — required for n/a, not-evaluated, and any sampled rule",
  "finding_key": "skills/aud-skl-02/profile-dataset"
}

Every rule gets exactly one row. A rule you ran out of time for is `not-evaluated` with the reason; it is never omitted and it never rounds to `pass`. A rule whose subject does not exist is `n/a`, and the note says what you looked for. `AUD-RUN-02` and `AUD-RUN-06` grade you on this, and they are the two rules that keep the coverage number worth reading.

**Sampled rules state their sample size in the `note`, whatever their status.** Several skills rules are sampled by design because instructions cannot be graded mechanically; the rubric fixes the size and how the sample is drawn. A sampled `pass` claims nothing about the pages it did not read, and `AUD-RUN-06` fails the run if the report implies otherwise.

Grade against the **invariant**. The probes each rule lists are suggestions and may be stale — a probe that no longer works is a `not-evaluated` only if you cannot check the invariant another way, and it is worth ment