Audit

Multi-level code review. All agents inherit the session model. Reviewers bold-labeled; Workers plain.

This skill exercises Layer 3 (Orchestrator) and Layer 9 (Security). After the review prints, a fix gate asks the user whether to apply the findings — on Yes, audit auto-invokes /hyperflow:plan with the findings as the spec, which then chains to /hyperflow:dispatch.

Iron Rules

Failure recovery (DOCTRINE rule 14). Worker errors, malformed output, NEEDS_REVISION verdicts, and gate failures in every Step follow the canonical policy in skills/hyperflow/failure-recovery.md. Audit-specific exception: a failed Reviewer at L1/L2 escalates to an L3+ Reviewer at the same severity level rather than aborting — audit exists to catch issues, so a Reviewer failure is best resolved by a more thorough Reviewer, not by stopping the chain.

Per-Step Agent Map (DOCTRINE rule 12)

Step	Sub-phase	Workers	Reviewers	Notes
1 — Resolve scope	—	—	—	Mechanical decision (exempt)
2 — Gather context	2a — Surface mapping	Searcher × 2 (glob + import-graph)	Reviewer	Parallel
2 — Gather context	2b — Semantic indexing	Searcher × 2 (type-system + symbol-graph)	Reviewer	Parallel
2 — Gather context	2c — Convention scan	Searcher × 1 (test patterns + lint config)	Reviewer	Justified single-angle
2 — Gather context	2d — Aggregate coverage gate	—	Reviewer verifies aggregate coverage	Standalone coverage gate
3 — Review	3a — L1+L2 (syntax/format/naming)	—	Domain specialist Reviewer × 2 (file groups, surface-matched) + Reviewer aggregates	Parallel pair dispatched as the matching domain specialists
3 — Review	3b — L3 (integration/security)	—	Reviewer × 2 — backend-reviewer + security-reviewer/vulnerability-reviewer + Reviewer aggregates	Parallel pair; security specialists web-research-first
3 — Review	3c — L4+L5 (perf/scale/a11y/UX)	—	Reviewer × 2 — performance-reviewer + accessibility-reviewer + Reviewer aggregates	Parallel pair dispatched as the matching specialists
4 — Findings synthesis	4a — Critical findings	Writer × 2 (evidence probe + impact analysis)	Reviewer	Parallel
4 — Findings synthesis	4b — Important findings	Writer × 2 (root-cause probe + fix-path analysis)	Reviewer	Parallel
4 — Findings synthesis	4c — Suggestions + observations	Writer × 2 (pattern analysis + praise identification)	Reviewer	Parallel
4 — Findings synthesis	4d — Memory feedback	Writer × 1 (anti-pattern curation)	Reviewer (dedup + compaction validation)	Atomic Worker→Reviewer; runs after 4a/4b/4c complete; with compaction pass when triggered
5 — Severity reconciliation	—	—	Reviewer reconciles severity labels from Step 3 sub-phases	Atomic-exempt per DOCTRINE 12.2.8 — reads existing Step 3 labels; no Workers needed
6 — Fix gate	—	—	—	AskUserQuestion only (exempt — structural gate)

Approval Gates

Gate	When	Format
Fix gate	Step 6, after NEEDS_FIX or PASS-with-suggestions	AskUserQuestion — fix all / criticals only / no
Hard halt	Any SECURITY_VIOLATION from the reviewer	Stop, surface the finding; no fix gate

Inputs

• Target — file path, line range, commit SHA, branch, or PR number provided by the user
• Default (no target) — git diff HEAD + git diff --staged
• Level flag — --level 1 through --level 5 (default — L2)

Review Levels

Adapted from review-levels.md:

L	Name	Checks
1	Quick	Syntax, obvious bugs, formatting
2	Standard	L1 + spec compliance, naming, edge cases
3	Thorough	L2 + cross-file consistency, integration risks, security
4	Deep	L3 + architecture, scalability, accessibility
5	Exhaustive	L4 + adversarial probing, perf profiling, alternatives

