Project Audit

Project Audit

A real audit is evidence-driven. Every finding points at a line, a route, a table or a config key, and every finding carries a way to prove the fix. Opinions without locations are not findings.

Phase 0 — Scope and consent (2 minutes, never skipped)

Establish before reading code:

1. What is in scope? Repository only, or also the live site, infrastructure and third-party accounts?
2. What is the audit for? Pre-launch gate, investor due diligence, an inherited codebase, a security concern, or a general health check. This changes what gets weighted.
3. What may be run? Read-only analysis is always safe. Ask before installing dependencies, running tests, starting services, or touching anything that reaches production.
4. Is there a live URL? If yes, the web-presence-audit, accessibility-audit and privacy-compliance passes become live checks rather than code inference.

Never scan, probe or send traffic to infrastructure the user has not confirmed they own or are authorised to test.

State the scope in one line and begin.

Phase 1 — Ground truth

Run the discovery protocol from senior-engineer/references/discovery-protocol.md. scripts/recon.sh (or recon.ps1 on Windows) automates the first pass and prints a structured summary — run it if the environment allows, and fall back to the manual commands if not. It is read-only.

Do not proceed to findings until the Ground Truth block is filled in. An audit built on a misread stack is worse than no audit.

Phase 2 — The fifteen domain passes

Load the specialised skill for each domain rather than working from memory.

Scale the depth to the project. Not every audit needs all fifteen at full depth:

• Quick scan (a small app, a first look): domains 1, 2, 3, 11 at depth; the rest as a one-line status each.
• Standard audit (the default): all fifteen, depth proportional to weight.
• Deep audit (due diligence, pre-funding, regulated): all fifteen at depth, plus a threat model, a restore drill and a load test.

Say which depth you are running, and why.

Parallelising. For a large codebase, running domain passes concurrently as subagents is the right call — dispatch security, data, testing and web-presence as independent reviewers, then merge. This skill authorises that; give each agent the Ground Truth block so nobody re-derives it.

Phase 3 — Evidence discipline

For every candidate finding, before it enters the report:

Can I point at the exact location?          -> if no, keep investigating or drop it
Can I state the concrete consequence?       -> if no, it is a preference, not a finding
Did I verify it, or am I inferring?         -> label CONFIRMED or PLAUSIBLE
Can I name a way to prove the fix works?    -> if no, the fix is underspecified

Confirm before escalating. A missing authorization check might be enforced in middleware you have not read. A missing index might exist under a different name. Grep for the mitigating control before calling something a P0 — a false P0 costs you the reader's trust for the whole report.

Sample when exhaustive is impossible. On a large codebase, review every auth-adjacent, money-adjacent and personal-data-adjacent path exhaustively, and sample the rest. Say what you sampled and at what rate.

Phase 4 — Score and report

Apply the rubric in senior-engineer/references/severity-and-reporting.md. Use templates/audit-report.md as the output shape.

Write to a file (AUDIT.md or docs/audit-YYYY-MM-DD.md) when the report is longer than a screen — a report that scrolls out of a terminal does not get acted on. Offer to publish it as a shareable artifact if the user wants to circulate it.

Mandatory sections, in this order:

1. Verdict — can this ship, what breaks first, what does the fix cost.
2. Score — NN/100 with the three weakest domains named.
3. Ground Truth.
4. Findings — P0, P1, P2, P3, each fully formed.
5. Scorecard — fifteen rows, each with a one-line justification.
6. Remediation plan — ordered, with effort estimates.
7. What I could not verify — never empty by omission.

Phase 5 — Remediation, on request

If the user asks you to fix rather than only report:

• Fix in severity order, P0 first. One finding per commit.
• Write the failing test before the fix wherever a test is possible.
• Do not bundle refactors with security fixes; a reviewer must be able to see the fix.
• Re-verify each fix with the verification step written in the finding, and report the actual result.
• If a fix turns out to be wrong or infeasible, say so and leave the finding open rather than quietly closing it.

Calibration

Grade against what this project claims to be, not against a hypothetical ideal. A weekend side project with no users and a fintech handling card data are held to different standards on scalability and process — and to identical standards on secrets in git, SQL injection, and honest privacy claims.

Two failure modes to avoid in equal measure:

• Flattery. Grading generously so the user feels good. They asked for a senior review; give them the number the evidence supports.
• Performative severity. Inflating findings to look thorough. A P0 that is not exploitable teaches the reader to ignore your P0s.

References and assets

• references/architecture-review.md — how to assess structure, boundaries, coupling
• references/stack-playbooks.md — per-stack specifics (Next.js, Django, Rails, Laravel, Spring, Go, .NET, Flutter, mobile)
• references/quick-scan.md — the 30-minute version and its command sequence
• templates/audit-report.md — the full report template
• scripts/recon.sh / scripts/recon.ps1 — read-only reconnaissance