Propose the audit plugin: bulk repository audits, starting with /audit:issues

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "name": "quantecon",
   "description": "QuantEcon's shared Claude Code skills and tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "plugins": [
     {
       "name": "qe",
@@ -22,6 +22,16 @@
       },
       "version": "0.1.0",
       "description": "Benchmarking and acceleration-evaluation tools for QuantEcon lecture code"
+    },
+    {
+      "name": "audit",
+      "source": {
+        "source": "github",
+        "repo": "QuantEcon/skills",
+        "path": "audit"
+      },
+      "version": "0.1.0",
+      "description": "Bulk, read-only audits of a QuantEcon repository — issue triage, PR review, technical debt, translation parity — each producing an evidence-cited report bundle"
     }
   ]
 }

CATALOG.md

@@ -33,3 +33,15 @@ This delivers the planned `qestyle-linter` + `qestyle` pair as Claude Code skill
 ## 2. `/benchmark:review-acceleration` — finish
 
 Blocked on the eight evaluation scripts (@xuanguang-li agreed 2026-07-07 to package and send). **Unblocked now:** the full rubric (7 weighted dimensions, verdict bands, HIGH/LOW calibration cases) is specified in the lecture-python.myst#717 thread and can move into `references/rubric.md` ahead of the scripts. Validation cases: lecture-python.myst#717 and #654.
