audit-code
Audit Code
Section titled “Audit Code”HARD GATE — Audit must check for: bugs (correctness), security, performance, and clarity. Do NOT skip security review if the code touches user data, auth, or external APIs.
Target (argument)
Section titled “Target (argument)”If an argument was passed after /audit (e.g. /audit abc1234 or /audit HEAD~3..HEAD), use it as the diff target:
git diff <arg> # range or two-ref form: abc..def, HEAD~3..HEADgit show <arg> # single commit: abc1234If no argument was given, review uncommitted working-tree changes (git diff + git diff --staged).
Run this self-review before asking anyone else to look at the code. The goal is to catch everything that is clearly wrong or missing — so the reviewer can focus on design and architecture, not hygiene.
Distinct from request-review: This is the coding agent checking its own work. No second agent is involved. Run this first; run request-review after this passes.
Look-here-first (churn heuristic)
Section titled “Look-here-first (churn heuristic)”Before the checklist, rank changed files by git churn and review high-churn hotspots first — they carry the most latent risk regardless of diff size.
bash scripts/bp-churn-rank.sh --since 90.days --limit 15Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope.
- Default: full checklist
- –quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
- –gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (
exit 1) on ANY checklist failure;exit 0only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. - –parallel: Run checklist sections in isolated git worktrees (e45s18) so concurrent checks cannot corrupt each other’s working tree:
bash scripts/lib/parallel-review-worktrees.sh audit-codeChecklist
Section titled “Checklist”Supply Chain & Security
Section titled “Supply Chain & Security”- slopcheck run for new dependencies; packages tagged in plan-work:
[OK],[SUS], or[SLOP] - No
[SLOP]packages without documented human approval - No secrets in diff (
sk-,ghp_,AKIA,.envvalues) — seeguard-gitpatterns - OWASP Top 10 spot-check: injection, broken auth, sensitive data exposure, misconfiguration (see
docs/references/security-threats.md) - Security: diff scanned — no unaddressed HIGH findings (or deviations documented in
specs/security/EXCEPTIONS.md)
Provenance & Metadata
Section titled “Provenance & Metadata”- New plan artefacts include
type:andcontext:metadata - Implementation steps reference ADR or commit SHA where decisions were made
Law of Demeter
Section titled “Law of Demeter”- No method chains through unrelated objects (e.g.
a.getB().getC().doX()) - Collaborators talk to immediate neighbors only; law violations need explicit justification
CONVENTIONS.md Compliance
Section titled “CONVENTIONS.md Compliance”- All output files are in
specs/(no docs written to project root) - No
gh issue createcalls anywhere in new/modified skills or scripts -
ghused only for PRs and repo clone operations - No GitHub REST API called directly (no curl/fetch to api.github.com)
- Changes are limited to what was asked — nothing extra refactored or reorganized
- No speculative features added
- No files touched outside the stated scope
- Discovered defects: Reproducible gate failures (Preflight, CI, golden suite) require fix-or-log —
quick-fixorfix-bug— even when “outside” the story scope. Scope-minimization does not waive Always Green. - Boy Scout Rule applies to files opened to fix a gate failure; it does not excuse skipping red Preflight
Boy Scout Rule
Section titled “Boy Scout Rule”- Every file I touched is cleaner than when I found it
- No dead code left behind
- No commented-out code blocks
Types and Safety
Section titled “Types and Safety”- No
anytypes introduced (TypeScript) or untyped public functions (Python/Go/etc.) - No
@ts-ignoreor// eslint-disableadded - No
as unknown as Xcasts that bypass type safety
Test Coverage
Section titled “Test Coverage”- Every new function has at least one test
- Every bug fix has a regression test
- Tests verify behavior through public interfaces (not implementation details)
- Tests are F.I.R.S.T compliant (per CONVENTIONS.md §Tests; use
enforce-firstif unsure)
SOLID and Heuristics
Section titled “SOLID and Heuristics”- Single Responsibility: no function or module doing two unrelated things
- Open/Closed: extended through interfaces, not by modifying stable code
- Dependency Inversion: dependencies injected, not imported globally where avoidable
- Chapter 17 Heuristics: Code is free of smells documented in
audit-code/HEURISTICS.md(G, N, C, T)
Refactoring Smells (Fowler)
Section titled “Refactoring Smells (Fowler)”Explicitly name any detected smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man.
Code Style (CONVENTIONS.md)
Section titled “Code Style (CONVENTIONS.md)”- Functions: 4–20 lines; split if longer
- Functions: descend exactly one level of abstraction (The Stepdown Rule / G34)
- Files: under 300 lines (ideally 200–300)
- Names: specific and unique (grep returns < 5 hits for each name)
- No duplication — shared logic extracted (DRY / G5)
- Early returns over nested ifs; max 2 levels of indentation
- Conditionals: expressed as positives (G29)
- Comments explain WHY, not WHAT
Red Flags
Section titled “Red Flags”Before reporting, name any rationalization you caught yourself making for skipping a checklist item. Silence is not acceptable — if you skipped an item, state the reason explicitly.
Output
Section titled “Output”Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs to be fixed.
If all items pass: suggest running request-review for an independent second opinion.
If any items fail: fix them before proceeding.
In --gate mode, print one summary line per checklist section (PASS Supply Chain / FAIL Provenance (2 items)). Exit 0 only if all PASS. Write full report to specs/verifications/AUDIT-<epic>-<story>.md.
Verify
Section titled “Verify”→ verify: test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review
Handoff
Section titled “Handoff”Gate: READY -> next: commit-message Writes: state.yaml handoff.next_skill = commit-message
<!– story: e01s02 –> <!– story: e06s03 –> <!– story: e07s01 –>