audit-rotation

Files (3)

• SKILL.md
• rotation.py
• state.json

SKILL.md (first lines)

# Audit Rotation

One invocation = **one cycle**: first fix any findings still open from earlier
audits, then pick the next subsystem in the rotation, audit it once, then fix
**all** of that audit's findings — most important first, one commit each — until
the findings run out or the quota budget is spent. Then advance the rotation.
Driven by `/loop` (self-paced), it walks every subsystem, restarts when the
rotation completes, and pauses fixing whenever quota is spent.

**Audit once, then fix the whole report in one go** — do *not* re-audit between
fixes (no "audit, bugfix, audit, bugfix" churn). All auditing and fixing happens
**directly in this session**.

This skill is **self-contained**. Its only external dependency is the helper
`rotation.py` next to this file (rotation bookkeeping + quota gate); never
hand-roll ccusage parsing or cursor math. All paths below are relative to the
repo root. Run the helper with the repo's `.venv\Scripts\python.exe` or any
Python 3.14+.

## Procedure (one cycle)

### 0. Quota pre-check — bail early if spent

```
python .agents/skills/audit-rotation/rotation.py quota --json
```

- Exit **0** (under cap): proceed to step 1.
- Exit **1** (at/over cap): do **not** debug, audit, or fix this iteration.
  Report that quota is spent, note the `block_end` from the JSON, and end the
  cycle. If driven by `/loop`, schedule the next wake near `block_end` (the
  5-hour block reset), not sooner — auditing also costs quota.
- Exit **2** (unknown — ccusage failed): treat as spent. Skip fixing; you may
  still run the audit if the user wants read-only progress, but default to
  pausing and report the error.

### 1. Debug leftovers FIRST — drain the existing backlog before any new audit

Before auditing anything new, check whether previous audits left findings that
still need debugging:

```
python .agents/skills/audit-rotation/rotation.py findings --json
```

- Empty / exit **1** → no backlog. Go to step 2.
- Non-empty → there is unfinished debugging from a prior audit. **Fix it now,
  before auditing anything new.** Run the **Fix procedure** (below) over these
  findings, most-important-first, re-checking quota before each. If the quota
  gate trips while draining the backlog, **stop the cycle here**: report the
  remaining backlog and do *not* start a new audit (auditing also costs quota).

Only once the backlog is empty (or there was none) do you proceed to a fresh
audit. Track how many backlog findings you fixed.

### 2. Pick the scope

```
python .agents/skills/audit-rotation/rotation.py next --json
```

Gives `{name, paths, note}` for the subsystem to audit now (this does **not**
advance the cursor — that happens in step 5, so an interrupted cycle resumes on
the same scope).

### 3. Audit (read-only)

Audit exactly `paths` per the **Auditing** section below. Write the report to
`docs/audit/<scope>_audit_<YYYYMMDD>.md`, using the scope `name` so filenames
stay stable across cycles (a same-day re-audit gets a `_v2` suffix). Do not fix
anything in this step.

Commit the report on its own:

```
git add docs/audit/<scope>_audit_<date>.md
git commit -m "docs(audit): <scope> rotation audit <date>"
```

If the audit found **no actionable findings** (only N/design notes), skip to
step 5 with `--fixed 0` (plus any backlog fixes from step 1).

### 4. Fix EVERY finding from this audit — most important first, quota-gated

Run the **Fix procedure** (below) over the findings in the report from step 3,
repeating until the findings run out or the quota gate trips. Fix the whole
report in this one cycle, **in-session** — do not re-audit between fixes.

Keep a count of findings fixed this cycle (backlog + this report).

### 5. Advance the rotation

```
python .agents/skills/audit-rotation/rotation.py complete --report docs/audit/<scope>_audit_<date>.md --fixed <N>
```

`<N>` is the number fixed from **this cycle's audit** (step 4). This records
history and advances the cursor (wrapping to the next cycle when the last
subsystem is done). Commit the state bump on its own:

```
git add .agents/skills/audit-rotation/state.json
git commit -m "chore(audit-rotation): advance past <scope> (cycle <c>, fixed <N>)"
```

### 6. Report the cycle

State: how many backlog findings were drained first (and from which reports),
which scope was audited, the report path, severity counts, which findings were
fixed (by ID) with commit hashes, how many were left unfixed and why (quota vs
none-actionable), current quota (`$cost / $cap`), and the next scope.

If driven by `/loop`: when quota is healthy, self-pace a short delay before the
next cycle; when quota tripped mid-cycle, self-pace a long wait until `block_end`.

## Auditing (read-and-reason, do not fix)

Used by step 3. Examine the code as it exists and produce a prioritized,
evidence-backed report of what could break, what is fragile, and what could be

From nengoxx/ctrl-b, MIT.

More from nengoxx/ctrl-b