# Audit Loop

> Explicitly selected repo-wide audit and repair loop: map the codebase, rank consequential defects, fix within current contracts, and review each change. Use when the user chooses $audit-loop or binding task instructions require it. An ordinary audit, known bug, or request to fix a few findings does not select this persistent lifecycle.

- Skill: `aelaguiz/audit-loop` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add aelaguiz/audit-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aelaguiz/audit-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: aelaguiz (https://skillmd.com/u/aelaguiz)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aelaguiz/audit-loop

---


# Audit Loop

Use this workflow only after explicit selection as `$audit-loop` or a
binding task instruction requiring it.

## When to use

- The user wants a repo-wide audit pass rather than help with one already-known bug.
- The user wants the agent to build a full mental model of the repo before acting.
- The user wants to find and fix real bugs, dead code, duplication, or missing high-value tests in priority order.
- The user wants to run one manual pass now or leave the audit running in Codex or Claude Code until the worthwhile work is exhausted.

## When not to use

- The task is a concrete known bug, crash, regression, or Sentry issue. Use `bugs-flow`.
- The work is fixed-scope feature delivery or architecture planning. Use `arch-step`, `arch-mini-plan`, or `lilarch`.
- The task is an open-ended optimization or investigation loop where the path is unknown and the job is not primarily bug finding. Use native goal mode or `north-star-investigation`.

## Non-negotiables

- `_audit_ledger.md` at repo root is the source of truth. Add it to the root `.gitignore` immediately.
- Triage before code changes. Do not skip straight to editing because one suspicious line looks fixable.
- Exhaustively map shipped code surfaces and the current proof surface before any product-code or test edits. If the map is incomplete, update the ledger and stop.
- When independent surface families make delegation worthwhile, use bounded
  clean native read-only mapping slices. Otherwise build the same exhaustive
  map sequentially.
- Rank consequence and impact first, then proof weakness, then fragility. Do not let a tiny safe fix outrank a higher-consequence surface.
- Select a risk front from the completed map, not from a hunch.
- Fix bugs inside the existing product, API, and behavior contracts. If the only apparent fix would change a contract, log the conflict and stop.
- Verification depth must be proportional to downstream consequence and blast radius.
- Every editful pass must run a post-change audit on the actual diff and touched surfaces for safety, downstream consequences, elegance, and duplication before it can stop.
- If that audit fails, repair the issue in the same pass and re-verify before stopping.
- New duplication is illegal. Do not solve a risk front by copying logic, tests, or fallback handling into a second place.
- Reduce the top unresolved risk materially. Do not cash out a pass on a tiny safe fix while a bigger justified problem still dominates the repo.
- Dead code deletion counts as a fix. Duplication on critical paths counts as real bug prevention work.
- It is acceptable and often necessary to touch multiple files, modules, and tests when they belong to the same risk story.
- Broader same-story cleanup is allowed when the post-change audit shows the current fix is awkward or duplicative, but keep it inside the same contract and risk front. Do not build a framework.
- Prefer behavior-level verification and integration coverage on critical paths. Do not write negative-value tests.
- When you add or materially rewrite a test, leave comments in the test that explain why the behavior matters and what correct user-visible or externally observable outcome should happen. The goal is to make misunderstandings easy to spot later, not to narrate the assertion line by line.
- Unrelated dirty or untracked files are not a blocker. Leave them alone unless they directly conflict with the current risk front or make verification unsafe.
- Default invocation with no mode is `run`.
- `review` is docs-only.
- `auto` is goal-mode friendly. In native goal mode, keep running `run` then `review` until no credible audit work remains or a real blocker stops it. Outside goal mode, run one bounded pass and name the exact next command.
- No auto commits. Keep the ledger truthful without relying on git history.

## First move

1. Read `references/ledger-contract.md`.
2. Read `references/shared-doctrine.md`.
3. Read `../_shared/agent-orchestration-policy.md` before dispatching any
   mapping or review child.
4. Resolve the mode:
   - `run`
   - `review`
   - `auto`
5. Resolve repo root, root `.gitignore`, and `_audit_ledger.md`.
6. Read the matching mode reference and `references/quality-bar.md`.

## Parent And Child Roles

- The active parent owns audit scope, ledger writes, decomposition, every
  child-result account, synthesis, accepted repair direction, and the final
  controller verdict. Capture current git status and the relevant diff before
  read-only children run, then compare current state before accepting their
  evidence.
- Mapping slices and each independent `review` critic default to new clean
  same-host native children. In Codex set `fork_turns: "none"`; in Claude use
  a clean named or custom subagent, not a bare conversation fork or skill
  `context: fork` shorthand. Use bounded or full inherited context only for a
  named dependency that exists solely in chat; ordinary context travels via
  the ledger, exact paths, and the child brief.
- Give mappers and critics the strongest read-only capability the host exposes
  and explicitly tell them not to edit or write files, including the ledger.
  They may use their own native sub-agents on their own host; they may not start
  external agents.
- Split only across independent surface families or review lenses. Bound
  fanout by available host slots, shared-file or shared-state collision risk,
  and the parent's capacity to inspect and integrate every return.
- If a controller needs a background or external process after the parent turn
  ends, that transport supplies lifecycle continuity, not critic freshness.
  Choose it only when that concrete lifecycle or another benefit is worth its
  process and integration cost under the shared policy.

## Workflow

### 1) `run`

- Create or repair `_audit_ledger.md` and the `.gitignore` entry.
- Build or refresh the exhaustive map of shipped code surfaces and the current proof surface.
- If the map is incomplete, record the next unfinished mapping tranche in `Next Area`, update the ledger, and stop without edits.
- Once the map is complete, rank risk fronts by consequence first, then proof weakness, then fragility.
- Pick the highest-priority unresolved risk front from that ranking and record the pre-edit proof plan plus the post-change audit focus.
- Read the implementation before the tests, log findings, and fix the strongest justified work across that risk front.
- When the pass adds or materially rewrites tests, make the intent clear in the test code itself so a later reader can see the why and the expected experience or outcome without reconstructing it from the assertion body.
- Verify the changes with proof proportional to the front's consequence.
- Audit the resulting diff and touched surfaces for safety, unintended downstream consequences, elegance, and duplication. If any lens fails, repair it in the same pass and re-verify.
- Update the ledger and stop only when further useful work would require a genuinely different audit story, a new reconnaissance pass, or a real blocker.

### 2) `review`

- Stay docs-only.
- Repair the ledger if it is missing or malformed.
- Have a new clean independent critic re-read the ledger and current repo
  state without writing files; the parent spot-checks and integrates its
  return.
- Confirm whether the map is complete, whether the current or next front comes from the ranked map, and whether verification depth matched the front's consequence.
- Confirm whether the latest editful pass completed and passed the post-change audit for safety, downstream consequences, elegance, and duplication.
- Check whether audit-loop-added or materially rewritten tests explain their purpose clearly enough for a later reviewer to spot a misunderstanding in the protected behavior or expected experience.
- Set the controller verdict to `CONTINUE`, `CLEAN`, or `BLOCKED` and name the next mapping tranche, risk front, or blocker plainly.

### 3) `auto`

`auto` is the repeated audit loop. Native goal mode supplies the repeated turns;
this skill does not install or arm automation hooks.

Workflow:

1. Run one truthful `run` pass. Mapping-only is correct on the first turns.
2. Run a new clean independent `review` critic against `_audit_ledger.md` and
   current repo state, using a same-host native child by default while the
   parent session is active.
3. If review says `CONTINUE`, run the next `$audit-loop run` pass.
4. In native goal mode, keep repeating until review says `CLEAN` or `BLOCKED`.
5. Outside native goal mode, stop after one run/review cycle and print the next exact command.

`audit-loop`-specific rules:

- User-facing invocation is just `audit-loop auto`.
- Dirty or untracked files are not a blocker. Do not refuse to run only because the repo has unrelated dirty or untracked files.
- `auto` must not degrade into a tiny-safe-fix treadmill or skip exhaustive mapping just to land a quick patch.
- Do not auto-commit findings.

## Output expectations

- Update `_audit_ledger.md` in every mode.
- Keep console output short:
  - audit North Star reminder
  - punchline
  - current mapping tranche, risk front, or verdict
  - evidence or tests run
  - next action

## Reference map

- `references/ledger-contract.md` - root ledger shape, status vocabulary, and cleanup lifecycle
- `references/shared-doctrine.md` - prioritization, fix discipline, and anti-patterns
- `references/run.md` - mapping-aware audit or fix pass
- `references/review.md` - new clean docs-only verdict pass
- `references/audit-loop-controller.md` - audit-loop auto status and verdict source
- `references/quality-bar.md` - strong vs weak triage, findings, tests, and stop decisions