audit-code

name	audit-code
description	Use when auditing an implementation against its plan. A clean agent follows behind a worker, verifying every decision, obligation, and detail. Triggers on "audit", "verify implementation", "check against plan", "review what was built", or when an implementation phase completes and needs validation before merging.

Implementation Auditing

A clean agent that verifies an implementation against its plan. You are NOT the implementer — you are the auditor. You have no context from the implementation session. You work only from the plan document and the actual code.

When to Use

• After an implementation phase completes
• When reviewing a PR or branch against its design doc
• When the user suspects an implementation drifted from the plan
• As the final gate before merging

When NOT to Use

• During implementation (use /solving-bugs or /wrapping-up-programming)
• For code review without a plan to audit against
• For style/convention review (use /conventions)

---

Process

Step 1: Load the Plan

Read the plan document. Extract every:

• Decision: an architectural or design choice that constrains the implementation
• Obligation: something the plan says MUST be done (feature, behavior, test, constraint)
• Boundary: an explicit scope limit (what's in, what's out)

Create a checklist from these. Every item gets verified or flagged.

Step 2: Four-Pass Audit (4 Parallel Agents)

Launch 4 agents simultaneously. Each reads the plan and all changed files, but focuses on a different lens. Each agent records its findings via audit_session_update.

Agent 1: Comprehension & Completeness

What does this code do? Map each change to the plan.

• For each plan obligation: identify the code that implements it (file:line)
• For each code change: identify the plan item it serves
• Flag: missing obligations, unplanned additions, partial implementations
• State what each function/block is supposed to do BEFORE evaluating whether it does it (guards against plausibility trap)

Status	Meaning
✅ Verified	Implementation matches plan
❌ Missing	Plan required it, implementation doesn't have it
⚠️ Deviated	Implementation does something different than planned
➕ Unplanned	Implementation adds something not in the plan

Agent 2: Correctness & Contracts

Does the code actually do what Agent 1 says it does?

• Invariants: for each data structure, state the invariant and verify every mutation preserves it
• Contracts: for each function, verify preconditions are checked and postconditions hold on ALL exit paths (including error paths and early returns)
• Boundary conditions: for each parameter and state variable, check empty/zero/nil, singleton, max, overflow
• State machines: identify implicit state machines, check every (state, event) pair has defined behavior

Agent 3: Integration & Side Effects

How does this change affect the rest of the system?

• Call site audit: for every interface change (signatures, types, protocols), check ALL call sites — not just those in the diff
• Dependency direction: verify no reverse dependencies introduced
• State mutations: does new code modify shared state other components depend on?
• Performance: new code in hot paths (request handling, render loop, tight loops)
• Migration/deployment: does the change require schema migration, config changes, or deployment ordering?

Agent 4: Adversarial & Error Paths

Try to break it. Think like an attacker, not a reviewer.

• For each function: "What input would make this crash?"
• For each state: "What timing would make this race?"
• For each invariant: "What sequence of operations would violate this?"
• Error path coverage: trace every error source to its handler — does it clean up, propagate correctly, give useful info?
• Cascading failures: if error handler A fails, what happens?
• Dead paths: code that exists but is never exercised, stubs, TODOs, placeholders
• Test coverage: every obligation, every error path, every boundary condition — is it tested?

Step 3: Synthesize

After all 4 agents complete, synthesize their findings into a single report.

Each finding gets a confidence level:

• CERTAIN: concrete, reproducible, no ambiguity ("line X indexes [0] on unguarded empty array")
• LIKELY: reasonable analysis with stated assumptions ("race condition between lines X and Y if called concurrently")
• POSSIBLE: depends on conditions not fully known ("O(n²) may matter with large datasets")

Only CERTAIN and LIKELY findings go in the handoff to the implementer. POSSIBLE findings are noted but do not block.

Step 4: Report

Present findings organized as:

1. Verified — what matches the plan (brief)
2. Missing — what the plan required but isn't implemented
3. Deviated — what diverged from the plan and how
4. Unplanned — what was added without plan coverage
5. Dead paths — code that goes nowhere
6. Untested — obligations and paths without test coverage
7. Recommendation — pass, fix-and-reaudit, or rethink

---

Graph-Native Audit Session

Use brain-mcp's audit session tools to create a persistent, queryable audit trail in the structure graph.

Before Starting

1. Create an audit session with audit_session_create:

   • slug: descriptive identifier (e.g., auth-middleware-v2-round-1)
   • scope: what is being audited (e.g., "auth middleware rewrite against plan://brain/auth-middleware-v2")
   • plan_uri: the plan:// URI being audited against
   • about_uris: code/topic URIs in audit scope

2. Check for prior audit sessions by querying the graph for audit:// nodes linked to the same plan. If this is a re-audit after fixes, verify whether prior findings were resolved.

During the Audit

Each agent records findings via audit_session_update:

• finding: description of the finding
• severity: info, warning, error, or critical
• category: correctness, completeness, integration, security, style, etc.
• code_uri: project:// URI of the specific code this finding refers to
• about_uris: additional linked URIs for cross-referencing

After Synthesis

Close the audit session with audit_session_close:

• verdict: pass, fail, or partial
• summary: brief summary of audit results

The graph trail (audit:// nodes with about edges to plan:// and project:// nodes) must be sufficient to reconstruct every decision made during the implementation.

Rules

• You are a fresh agent. Do NOT carry assumptions from an implementation session.
• Every claim must reference a specific file and line range.
• "Looks fine" is never acceptable. Verify or flag.
• Do not suggest fixes. Report findings. The implementer fixes.
• If the plan is ambiguous, flag the ambiguity — do not interpret it charitably.
• If there is no plan document, stop and say so. You cannot audit without a plan.

Common Mistakes

Mistake	Fix
Trusting that code "looks right"	Trace every obligation to specific code
Skipping test coverage check	Every obligation and error path needs a test
Charitable interpretation of ambiguity	Flag it — ambiguity is a finding
Suggesting fixes in the audit	Report only — implementer fixes
Auditing without reading every changed file	Read everything, no skimming
Ignoring unplanned additions	Unplanned code is a finding, not a bonus