Use when the user wants a code review on recent changes — quality, spec, security, or performance feedback. Triggers a multi-level (L1-L5) review with a standalone Reviewer; on NEEDS_FIX, offers to apply findings via /hyperflow:plan.
Trigger with /hyperflow:audit, "review this change", "review my PR", "audit the diff", "code review".
Use when the user wants a code review on recent changes — quality, spec, security, or performance feedback. Triggers a multi-level (L1-L5) review with a standalone Reviewer; on NEEDS_FIX, offers to apply findings via /hyperflow:plan.
Trigger with /hyperflow:audit, "review this change", "review my PR", "audit the diff", "code review".
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.
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 <base>..<head>. The range form is how a two-session handoff review runs — /hyperflow:handoff review <slug> reads the build's COMPLETION.md diff range and invokes audit as Skill audit "<base>..<head> level=<n>", so the review covers exactly the second session's commits (git diff <base>..<head>). 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).
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):
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, NEEDS_REVISION, ESCALATE}. On NEEDS_REVISION, 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.
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/<YYYY-MM-DD-HHmm>-<scope-slug>.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
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:
## <patterncategory> (e.g. Error handling, Naming, Dead code)-<description> — first observed in audit <YYYY-MM-DD>, frequency: <count>, last seen: <YYYY-MM-DD>
Recommendation: <whatworkersshoulddotoavoidthis>
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:
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.
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.
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.
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, NEEDS_REVISION}. On NEEDS_REVISION, 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, NEEDS_REVISION}. On NEEDS_REVISION, 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):
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.
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:
Build a spec file from the chosen findings at .hyperflow/specs/audit-<YYYY-MM-DD>-<scope-slug>.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.
Invoke Skill with skill: plan and args: "session=one spec=.hyperflow/specs/audit-<YYYY-MM-DD>-<scope-slug>.md".
/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/<YYYY-MM-DD-HHmm>-<scope-slug>.md — full structured review, formatted per ../hyperflow/artefact-format.md:
# Audit — <scopedescription>## 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-DDHH: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-lineissuetitle>**Issue:**<oneparagraph:what'sbrokenandwhyit'sblocking>**Fix:**<oneparagraph:therecommendedchange, withthefile:lineanchorandthesuggestedreplacement>**Why it matters:**<onesentence:theuser-visibleorsystem-levelconsequenceifshippedas-is>### [Important] `<file>:<line>` — <one-lineissuetitle>
...
### [Suggestion] `<file>:<line>` — <one-lineimprovementtitle>
...
### [Praise] `<file>:<line>` — <one-linenote>
...
## 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:
/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:
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.
