CTRL NODE
← Back to article · Internal artifact

Audit Prompt

You are a world-class, principal-engineer-level software engineer and technical audit expert. Your task is to perform an in-depth analysis of this code repository, provide an honest audit report, and offer a prioritized, actionable improvement plan.

Please strictly follow the four phases below in order. Do not skip steps. All judgments must be based on real file evidence: cite file paths and line numbers. If something cannot be verified, state it explicitly — do not guess.

Phase 1 — Discovery & Mapping: Read First, Then Judge

Before forming any conclusions, systematically explore the entire repository:

  • Map the directory structure: project type, languages, frameworks, runtime targets.
  • Identify entry points, core modules, and primary data/control flows.
  • Read: package manifests, lockfiles, build configs, CI configs, env/config files, and all documentation (README, CONTRIBUTING, ADRs, etc.).
  • Determine the project's purpose: goals, intended users, and current maturity level (prototype / internal tool / production service / library).
  • Document existing conventions: naming, module boundaries, error handling patterns, testing style — so suggestions align with the existing engineering culture.

Output for this phase: A concise "Repository Map" including: purpose, tech stack, architectural sketch, key directories with one-line descriptions, and anything that surprised you.

Phase 2 — Audit: Evidence-Based, with Severity

Perform an audit across these dimensions. For each finding, record:

a) What you found b) Where: File:LineNumber c) Why it matters (concrete consequences, not abstract principles) d) Severity: Critical / High / Medium / Low

Architecture & Design

Module boundaries, coupling/cohesion, circular dependencies, leaky abstractions, God objects/files, layer violations, scalability bottlenecks.

Code Quality

Duplication, dead code, complexity hotspots (longest functions, most branches), inconsistent patterns, error handling gaps (swallowed exceptions, missing edge cases), type safety vulnerabilities.

Security

Hardcoded secrets or credentials, injection risks, unsafe deserialization, missing input validation, auth/authorization weaknesses, outdated dependencies with known CVEs, overly permissive configurations.

Testing

Coverage gaps (especially core business logic), test quality (behavior vs just "runs"), missing test types (unit/integration/e2e), flaky test patterns, hard-to-test code.

Performance

N+1 queries, unnecessary allocations/copies, blocking calls in async paths, missing caching or indexing, unbounded growth (memory, files, queues).

Dependencies

Outdated, unmaintained, duplicate, or unnecessarily heavy dependencies; license risks; lockfile maintenance.

Developer Experience & Operations

Build/startup costs, CI/CD gaps, missing linting/formatting enforcement, logging & observability quality, error reporting, deployment paths.

Documentation

README accuracy, onboarding paths, undocumented critical behaviors, docs contradicting actual code.

Rules for this phase

  • Prefer 15 high-confidence findings over 50 speculative ones.
  • Differentiate fact from judgment. Label them clearly.
    • Fact: "This function has no error handling: src/api/client.ts:142"
    • Judgment: "The responsibility boundaries of this module feel unclear"
  • Also list what the repository does WELL. Strengths matter — they define what to preserve.

Output for this phase: An "Audit Report" — grouped by dimension, sorted by severity, with a Strengths section. Highlight the most urgent issues.

Phase 3 — Improvement Strategy

Synthesize audit findings into a strategic approach:

  • Identify 3–5 themes explaining most issues (e.g., "No enforced layer boundaries", "Error handling is ad-hoc").
  • For each theme: propose a target state and the underlying principles.
  • Explicitly state trade-offs: which problems NOT to fix now, and why (effort/reward mismatch, high risk, project maturity doesn't warrant it yet).
  • Define "done" with measurable signals: e.g., "CI fails on lint errors", "Core module coverage ≥ 80%", "No Critical findings".

Phase 4 — Detailed Task Plan

Translate the strategy into an execution plan. Each task must include:

  • Title and short description
  • Affected files/areas
  • Acceptance criteria (how to verify it's complete)
  • Workload estimate:
    • S = < 2 hours
    • M = half a day
    • L = 1–2 days
    • XL = needs further breakdown
  • Risk of the change (potential to break existing functionality)
  • Dependencies on other tasks

Organize tasks into milestones:

  • Milestone 0 — Safety Net: things that must be in place before safe refactoring — key path tests, CI gates, backups.
  • Milestone 1 — Critical Fixes: security issues and correctness problems.
  • Milestone 2 — High-Leverage Improvements: changes that make all subsequent work easier.
  • Milestone 3 — Quality & Polish: remaining medium/low-priority items worth addressing.

Call out QUICK WINS separately: high-impact, S-effort tasks that can be done immediately. For the top 3 priority tasks, include a brief implementation sketch: approach, key steps, and potential pitfalls.

Final Delivery Format

Generate a single document with the following sections:

  1. Executive Summary (max 10 sentences)
    • Overall health grade: A–F with justification
    • Top 3 risks
    • Top 3 opportunities
  2. Repository Map (Phase 1 output)
  3. Audit Report (Phase 2 output)
  4. Improvement Strategy (Phase 3 output)
  5. Task Plan (Phase 4 output)
    • Organized by milestone
    • Quick wins highlighted
    • Implementation sketches for top 3 tasks

Generate the output as a well-structured Markdown document calling audit-report-sonnet-1706.md.

Additionally, generate a standalone HTML file called audit-report-sonnet.html with integrated CSS (no external dependencies) that presents the same information as an interactive dashboard with the following tabs:

  • Overview — Executive Summary, health grade (A–F styled as a large badge), top risks and opportunities.
  • Repository Map — Tech stack, architecture sketch, key directories table.
  • Audit Report — Findings grouped by dimension, each with severity badge (Critical=red, High=orange, Medium=yellow, Low=green), file:line references, and a strengths section.
  • Improvement Strategy — Thematic issues, target states, trade-offs, and "done" criteria.
  • Task Plan — Milestones as collapsible sections; each task as a card with workload badge (S/M/L/XL), risk level, and acceptance criteria. Quick wins highlighted in a separate top section.

Design requirements for the HTML:

  • Dark theme with a professional tech aesthetic.
  • Tab navigation at the top, fully functional with pure JavaScript (no frameworks).
  • Each tab must have substantial content — do not summarize; replicate the full detail from the Markdown.
  • Responsive layout.
  • Save the file in the repository root as audit-report-sonnet-1706.html.