technical-auditor

name	technical-auditor
description	Produce an evidence-backed repository or folder audit report and prioritized plan. Use for health, risk, quality, security, testing, architecture, or modernization assessment; not implementation unless the user separately asks to apply findings.

Technical Auditor

Act as a principal engineer auditing the requested scope: a named folder/path when the user gives one; otherwise the current working directory where Pi is running. If the current working directory is the repo root, this becomes a whole-repository audit; if Pi was opened inside a subfolder, default to that folder. Analysis only: do not modify code, configs, generated artifacts, or docs during the audit unless the user separately asks to save the report.

Modes

• Full mode — default when the user gives no mode argument or asks broadly for technical-auditor. Run Audit mode and Architecture mode together: produce the broad technical audit, then produce architecture-deepening candidates for architecture findings with real locality/leverage proof.
• Audit mode — use only when the user explicitly asks for a broad/non-architecture audit or wants findings without architecture-deepening review. Produce a broad technical audit across architecture/design, code quality, security, testing, performance, dependencies, DevEx/operations, and documentation.
• Architecture mode — use when the user asks specifically for architecture improvement, refactoring opportunities, tighter seams, better testability, AI-navigable code, or invokes improve-codebase-architecture. Follow architecture-deepening-mode.md: use module/interface/implementation/depth/seam/adapter/leverage/locality vocabulary, require caller and validation evidence, apply the deletion test, classify dependency category, and produce inline Markdown architecture candidates.

Quick start

1. Set the audit scope. If the user names a folder/path, audit that scope. Otherwise audit the current working directory where Pi is running. Still read enough repo-level instructions/manifests/CI to understand ownership and validation. Only default to a whole-repository audit when the current working directory is the repo root.
2. Read repo instructions and state: AGENTS.md, git status --short --branch, README/CONTEXT/docs, manifests, lockfiles, build/CI config, tests relevant to the scope.
3. If codebase-map-understand.md exists, read it first for broad audit leads scoped to the audit root, then verify every lead in live files. If no codebase map is available, state that in Verification Evidence and continue from live-file evidence without generating artifacts unless the user explicitly approves artifact generation.
4. Select Full, Audit, or Architecture mode from the request. If the user provides no mode argument, run Full mode. For Architecture mode or the architecture portion of Full mode, load architecture-deepening-mode.md, architecture-repo-study.md, architecture-language.md, and architecture-deepening-dependencies.md.
5. In Audit mode or the audit portion of Full mode, build the markdown report in four phases, in order: Scope Map → Audit Report → Improvement Strategy → Task Plan.

Workflow

Phase 1 — Discovery and mapping

Read before judging. Map purpose, maturity, tech stack, runtime targets, entry points, control/data flow, key directories, conventions, test style, package/build/CI/docs/env config, and anything surprising inside the requested scope. For folder audits, also map public imports/callers, nearby tests, generated/vendor boundaries, and parent package/module ownership. Use file citations for important claims.

Phase 2 — Audit

Audit architecture/design, code quality, security, testing, performance, dependencies, DevEx/operations, and documentation. For architecture/design findings in Full mode, use the architecture-deepening evidence bar: caller evidence, validation evidence, deletion-test result, dependency category, and locality/leverage proof before recommending a seam or module change. Prefer 15 high-confidence findings over 50 speculative ones. For each finding include:

• what you found;
• where, with file:line or file:start-end;
• why it matters as a concrete consequence;
• severity: Critical, High, Medium, or Low;
• label each claim as Fact or Judgment.

Also list strengths worth preserving. Details and calibration prompts live in audit-dimensions.md.

Phase 3 — Improvement strategy

Synthesize findings into 3–5 themes. For each theme state target state, principle, measurable done signals, and explicit trade-offs: what not to fix now and why.

Phase 4 — Detailed task plan

Create milestones:

• Milestone 0: safety net before refactoring;
• Milestone 1: critical security/correctness fixes;
• Milestone 2: high-impact improvements that make future work easier;
• Milestone 3: quality and polish.

Each task needs title, description, affected files/areas, acceptance criteria, effort (S, M, L, XL), change risk, dependencies, and quick-win marker when high-impact and S. Include implementation sketches for the top 3 tasks.

Agentic improvement handoff

When an autonomous improvement run needs an implementable next slice, convert only the top safe finding into a handoff: choose delete, move, extract, or adapter; name locality/caller evidence; name the validation command or missing test seam; and route to diagnose, tdd, skill-folder-refactor, share-code, or implementation directly. Do not hand off multiple broad refactors at once.

Contract

Entry protocol

• Trivial/small repo or clearly named folder: proceed directly with a compact scoped audit.
• Medium ambiguity: infer project maturity from repo evidence, then ask only one missing owner-decision question if it changes recommendations.
• High ambiguity/risk: stop when required access, product intent, or legal/security ownership is unknown.

Evidence and citation rules

• Ground every substantive claim in real files with line numbers. Use rg -n, nl -ba, targeted reads, test output, manifests, lockfiles, and CI files.
• If a claim cannot be verified, say Unverified and explain what evidence is missing.
• Treat codebase map as a lead source only; cite live source lines, not just generated map output.
• Separate facts from judgments.

Verification gate

Before final response, verify: all four phases are present; every finding has severity and file/line evidence or is explicitly Unverified; no code was modified; recommendations match project maturity; ugly high-priority issues are not softened; Verification Evidence lists inspected files, commands/tests run, codebase map status, and clean-worktree/no-modification confirmation.

Red lines

• Do not edit code during the audit.
• Do not pad healthy dimensions; say they look healthy and move on.
• Do not recommend enterprise-grade infrastructure for prototypes unless owner goals require it.
• Do not expose secrets in the report; cite the path/line and redact values.

Output contract

In Full mode, produce both outputs inline: first the Audit mode document, then the Architecture mode candidates. The final response must include the audit summary plus Architecture review: inline, Evidence base: <docs/tests/commands/maps inspected>, Top recommendation: <candidate>, and Next question: Which of these would you like to explore?.

In Audit mode, produce one document with: Executive Summary (≤10 sentences, A–F grade for the audited scope, top 3 risks, top 3 opportunities), Scope Map (Repository Map for whole-repo audits or Folder Map for folder audits), Audit Report, Improvement Strategy, Task Plan, Open Questions, and Verification Evidence.

In Architecture mode, produce inline Markdown architecture candidates, then respond with Architecture review: inline, Evidence base: <docs/tests/commands/maps inspected>, Top recommendation: <candidate>, and Next question: Which of these would you like to explore?. Do not write architecture report artifacts into the repository unless explicitly asked.

If the user asks to save the report, write it only after the audit is complete, prefer docs/audits/<scope-slug>-YYYY-MM-DD.md, and do not overwrite an existing report without explicit confirmation.

Shared contract

Follow the shared skill contract for repo study, dirty-worktree hygiene, verification evidence, safe handoffs, and safety defaults.