+
+## 3. `audit` — the bulk-audit family
+
+Portfolio-wide, read-only sweeps of one repository, each delivering a report bundle. Four skills: **`/audit:issues`** (every issue, open and closed — landed), then **`/audit:prs`** (every open PR: does it solve a real issue, is it mergeable, what should the review say), **`/audit:tech-debt`** (a codebase's debt plus a filing-ready issue catalog), **`/audit:translations`** (parity between a source series and its translation).
+
+**Evidence:** unlike the style family, the case here is not per-repo frequency — a tracker audit is a once-or-twice-a-year event for any one repo. It is *breadth*: the org has ~245 non-archived repos, and three of the four procedures have already been executed by hand — the issue triage this plugin ships, the `quantecon-py` technical-debt report, and the zh-cn translation work. Each hand run cost hours of re-derivation because the method lived in a pasted prompt.
+
+**Structure (proposed 2026-07-26):** four sibling skills, no umbrella — unlike `qe`'s categories, these are distinct procedures over distinct inputs, so the `qe` pattern to reuse is plugin-level sharing, not the umbrella. The method is authored once in `audit/references/` (`doctrine.md`, `quantecon-context.md`, `deliverables.md`) and each `SKILL.md` carries only its own subject matter. Membership test: bulk **and** read-only **and** report-bundle output — which keeps single-item review (`/benchmark:review-acceleration`) outside the family and stops the plugin becoming a general runbook dump.
+
+**Why read-only is structural, not cautious:** the boundary mirrors the org's own automation split, where the family line *is* the permission line. It makes the family safe to point at any repo and safe to run headlessly, and it keeps a report honest — an audit that half-applied its findings would describe a repo that no longer exists. Acting on a bundle (filing the catalog, posting drafted comments, `qe gh labels sync`) is a separate human-invoked step.
+
+**Long-run machinery:** every skill runs the same five phases (snapshot → verify → relate → write → self-audit), each checkpointed to disk so a lost session resumes rather than restarts, and all reading one frozen snapshot so the report describes a single point in time. Phase 1 is deterministic (`audit/scripts/fetch_tracker.py`), which also makes the coverage self-audit mechanical rather than narrated.

README.md

@@ -10,8 +10,9 @@ Each plugin bundles one area of work — a skill (the instructions Claude follow
 |---|---|---|---|
 | `qe` | `/qe:check-style` (+ `check-writing`, `check-math`, `check-code`, `check-figures`, `check-jax`, `check-refs`) | scaffolding | [CATALOG.md](CATALOG.md), work plan in `project-style-guide` |
 | `benchmark` | `/benchmark:review-acceleration` | under construction | [meta#335](https://github.com/QuantEcon/meta/issues/335) |
+| `audit` | `/audit:issues` (+ planned `prs`, `tech-debt`, `translations`) | first runbook landed | [CATALOG.md](CATALOG.md) §3 |
 
-The `qe` plugin is the author-facing surface: one memorable prefix for the skills authors use while editing lectures and preparing PRs. `check-style` is the umbrella (whole lecture, optional category filter, e.g. `/qe:check-style lectures/aiyagari.md figures math`); the per-category sub-skills run the same shared rules individually. `benchmark` is a specialist family for maintainers evaluating accelerated implementations. See [CATALOG.md](CATALOG.md) for the plan and [FUTURE-IDEAS.md](FUTURE-IDEAS.md) for parked candidates.
+The `qe` plugin is the author-facing surface: one memorable prefix for the skills authors use while editing lectures and preparing PRs. `check-style` is the umbrella (whole lecture, optional category filter, e.g. `/qe:check-style lectures/aiyagari.md figures math`); the per-category sub-skills run the same shared rules individually. `benchmark` is a specialist family for maintainers evaluating accelerated implementations. `audit` is the maintainer-facing family for bulk, read-only sweeps of a whole repository — every issue, every PR, a whole codebase, a whole translated series — each delivering a report bundle rather than a chat answer. See [CATALOG.md](CATALOG.md) for the plan and [FUTURE-IDEAS.md](FUTURE-IDEAS.md) for parked candidates.
 
 ## Installation
 
@@ -33,12 +34,15 @@ Lecture repositories opt in by checking the following into their `.claude/settin
 }
 ```
 
+`audit` is deliberately absent from the lecture-repo block: it is maintainer tooling, and the plugin is the enable unit, so auto-installing it would put org-wide audit skills in every author's command list. Maintainers install it themselves.
+
 ### Manual (any project)
 
 ```
 /plugin marketplace add QuantEcon/skills
 /plugin install qe@quantecon
 /plugin install benchmark@quantecon
+/plugin install audit@quantecon
 ```
 
 ### CI (GitHub Actions)
@@ -68,6 +72,11 @@ benchmark/                        # specialist plugin
   .claude-plugin/plugin.json
   skills/review-acceleration/SKILL.md
   scripts/                        # supporting Python scripts the skill drives
+audit/                            # maintainer-facing bulk-audit plugin
+  .claude-plugin/plugin.json
+  skills/issues/SKILL.md          # one skill per audit subject
+  references/                     # shared doctrine, org context, bundle contract
+  scripts/                        # deterministic snapshot + coverage machinery
 ```
 
 ## Contributing

audit/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "audit",
+  "description": "Bulk, read-only audits of a QuantEcon repository — issue triage, PR review, technical debt, translation parity — each producing an evidence-cited report bundle",
+  "version": "0.1.0",
+  "author": { "name": "QuantEcon" }
+}

audit/README.md

@@ -0,0 +1,60 @@
+# audit
+
+Bulk audits of a QuantEcon repository. Where `qe` serves an author working on one lecture and `benchmark` evaluates one conversion, these skills sweep a whole portfolio — every issue, every PR, a whole codebase, a whole translated series — and deliver a report.
+
+## Skills
+
+| Skill | Audits | Status |
+|---|---|---|
+| [`/audit:issues`](skills/issues/SKILL.md) | Every issue, open and closed: status verified against the code, tiered into the repo's plan | runbook landed |
+| `/audit:prs` | Every open PR: does it solve a real issue, is it mergeable, what should the review say | candidate |
+| `/audit:tech-debt` | A codebase's accumulated debt, with a filing-ready issue catalog | candidate |
+| `/audit:translations` | Parity between a source series and a translation (`lecture-python.myst` ↔ `lecture-python.zh-cn`) | candidate |
+
+Only the first is written. The rest are candidates, tracked in [issue #12](https://github.com/QuantEcon/skills/issues/12) — each still needs the evidence a skill here normally carries before anyone writes it. Shipping one first is the point: the shared method gets proven against a real procedure before more are built on top of it.
+
+## What belongs here
+
+Two tests:
+
+1. **Bulk** — it sweeps a portfolio, not an item. Reviewing one PR's technical quality is not an audit; reviewing all of them is.
+2. **Read-only** — it observes and reports. No skill here mutates a tracker, a branch, or a file in the audited repo ([doctrine §3](references/doctrine.md#3-read-only-boundary)).
+
+The read/write line is the one that matters, and it is deliberate: it mirrors the org's own automation split, where the family boundary *is* the permission boundary. Anything that acts on findings — filing the catalog as issues, posting the drafted comments, applying labels — is a separate human-invoked step, which is what makes this family safe to point at any repo and safe to run headlessly.
+
+An audit also produces a written report rather than a chat answer, since the point is something a reader can check later. That says nothing about how long it is or how many files it takes — see [deliverables.md](references/deliverables.md), which describes what `/audit:issues` produces without requiring the next skill to match it.
+
+## Shared references
+
+Skills are thin; the method lives once at plugin level.
+
+| Document | Owns |
+|---|---|
+| [references/doctrine.md](references/doctrine.md) | Trust rules, evidence classes, read-only boundary, checkpointing, coverage self-audit |
+| [references/quantecon-context.md](references/quantecon-context.md) | Repo types, label ownership, the cross-repo graph, notes-system discovery, access |
+| [references/deliverables.md](references/deliverables.md) | What an audit owes its reader, where reports may land, and the `/audit:issues` bundle as a worked example |
+| [scripts/](scripts/) | Deterministic fetch machinery |
+
+## Running one
+
+```
+/audit:issues QuantEcon/action-translation
+```
+
+Audits are long. They work from a frozen snapshot and checkpoint each phase to disk, so a run that loses its session resumes at the last completed phase rather than restarting — and every number in the report refers to one point in time. Expect hours, not minutes, on a repo with a hundred items.
+
+Headless runs work the same way:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    plugin_marketplaces: "https://github.com/QuantEcon/skills.git"
+    plugins: "audit@quantecon"
+    prompt: "/audit:issues QuantEcon/action-translation"
+```
+
+## A note on naming
+
+Skill names here are objects because the plugin is the verb: `/audit:issues`, `/audit:translations`. Both read as commands, which is the part that matters, and `/audit:audit-issues` would stutter at every invocation.
+
+`audit` was chosen over `review` for the same reason the family excludes single-item work: `review` is already the per-item word here (`/benchmark:review-acceleration`, and PR review generally), so a `/review:prs` that sweeps every open PR would sit one keystroke from reviewing one. `audit` also matches QEP-3's `audit-` repo prefix and already connotes observe-and-report, which is the boundary this plugin enforces.

audit/references/deliverables.md

@@ -0,0 +1,46 @@
+# Reporting
+
+What an audit hands back. The four-document bundle below is what `/audit:issues` produces; it is a worked example, not a contract every skill in this plugin has to satisfy. A skill should produce what its subject actually needs — a debt audit's output is a filing-ready catalog, a parity audit's is a divergence list, and a small audit may reasonably be a single document. Reach for the bundle where it fits, and don't manufacture a section to fill a slot.
+
+What every audit owes its reader is much smaller, and is in the last section.
+
+## Where it goes
+
+**Never into `QuantEcon/skills`.** This repo holds the procedure; the findings belong with the thing audited. In order of preference:
+
+1. The audited repo's own notes system — `.dev/audits/<date>-<subject>/` or equivalent.
+2. The paired `project-*` repo, when the audit serves a program rather than a repo (`project-translation/reports/` for a translation audit).
+3. A dedicated `audit-*` repo, per [QEP-3](https://github.com/QuantEcon/qeps/pull/7), once an audit is recurring and its findings are worth publishing.
+
+Confirm the destination before writing, and name it in the report. Private inputs stay in private destinations: a `project-*` repo's contents must not be summarised into a public one.
+
+## The `/audit:issues` bundle
+
+Four documents, which suit a whole-tracker review because it has an argument to make, a long enumeration to carry, and a graph worth drawing separately. Another audit may need two of these, or none.
+
+**`01-<subject>-report.md`** — the argument. Method and evidence base; the snapshot timestamp; portfolio statistics; the findings that change a status, each with its evidence tag; the tiering, tied to the repo's existing plan; policy alignment; and a time-boxed execution order for whoever acts on it.
+
+**`02-<subject>-catalog.md`** — the enumeration. A legend, then a full summary table (item · tier · action · type · priority), then one entry per open item:
+
+> **Bold header line** — the item and its one-line characterisation
+> *Status:* what is actually true, with evidence and its tag
+> *Recommend:* the proposed action, and what it depends on
+> *Links:* related items, in and out of this repo
+
+Close with the verification of the closed set (explicitly thread-complete), and write up anything agreed-but-never-filed as a proposed new item, in a form that could be filed as-is.
+
+**`03-<subject>-links.md`** — the graph. Clusters and their anchor items; a concrete table of missing links worth adding; true orphans and over-dense hubs; and the external cross-link registry (sibling repos, program and meta issues, evidence PRs). This one is the most tracker-specific of the four — an audit whose subject has no interesting link structure should simply not produce it.
+
+**`README.md`** — the index. Headline numbers, what each document is for, and the coverage statement.
+
+Where a later audit does reuse this shape, keeping the names and the entry format identical is worth something: a reader who has read one bundle can read the next, and two audits of the same subject diff mechanically ([doctrine rule 7](doctrine.md#1-what-makes-a-bulk-audit-trustworthy)). That is a reason to converge where the shape fits, not a reason to force it.
+
+## What any audit owes its reader
+
+Short list, and this part is not advisory — each item is what keeps a long report checkable by someone who will not re-run it.
+
+- **A coverage statement.** Exactly what was and was not inspected, per [doctrine §5](doctrine.md#5-coverage-self-audit). In a bundle it belongs in the index; in a single document it is a section. It is the first thing a reader should be able to check and the last thing the audit should write.
+- **An evidence tag on every claim** ([doctrine §2](doctrine.md#2-evidence-classes)). An untagged status claim is a defect.
+- **Recommendations marked as proposals.** Write them in the imperative for whoever executes ("close, citing PR #204"), but the audit does not execute them.
+- **Drafted comment text marked as unsent**, in a fenced block — and subject to the closing-keyword hazard in [quantecon-context.md](quantecon-context.md#the-cross-repo-graph-is-the-point).
+- **A date and a named snapshot.** Two audits of the same subject must be distinguishable at a glance, and every number in a report refers to one point in time.