Security scan (hardcoded secrets, injection, path traversal, XSS, missing validation) is mandatory at L3+. See security.md.

Flow

Step 1 — Resolve scope

Use the provided target or run git diff HEAD + git diff --staged. No agent dispatched (read-only git).

Targets accepted: a path/glob, an explicit file list, or a git range ... The range form is how a two-session handoff review runs — /hyperflow:handoff review reads the build's COMPLETION.md diff range and invokes audit as Skill audit ".. level=", so the review covers exactly the second session's commits (git diff ..). See ../hyperflow/session-handoff.md.

Step 2 — Gather context

Sub-phases 2a, 2b, 2c run in parallel (P1). Step 2 output is the union of their worker outputs plus three sub-phase Reviewer verdicts, handed to a standalone aggregate coverage gate. The Searchers also record which surfaces the diff touches (frontend / api / db / devops / mobile / data-ml / security) — this drives the domain-specialist selection in Step 3 (../../agents/README.md).

Step 2a — Surface mapping

Dispatch two Searcher agents in parallel:

• Searcher — glob discovery (file extensions, directory tree, entry points)
• Searcher — import-graph traversal (follow import/require/use chains from touched files)

Then dispatch Reviewer — 2a surface mapping coverage check. Verdict ∈ {PASS, NEEDSREVISION, ESCALATE}. On NEEDSREVISION, re-dispatch only 2a.

Step 2b — Semantic indexing

Dispatch two Searcher agents in parallel:

• Searcher — type-system probe (interface/schema definitions relevant to changed symbols)
• Searcher — symbol-graph probe (callsites, usages, exported references of changed symbols)

Then dispatch Reviewer — 2b semantic indexing coverage check. Verdict as above.

Step 2c — Convention scan

Dispatch one Searcher agent (single-angle justified — test patterns and lint config are a single orthogonal corpus with no independent axis to fan out across):

• Searcher — convention scan (existing test patterns, lint rules, naming conventions, code-style config)

Then dispatch Reviewer — 2c convention scan coverage check. Verdict as above.

Step 2d — Aggregate coverage gate

After 2a + 2b + 2c complete, dispatch Reviewer — verifying aggregate context coverage to confirm the combined surface covers all subsystems relevant to the diff. On coverage gap: re-dispatch the affected sub-phase (max 2 retries); surface gap to user if retries exhausted.

Step 3 — Review

Sub-phases 3a, 3b, 3c run in parallel (P1) — each ends with a sub-phase aggregator Reviewer before the next batch fires. Active sub-phases scale with --level: L1-L2 runs only 3a; L3 adds 3b; L4-L5 add 3c.

Specialist selection. Step 2 detects which surfaces the diff touches (frontend, api, db, devops, mobile,

data/ml, …). Step 3 dispatches each Reviewer as the matching domain specialist

(../../agents/README.md) — its charter + strict checklist injected, and (audit is a

gated flow) its web-research-first pass run for current best-practice / CVE currency. When the target has a

spec/task file, its Brain-decided Specialists roster seeds the selection.

Step 3a — L1+L2: syntax, formatting, naming

Dispatch two Reviewer agents in parallel over different file groups (split by directory or feature boundary),

each as the domain specialist matching that group's surface (frontend-reviewer / backend-reviewer /

api-reviewer / database-reviewer / devops-reviewer / mobile / data-ml-reviewer):

• Reviewer (domain specialist) — L1+L2 review, file group A (syntax errors, obvious bugs, formatting, naming conventions)
• Reviewer (domain specialist) — L1+L2 review, file group B (same checklist, different file group)

Then dispatch Reviewer — 3a aggregation to union the two verdicts and deduplicate overlapping findings. Verdict ∈ {PASS, NEEDSREVISION, ESCALATE}. On NEEDSREVISION, re-dispatch only 3a.

Step 3b — L3: integration, security (L3+ only)

Dispatch two Reviewer agents in parallel over different concern dimensions — as the security specialists:

• Reviewer (backend-reviewer or api-reviewer) — L3 integration risks (cross-file consistency, API contract mismatches, race conditions, edge cases)
• Reviewer (security-reviewer + vulnerability-reviewer) — L3 security scan (hardcoded secrets, injection, path traversal, XSS, missing validation, known-CVE exposure — per security.md, web-research-first on current advisories)

If the security Reviewer emits SECURITY_VIOLATION: → halt immediately; skip the fix gate; surface the finding inline; user decides remediation.

Then dispatch Reviewer — 3b aggregation to union the two verdicts. Verdict as above.

Step 3c — L4+L5: performance, scalability, accessibility, UX (L4+ only)

Dispatch two Reviewer agents in parallel — as the matching specialists:

• Reviewer (performance-reviewer) — L4+L5 performance and scalability (algorithmic complexity, memory, bundle size, adversarial load)
• Reviewer (accessibility-reviewer) — L4+L5 accessibility and UX (WCAG compliance, keyboard nav, screen-reader semantics, interaction design)

Then dispatch Reviewer — 3c aggregation to union the two verdicts. Verdict as above.

The Reviewer uses the reviewer-prompt.md template with the diff, level definition, and any applicable spec. Each sub-phase produces structured [Critical] / [Important] / [Suggestions] / [Praise] findings that feed into Step 4.

Step 4 — Findings synthesis

Write the full structured audit to .hyperflow/audits/-.md. Sub-phases 4a, 4b, 4c run in parallel (P1), each authoring a section of the audit file. The audit file also receives a memory-append section per memory-system.md.

Step 4a — Critical findings

Dispatch two Writer agents in parallel:

• Writer — evidence probe (trace each Critical finding back to the diff line; confirm reproducibility)
• Writer — impact analysis (articulate user-visible / system-level consequence for each Critical finding)

Then dispatch Reviewer — 4a critical findings review to verify each Critical entry has a confirmed fix path and no false positives. Verdict ∈ {PASS, NEEDS_REVISION, ESCALATE}.

Step 4b — Important findings

Dispatch two Writer agents in parallel:

• Writer — root-cause probe (trace each Important finding to its origin; confirm it's not a symptom of a Critical)
• Writer — fix-path analysis (propose the recommended change per finding, with file:line anchors)

Then dispatch Reviewer — 4b important findings review. Verdict as above.

Step 4c — Suggestions, observations, and memory append

Dispatch two Writer agents in parallel:

• Writer — pattern analysis (identify Suggestion-level improvements; extract reusable patterns for memory)
• Writer — praise identification (flag genuinely well-done decisions; append durable patterns to .hyperflow/memory/learnings.md per memory-system.md)

Then dispatch Reviewer — 4c suggestions + memory dedup check to ensure no duplicate memory entries land and no Suggestions are mis-classified as Important. Verdict as above.

Step 4d — Memory feedback (runs after 4a/4b/4c complete)

After the audit file is written, curate recurring problem patterns into .hyperflow/memory/anti-patterns.md so future audit runs and workers benefit from accumulated findings. This is an atomic Worker→Reviewer pair.

Dispatch one Writer agent:

• Writer — anti-pattern curation (read .hyperflow/memory/anti-patterns.md if it exists; extract up to 3 new entries from the [Critical] and [Important] findings produced in 4a/4b; append or update the file)

Curation rules the Writer must follow:

• Only [Critical] and [Important] findings are eligible — Suggestions and Praise are excluded.
• Before writing, read the existing anti-patterns.md. If a matching pattern already exists, increment its frequency counter and update last seen. Do not create a duplicate entry.
• Limit: max 3 new pattern entries per audit run. When more than 3 eligible findings exist, prioritize by breadth — multi-file findings before single-file findings.
• Append entries in this format:

## <pattern category> (e.g. Error handling, Naming, Dead code)
- <description> — first observed in audit <YYYY-MM-DD>, frequency: <count>, last seen: <YYYY-MM-DD>
  Recommendation: <what workers should do to avoid this>

• Tag anti-patterns.md as #hot in the session memory index so workers load it at session start alongside other hot-tier files.

Compaction pass (runs after the Writer appends new entries, not before):

New findings always land first. After the append, the Writer checks whether compaction is needed. Compaction is triggered when ANY of the following is true:

• Total entry count in anti-patterns.md exceeds 50.
• Any entry has last seen more than 6 months ago AND frequency == 1 (stale singleton — never reinforced).
• File line count meets or exceeds the memory.compactionThreshold (default 300, from ~/.hyperflow/config.json).

When triggered, the Writer runs these actions in order:

1. Merge duplicates. Entries in the same category with similar wording are merged into one. Combined frequency = sum of the merged entries; last seen = most recent of the merged entries. Wording is taken from the higher-frequency entry.
2. Archive stale singletons. Entries where frequency == 1 AND last seen is older than 6 months move to .hyperflow/memory/archive/YYYY-MM.md (month derived from the entry's last seen date), tagged with their source so they remain retrievable. This is the same shared monthly archive convention used by /hyperflow:cache compact — see skills/cache/references/compaction.md.
3. Cap at 50 entries. If the file still exceeds 50 entries after merge and archive, evict the lowest-frequency entries. Tiebreak: oldest last seen is evicted first. Never evict entries derived from [Critical] findings — the highest-severity patterns are exactly the ones that must keep surfacing; if eviction is needed and only Critical-sourced entries remain over the cap, leave the file over-cap and note it for the next compaction. Evicted entries move to the same shared monthly archive.
4. Hot-tier is already wired. anti-patterns.md is permanently hot-tier (see memory-system.md). The post-compaction file is injected automatically at the next session start. No manual hot-tier refresh is needed.

If compaction was triggered but none of the three actions has anything eligible to do (e.g. the line-count threshold tripped on a verbose but already-deduped ≤50-entry file), the Writer skips the rewrite — no no-op compaction dispatch. If compaction was not triggered at all, the Writer skips this block entirely and proceeds to the Reviewer.

Then dispatch Reviewer — 4d anti-pattern dedup and compaction check to verify: no duplicate entries landed, frequency counters are accurate, only Critical/Important findings were promoted, the new-entry count does not exceed 3, and — when compaction ran — no critical entries were dropped without archiving and the archive sidecar was written correctly. Verdict ∈ {PASS, NEEDSREVISION}. On NEEDSREVISION, the Writer re-reads the file and corrects the specific violation (max 1 retry before surfacing inline).

Step 5 — Severity reconciliation (atomic-exempt per DOCTRINE 12.2.8)

Dispatch one Reviewer — severity reconciliation to consolidate the [Critical] / [Important] / [Suggestion] / [Praise] labels already emitted by Step 3 sub-phases (3a/3b/3c). No Workers are dispatched: the Reviewer reads existing Step 3 labels and resolves any conflicts across sub-phases (e.g. a finding flagged [Important] in 3a and [Critical] in 3b resolves to [Critical]). Verdict ∈ {PASS, NEEDSREVISION}. On NEEDSREVISION, the Reviewer annotates the specific conflict; the orchestrator applies the resolution inline (no re-dispatch).

After Step 5 completes, the orchestrator writes the graded findings into the audit file (Step 4 section headers get severity labels applied) and prints the chat summary (file-first, DOCTRINE rule 8):

── Audit Result ──────────────────────
Scope:    main..HEAD (13 files)
Level:    L3
Verdict:  NEEDS_FIX
Findings: 0 Critical · 4 Important · 4 Suggestions · 5 Praise
Written:  .hyperflow/audits/2026-05-16-1730-memory-compaction.md
─────────────────────────────────────

No [Critical] / [Important] body lines in chat. The user opens the file (or the chat host previews it). For PASS-clean runs (no Critical/Important), print just the one-line Audit clean — no fixes needed. and still write the file with the praise + suggestions list (so the audit history is preserved). Skip the file write only on SECURITY_VIOLATION — those need immediate eye-level surfacing; print the finding inline and halt.

Step 6 — Fix gate (STRUCTURAL GATE · DOCTRINE rule 8)

After the summary prints, the audit skill MUST ask the user via AskUserQuestion whether to apply the findings. Per DOCTRINE rule 8, this gate always fires when findings exist — autonomy directives do NOT skip it. Defaulting silently is a doctrine violation.

Skip the gate only when: verdict is PASS with no [Critical] or [Important] entries (Suggestions-only or Praise-only). Stop after the one-line Audit clean — no fixes needed. summary.

Skip the gate also when: verdict is SECURITY_VIOLATION. Halt and let the user decide.

Otherwise, ask:

?  Audit findings written to .hyperflow/audits/<timestamp>-<slug>.md — apply fixes?

   Fix all (Recommended)   — Critical + Important + Suggestions via /hyperflow:plan → /hyperflow:dispatch
   Critical + Important    — skip Suggestions, fix the rest
   Critical only           — fix the must-haves, defer the nice-to-haves
   No, leave as-is         — stop; you'll handle manually

Recommended option scales with finding mix:

• Any [Critical] present → Fix all (Recommended) — Critical items can't be deferred
• Only [Important] + [Suggestions] → Critical + Important (Recommended)
• Only [Suggestions] → No, leave as-is (Recommended) — Suggestions are optional by definition; the gate fires but recommends skipping

On any "Fix …" choice:

1. Build a spec file from the chosen findings at .hyperflow/specs/audit--.md. Each finding becomes a numbered fix section with: file:line, the issue, the reviewer's suggested fix (or "design needed" if no Fix: was provided), and the commit message stub. The spec file is the chain-driving artefact; do NOT paste fix bullets into chat.
2. Invoke Skill with skill: plan and args: "session=one spec=.hyperflow/specs/audit--.md".
3. /hyperflow:plan will decompose into batches; /hyperflow:dispatch will execute them — same per-sub-task commit cadence and per-batch L1–L review as any other chain run.

On "No":

Print one line and stop:

Audit complete — N findings recorded, no fixes applied. Re-run /hyperflow:audit later or invoke /hyperflow:plan manually if you change your mind.

If AskUserQuestion cannot be presented as a popup, use the portable-surface fallback (Codex / OpenCode / Grok): print the fix gate as a Hyperflow Question chat block with numbered options, then stop and wait for the user's answer. If no interactive channel is available at all, print the findings and an error line — never silently auto-fix or silently exit.

Output Format

Two outputs per audit run:

1. The audit file at .hyperflow/audits/-.md — full structured review, formatted per ../hyperflow/artefact-format.md:

# Audit — <scope description>

## Status

| Field    | Value                                                |
|----------|------------------------------------------------------|
| Verdict  | `<PASS \| NEEDS_FIX \| SECURITY_VIOLATION>`          |
| Scope    | `<files / range / commit>`                           |
| Level    | L<n>                                                 |
| Findings | N Critical · N Important · N Suggestions · N Praise  |
| Date     | <YYYY-MM-DD HH:mm>                                   |

## TL;DR

<2–3 sentences: the most important takeaway + the most important fix
to apply. The user reads this and decides whether to dig into the
findings list.>

## Findings

### [Critical] `<file>:<line>` — <one-line issue title>

**Issue:** <one paragraph: what's broken and why it's blocking>

**Fix:** <one paragraph: the recommended change, with the file:line
anchor and the suggested replacement>

**Why it matters:** <one sentence: the user-visible or system-level
consequence if shipped as-is>

### [Important] `<file>:<line>` — <one-line issue title>
...

### [Suggestion] `<file>:<line>` — <one-line improvement title>
...

### [Praise] `<file>:<line>` — <one-line note>
...

## Security scan (L3+ mandatory)

| Category          | Result                |
|-------------------|-----------------------|
| secrets           | pass                  |
| injection         | pass                  |
| path traversal    | pass                  |
| DoS               | pass | concerns       |
| missing validation| pass | concerns       |

## Cost

| Role      | Agents | Tokens   |
|-----------|-------:|---------:|
| Worker    |      1 |     ~Nk  |
| Reviewer  |      1 |     ~Nk  |
| **Total** |  **2** | **~Nk**  |

2. The chat summary — one short box that points at the file, NEVER the findings themselves:

── Audit Result ──────────────────────
Scope:    <files / range>
Level:    L<n>
Verdict:  <PASS | NEEDS_FIX | SECURITY_VIOLATION>
Findings: 0 Critical · 4 Important · 4 Suggestions · 5 Praise
Written:  .hyperflow/audits/<YYYY-MM-DD-HHmm>-<scope>.md
──────────────────────────────────────

Hand-off

• PASS (no findings worth fixing) — print Audit clean. Suggest /hyperflow:deploy if the user is ready to release. Do not auto-ship.
• NEEDS_FIX — fix gate fires (Step 6). On Yes … → auto-chain to /hyperflow:plan. On No → stop with findings printed.
• SECURITY_VIOLATION — halt. Skip the fix gate. User decides remediation path.

Doctrine

Full rules in DOCTRINE.md. Output style in output-style.md. Per-step agent dispatching follows rule 12.

Overview

/hyperflow:audit runs a multi-level code review against uncommitted changes, a specific commit, branch, or PR. Searchers gather context; a standalone Reviewer produces verdicts at the chosen level (L1 quick scan to L5 exhaustive). On NEEDS_FIX, a structural gate asks the user whether to apply findings — Yes auto-chains to /hyperflow:plan, which decomposes the fix and then stops at its own build-location gate before any build starts; No leaves the diff alone.

Prerequisites

• Git repository with the change(s) to review present in the working tree, staged, or in history.
• .hyperflow/ cache optional but recommended (Layer 0 analysis improves reviewer context). Run /hyperflow:scaffold first if missing.

Instructions

See Flow above — Steps 1-6 are the operational instructions. Summary:

1. Resolve scope (target arg or git diff HEAD).
2. Surface mapping + semantic indexing + convention scan (2a/2b/2c in parallel); aggregate coverage gate (2d).
3. L1+L2 syntax/naming (3a) + L3 integration/security (3b) + L4+L5 perf/a11y (3c); each sub-phase Reviewer pair → aggregator.
4. Findings synthesis: Critical (4a) + Important (4b) + Suggestions/memory (4c) — each sub-phase Writer pair → Reviewer.
5. Severity reconciliation (atomic-exempt — single Reviewer consolidates Step 3 labels); print chat summary pointing at audit file.
6. Fix gate fires on NEEDS_FIX with critical/important findings.

Output

See Output Format above for the exact block. Single review block per invocation; agent count line at the bottom shows the model/role split.

Error Handling

Failure	Behavior
No diff to review (clean working tree, no target)	Print Nothing to review — clean working tree. Pass an explicit target. and stop.
Searcher returns no context (file gone, bad path)	Reviewer flags [Critical] — target unreachable and halts at Step 3.
Reviewer emits SECURITY_VIOLATION (L3+ only)	Skip Step 4 onward. Print finding. Do not fire fix gate. User decides remediation.
AskUserQuestion popup unavailable (Codex / OpenCode / Grok)	Print the fix gate as a Hyperflow Question chat block and wait for the user's answer.
No interactive channel at all	Print findings + an error line stating the fix gate could not fire. Never silently auto-fix or silently exit.
Reviewer disagrees with worker context (NEEDS_FIX on Step 2 coverage check)	Re-dispatch Searcher with the reviewer's gap list. Max 2 retries before surfacing the gap to user.

Examples

Worked transcripts moved to examples.md so the SKILL body stays lean. The examples are illustrative — not load-bearing for behaviour. Read the companion file when you want to see end-to-end transcripts.

Resources

• DOCTRINE.md — orchestration rules (especially #8 structural gates, #12 per-step agents).
• review-levels.md — full checklist for L1-L5.
• reviewer-prompt.md — reviewer template.
• security.md — security scan policy (mandatory at L3+).
• memory-system.md — how patterns are persisted.
• output-style.md — label and table conventions.