Smart Contract Audit Prep

Smart contract audit prep

Refuse first

• Do not fix source findings; record and classify them for the audit handoff.
• Do not install missing tools or touch remotes, credentials, deployments, or history rewrites.
• Do not declare readiness from prior reports or an untested commit.

Contract

Inputs

• Required: the target project directory; verify it is the project root before any write.
• Required: human answers on security objectives, concern areas, and the worst-case scenario for the goals document.
• Optional: prior audit reports or a known-concern list; they seed goals and known-issue notes.
• Optional: intended audit date; it only orders the readiness checklist.
• Platform, toolchain, and dependency facts are read from the project's manifests, never assumed.

Procedure

1. Confirm the target: verify the directory is a project root (manifest, lockfile, or build config present) and identify the platform (Solidity with Foundry or Hardhat, Rust, Go, or other). If root or scope is undeterminable, stop before any write and ask the human. Done when: the canonical project root, platform, and review scope are explicit before any artifact is written.
2. Set review goals: collect security objectives, areas of concern (prior findings, complex components, fragile parts), and the worst-case scenario; write audit/goals.md containing objectives, concern areas with file references, the worst-case scenario, and open questions for auditors. Done when: audit/goals.md contains every required goal element, with file references where the project provides them.
3. Run static analysis now: run the platform tool that exists (slither . --exclude-dependencies for Solidity, dylint --all for Rust, golangci-lint run for Go). A prior clean report is not evidence; a missing tool is a recorded gap, never an install. Triage every finding into audit/known-issues.md with a disposition of must-fix before audit, accepted risk with rationale, or informational. Done when: the available platform analyzer has run now and every finding or missing-tool gap has an explicit disposition in audit/known-issues.md.
4. Measure, do not eyeball: run the project's coverage command and automated dead-code detection; record measured coverage numbers with named untested paths plus unused functions, libraries, and stale features in audit/known-issues.md as recommendations. Do not delete or edit source. Done when: measured coverage, named untested paths, and dead-code results or unavailable-tool gaps are recorded without source mutation.
5. Freeze the review target: choose the commit auditors will review (prefer current HEAD only when its tests pass), create local branch audit-freeze and tag audit-freeze-<short-sha> at it, and record the hash, branch, tag, and dependency lock state. Deleting the branch and tag rolls this step back. Done when: one tested commit is identified by recorded hash, local freeze branch, local freeze tag, and dependency lock state.
6. Verify the build from cold: write audit/build-and-test.md with exact prerequisites and pinned versions, then execute every step in a fresh clone and record pass or fail with output. Put the in-scope and out-of-scope paths and the boilerplate map (copied, forked, third-party code) at the top of audit/architecture.md so review focuses on first-party code. Done when: the cold-clone transcript proves each documented build and test step, and audit/architecture.md opens with scope and boilerplate boundaries.
7. Generate architecture material: in audit/architecture.md, add actual diagrams of primary workflows and component relationships (mermaid or ASCII, not prose claims); user roles and interactions; on-chain and off-chain assumptions (oracle sources, bridge and trust boundaries, who validates what); the actor and privilege map with access controls; function-level notes for critical functions (invariants, parameter ranges, arithmetic and precision behavior); and a glossary of domain terms. Record documentation gaps as checklist items; never invent evidence. Done when: every named architecture element is present or an evidence-backed documentation gap is queued for the readiness checklist.
8. Assemble audit/readiness-checklist.md: one row for each item: goals documented, static analysis run and triaged, coverage measured, dead code listed, build verified from a cold clone, version frozen, diagrams present, user stories present, assumptions documented, actors and privileges listed, function notes complete, glossary complete. Give each row a pass or fail result and an evidence pointer, and include the frozen commit. Classify READY only when every row passes. Done when: every required row has a truthful result and evidence pointer, the frozen commit is named, and the terminal classification follows the all-pass rule.

Failure and recovery

Evidence and tool gaps

• Missing analysis tool: record the gap in audit/known-issues.md, mark its checklist row failed, continue the remaining steps; never install tools.
• Cold-clone build or test failure: record the exact failing step and output in audit/known-issues.md; readiness is NOT READY; do not patch source.

Scope and completion failures

• Undeterminable project root or scope: stop before any write and ask the human; this is the only outcome that produces no artifacts.
• Partial completion: keep every completed artifact and mark each unmet checklist row failed with its gap; the partial package is deliverable, READY is not.
• Never swallow a failed step or pass a failing row; the terminal classification is READY or NOT READY with named gaps, never an unverifiable claim.

Rollback

• Delete the audit/ directory, the audit-freeze branch, and the freeze tag; the project returns to its pre-invocation state.

Output

Output contract: Return audit/goals.md, audit/build-and-test.md, audit/known-issues.md, audit/architecture.md, and audit/readiness-checklist.md, then the local freeze branch and tag, then READY only if every checklist row passes, otherwise NOT READY with named gaps and evidence pointers.