{"slug": "repo-audit-improvement-plan-repo-audit-slash-command-for-claude-code-parallel", "title": "Repo Audit & Improvement Plan — /repo-audit slash command for Claude Code (parallel subagents, adversarially verified findings, agent-executable task plan)", "summary": "A developer has created a \"/repo-audit\" slash command for Claude Code that performs a principal-engineer-grade repository audit using parallel subagents and adversarially verified findings. The tool maps the repository, fans out subagents across audit dimensions while mining git history for churn and complexity hotspots, then verifies every Critical and High finding against actual code before generating a comprehensive AUDIT.md report. The read-only command produces an executive summary with health grades, severity-rated findings, and a milestone-ordered task plan with runnable acceptance criteria that can be handed directly to fresh agent sessions.", "body_md": "A principal-engineer-grade repository audit, tuned for Claude's latest models running inside Claude Code.\n\nIt maps the repo, fans out parallel subagents (one per audit dimension, plus git-history mining for churn × complexity hotspots), adversarially verifies every Critical/High finding against the actual code before reporting it, runs the repo's own lint/type-check/test commands instead of guessing at health, and writes a single AUDIT.md containing:\n\nExecutive Summary — health grade A–F, top 3 risks, top 3 opportunities\n\nRepo Map\n\nSeverity-rated findings (file:line cited, facts separated from judgments)\n\nImprovement strategy — the 3–5 themes behind the findings, with measurable \"done\" signals\n\nA milestone-ordered task plan where each task is a self-contained brief a fresh agent session can execute, with runnable acceptance criteria\n\nQuick wins flagged separately\n\nRead-only: it never modifies your code. The report is the only file it creates.\n\nInstall — user-wide (available in every repo)\n\n```\nmkdir -p ~/.claude/commands\ncurl -fsSL https://gist.githubusercontent.com/OmerFarukOruc/753f95b1ac278b683be83ed26b3bcc1f/raw/repo-audit.md -o ~/.claude/commands/repo-audit.md\n```\n\nOpen a new Claude Code session and run /repo-audit.\n\nInstall — single project only\n\n```\nmkdir -p .claude/commands\ncurl -fsSL https://gist.githubusercontent.com/OmerFarukOruc/753f95b1ac278b683be83ed26b3bcc1f/raw/repo-audit.md -o .claude/commands/repo-audit.md\n```\n\nInstall — manual\n\nCopy the contents of repo-audit.md from this gist into ~/.claude/commands/repo-audit.md. That's it — Claude Code picks up the file automatically.\n\nUsage\n\n```\n/repo-audit\n```\n\nPass an optional focus: /repo-audit security or /repo-audit src/billing.\n\nRun it in normal mode, not plan mode. The audit is read-only; plan mode inserts an approval stop that costs you nothing but waiting.\n\nFor very large repos where you want maximum depth, opt into multi-agent orchestration explicitly: /repo-audit use a workflow (or include the word ultracode).\n\nThe audit runs end to end without check-ins — it's read-only and safe to leave running.\n\nOutput lands in AUDIT.md at the repo root, written for a reader who didn't watch the run.\n\nWhy this version\n\nThis is a rework of the viral \"Repo Audit & Improvement Plan\" prompt, restructured around how current Claude models actually work best:\n\nPurpose over persona — states why the audit exists (the report becomes a work queue for future agent sessions) instead of role-playing a \"world-class engineer\".\n\nOrchestrated, not single-threaded — parallel subagents per dimension instead of one linear pass.\n\nVerified, not just cited — fresh-context subagents try to refute each Critical/High finding; what doesn't survive gets dropped or downgraded. Claims are checked against actual tool output (including really running the test suite) before they enter the report.\n\nHistory-aware — mines git history for bug-fix-dense, high-churn files instead of auditing a frozen snapshot.\n\nAgent-executable output — tasks have runnable pass/fail acceptance criteria, so you can hand each one straight to a new Claude Code session.\n\nPrincipal-level repo audit → evidence-verified findings → agent-executable task plan\n\nargument-hint\n\noptional focus — a subdirectory\n\ndimension\n\nor concern\n\nRepo Audit & Improvement Plan\n\nContext — why this audit exists\n\nI maintain multiple products solo and don't have time to review tech debt by hand.\nYour audit becomes the work queue for future Claude Code sessions: each task you\nproduce will be handed to a fresh agent with no other context. Audit accordingly —\ntruth over reassurance; a flattering report is worthless to me.\n\nAudit focus for this run, if any: $ARGUMENTS\n\nGround rules\n\nEvery finding cites file:line you actually read this session. If you can't verify\na claim, label it unverified — never guess. Before writing the final report, check\neach claim against a tool result from this session.\n\nAnalysis only. Do not modify code, config, or dependencies. The only file you\ncreate is the report.\n\nDon't just read claims of health — observe them. Run the repo's own read-only\ncommands (install, lint, type-check, test suite, dependency audit) where practical,\nand report outcomes faithfully: if the tests fail, say so with the output.\n\nCalibrate to the project's maturity — don't demand enterprise rigor of a prototype.\nIf the repo is large, go deep on the core 20% that does 80% of the work, and say\nwhat you skipped.\n\nPrefer 15 high-confidence findings over 50 speculative ones. Separate facts from\njudgments. If a dimension is healthy, say so in one sentence and move on. List\ngenuine strengths too — they tell me what to protect.\n\nHow to work\n\nIf you were launched in plan mode, every decision is already made here: your plan\nis one line (\"run this audit as specified\") — submit it for approval immediately.\n\nFan out parallel subagents: Explore agents for discovery first, then one auditor\nper audit dimension, spawned as a single parallel batch and each handed the repo\nmap so it doesn't re-derive it. Keep synthesizing while they run.\n\nIf a repo tool (pnpm, yarn, a linter) is missing from PATH, try corepack or\nversion-manager shims (mise, asdf, nvm) before concluding it's absent.\n\nPlain subagents (the Agent tool) are the right default: you keep synthesizing,\nsteering refuters, and re-verifying citations between waves. Only if my\ninvocation says \"use a workflow\" or \"ultracode\" should you script the fan-out\nwith the Workflow tool instead — treat those words as orchestration opt-in,\nnot as an audit focus.\n\nMine git history, not just the snapshot: high-churn × high-complexity files,\nbug-fix-dense modules, abandoned directories, the age of TODO/FIXME comments.\n\nAdversarial verification: before any Critical or High finding enters the report,\na fresh-context subagent must try to refute it against the actual code. Drop or\ndowngrade findings that don't survive.\n\nWork end to end without checking in — this is read-only and safe. When you have\nenough information to act, act.\n\nPhase 1 — Discovery (read before judging)\n\nMap: purpose and intended users, stack and runtime targets, entry points, core\nmodules, main data/control flow, build/CI/env config, existing conventions (so\nrecommendations fit the culture, not fight it), maturity level. Output a concise\nRepo Map, including anything that surprised you.\n\nEach finding: what, where (file:line), why it matters, severity\n(Critical/High/Medium/Low), confidence, fact-or-judgment.\n\nPhase 3 — Improvement strategy\n\nThe 3–5 themes that explain most findings; target state and the principle behind\nit per theme; what you are NOT fixing and why (effort vs payoff); \"done\" defined\nas measurable signals (e.g. \"CI fails on lint errors\", \"core-path coverage ≥ 80%\").\n\nPhase 4 — Task plan\n\nDiscrete tasks a fresh Claude Code session can execute from the brief alone:\ntitle, one context paragraph, files affected, acceptance criteria as runnable\nchecks wherever possible (a command that passes or fails), effort (S <2h,\nM half-day, L 1–2 days, XL needs breakdown), risk, dependencies. Order into\nmilestones:\n\nM0 — Safety net: tests around critical paths, CI gates\n\nM1 — Critical fixes: security and correctness\n\nM2 — High-leverage: changes that make all future work easier\n\nM3 — Quality & polish\n\nFlag quick wins (high impact, S effort) separately. Include implementation\nsketches for the top 3 tasks.\n\nDeliverable\n\nWrite one file, AUDIT.md, at the repo root. Open it with the audited commit SHA,\nthe date, and a one-paragraph method note ending in the refuter tally (findings\nrefuted outright / downgraded / survived). Then: Executive Summary (health grade\nA–F, top 3 risks, top 3 opportunities) → Repo Map → Audit Report (worst first) →\nImprovement Strategy → Task Plan → Open Questions (each naming the decision I\nneed to make).\n\nWrite it for a reader who didn't watch you work: lead with the outcome, complete\nsentences, spell out terms, no working shorthand. Don't pad — be selective about\nwhat you include, don't compress the writing.", "url": "https://wpnews.pro/news/repo-audit-improvement-plan-repo-audit-slash-command-for-claude-code-parallel", "canonical_source": "https://gist.github.com/OmerFarukOruc/753f95b1ac278b683be83ed26b3bcc1f", "published_at": "2026-06-10 10:36:00+00:00", "updated_at": "2026-06-11 22:43:51.144106+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "large-language-models"], "entities": ["Claude Code", "Claude"], "alternates": {"html": "https://wpnews.pro/news/repo-audit-improvement-plan-repo-audit-slash-command-for-claude-code-parallel", "markdown": "https://wpnews.pro/news/repo-audit-improvement-plan-repo-audit-slash-command-for-claude-code-parallel.md", "text": "https://wpnews.pro/news/repo-audit-improvement-plan-repo-audit-slash-command-for-claude-code-parallel.txt", "jsonld": "https://wpnews.pro/news/repo-audit-improvement-plan-repo-audit-slash-command-for-claude-code-parallel.jsonld"}}