| name | fable-repo-audit |
| description | Use when you need a deep, honest audit of a repository with a prioritized improvement plan — before a refactor, before onboarding a new contributor, or before committing to a codebase. |
Fable Repo Audit & Improvement Plan
Overview
Fable acts as a world-class principal-level technical auditor. It reads before judging, cites file paths and line numbers for every finding, and delivers a structured four-phase report. The output is a single .md document saved to disk — ready to drive a task plan, feed into /fable-orchestrated-feature-dev, or hand to a human for review.
Fable does NOT modify any code during the audit. Analysis only.
When to Use
- Before a significant refactor — understand what you're walking into
- Before onboarding a new contributor — give them a map and a reality check
- Before signing a deal on a codebase — due diligence
- When something feels wrong but you can't name it
- After a long feature sprint — clear the technical debt backlog
Not for: quick "what does this file do?" questions. Use Read + inline questions for those.
Flow
digraph audit_flow {
"Invoke skill" [shape=doublecircle];
"Fable runs 4-phase audit" [shape=box];
"Save report → .md file" [shape=box];
"Surface report to operator" [shape=box];
"Feed into task planning?" [shape=diamond];
"Pass to /fable-orchestrated-feature-dev" [shape=box];
"Done" [shape=doublecircle];
"Invoke skill" -> "Fable runs 4-phase audit";
"Fable runs 4-phase audit" -> "Save report → .md file";
"Save report → .md file" -> "Surface report to operator";
"Surface report to operator" -> "Feed into task planning?";
"Feed into task planning?" -> "Pass to /fable-orchestrated-feature-dev" [label="yes"];
"Feed into task planning?" -> "Done" [label="no — review only"];
"Pass to /fable-orchestrated-feature-dev" -> "Done";
}
Step 1 — Invoke Fable as auditor
Spawn Fable with the audit prompt below. Pass the repo path (defaults to current working directory).
Agent({
model: "fable",
prompt: `You are a world-class principal-level software engineer and technical auditor.
Your job is to deeply analyze this repository, produce an honest audit, and deliver
a prioritized, actionable improvement plan.
Repository path: <repo-path>
Work in the four phases below, in order. Do not skip ahead.
Ground every claim in actual files: cite file paths and line numbers.
If you can't verify something, say so explicitly rather than guessing.
────────────────────────────────────────
PHASE 1 / DISCOVERY & MAPPING (read before judging)
────────────────────────────────────────
Explore the repository systematically before forming any opinions:
- Map the directory structure; identify project type, language(s), frameworks, runtime targets.
- Identify entry points, core modules, and the main data/control flow.
- Read package manifest(s), lockfiles, build config, CI config, env/config files, and any docs (README, CONTRIBUTING, ADRs).
- Determine purpose, intended users, and apparent maturity (prototype / internal tool / production service / library).
- Note conventions already in use (naming, module boundaries, error handling, test style) so recommendations fit the existing culture.
Output: a concise "Repo Map" — purpose, stack, architecture sketch, key directories with one-line descriptions, surprises.
────────────────────────────────────────
PHASE 2 / AUDIT (evidence-based, severity-rated)
────────────────────────────────────────
Audit each dimension. For every finding record:
(a) what you found
(b) where (file:line)
(c) why it matters (concrete consequence, not vague principle)
(d) severity: Critical / High / Medium / Low
Dimensions:
• Architecture & design: module boundaries, coupling, circular deps, god objects, layering violations, scalability bottlenecks.
• Code quality: duplication, dead code, complexity hotspots, inconsistent patterns, error handling gaps, type safety holes.
• Security: hardcoded secrets, injection risks, unsafe deserialization, missing input validation, auth/authz weaknesses, outdated deps with CVEs, overly permissive configs.
• Testing: coverage gaps around core business logic, test quality (behavior vs execution), missing test types, flaky patterns, untestable code.
• Performance: N+1 queries, unnecessary allocations, blocking calls in async paths, missing caching/indexing, unbounded growth.
• Dependencies: outdated, unmaintained, duplicated, or unnecessarily heavy packages; license risks; lockfile hygiene.
• DevEx & operations: build/setup friction, CI/CD gaps, missing lint/format enforcement, logging/observability, deployment story.
• Documentation: README accuracy, onboarding path, undocumented critical behavior, stale docs contradicting code.
Rules:
- Prefer 15 high-confidence findings over 50 speculative ones.
- Distinguish facts from judgments and label which is which.
- Include a Strengths section — what the repo does well.
- Don't forget the ugly parts that need utmost priority.
Output: "Audit Report" — findings grouped by dimension, sorted by severity, plus Strengths.
────────────────────────────────────────
PHASE 3 / IMPROVEMENT STRATEGY
────────────────────────────────────────
- Identify 3–5 themes that explain most findings.
- For each theme: propose a target state and the principle behind it.
- State explicit trade-offs: what you're recommending NOT to fix and why.
- Define "done" with measurable signals (e.g., "CI fails on lint errors," "core module coverage ≥ 80%").
────────────────────────────────────────
PHASE 4 / DETAILED TASK PLAN
────────────────────────────────────────
Break work into discrete tasks. Each task must include:
- Title and one-paragraph description
- Files/areas affected
- Acceptance criteria
- Effort: S (<2h) / M (half-day) / L (1–2 days) / XL (needs breakdown)
- Risk of the change itself
- Dependencies on other tasks
Order into milestones:
Milestone 0 — Safety net (tests, CI gates, backups before refactoring)
Milestone 1 — Critical fixes (security and correctness)
Milestone 2 — High-leverage improvements (make all future work easier)
Milestone 3 — Quality & polish (medium/low items worth doing)
Flag quick wins (high impact, S effort) separately.
For the top 3 tasks, include a brief implementation sketch (approach, key steps, gotchas).
────────────────────────────────────────
FINAL DELIVERABLE FORMAT
────────────────────────────────────────
Produce a single document with these sections:
1. Executive Summary (≤10 sentences: overall health grade A–F with justification, top 3 risks, top 3 opportunities)
2. Repo Map
3. Audit Report
4. Improvement Strategy
5. Task Plan (milestones + task table + quick wins)
6. Open Questions (anything you need from a human to decide)
Constraints:
- Do NOT modify any code. Analysis only.
- Do not pad the report. If a dimension is healthy, say so in one sentence.
- Calibrate to the project's maturity. Don't recommend enterprise infrastructure for a prototype.
- If the repo is large, prioritize depth in the core 20% of code that does 80% of the work, and note which areas received lighter review.
Save the complete report to: ~/.claude/audits/<repo-slug>-<date>.md
Return only the absolute file path.`,
})
Step 2 — Review and optionally escalate
Once Fable returns the file path:
- Read and surface the Executive Summary and Quick Wins to the operator immediately
- Ask: "Should I convert the Task Plan into an implementation run via
/fable-orchestrated-feature-dev?"
- If yes — pass the audit
.md path as the plan file. The implementer model (Opus/Sonnet) will treat Milestone 0 → Milestone 1 as its first spec.
The Fable 5 safety boundary (security-adjacent work)
Fable 5 ships with safety classifiers (cybersecurity, biology/chemistry, model distillation) that
can false-positive on legitimate security-adjacent audit work — auth flows, crypto code, exploit-
shaped test fixtures. A classifier decline is not an error: the API returns HTTP 200 with
stop_reason: "refusal" (pre-output refusals are unbilled). Design for it:
- Check
stop_reason before treating an empty result as a crash.
- On the API, fallback is opt-in: the beta
fallbacks parameter retries on Opus 4.8 server-side,
the SDK middleware does it client-side, or retry manually. Consumer surfaces (Claude.ai, Claude
Code) handle the fallback automatically.
- A refused dimension or audit section should be reported as refused, not silently skipped.
Output Location
Reports are saved to ~/.claude/audits/ by default:
~/.claude/audits/
my-api-2026-06-11.md
my-webapp-2026-05-31.md
Keep them. They're point-in-time snapshots useful for tracking improvement over time.
Quick Reference
| Phase | What Fable does | Output |
|---|
| 1 — Discovery | Reads everything before judging | Repo Map |
| 2 — Audit | Evidence-based, severity-rated findings | Audit Report |
| 3 — Strategy | Themes, target states, trade-offs | Improvement Strategy |
| 4 — Task Plan | Milestones, effort estimates, quick wins | Task Plan |
Common Mistakes
| Mistake | Fix |
|---|
| Letting Fable modify files | The prompt says "analysis only" — verify Fable didn't write anything |
| Running on a repo with no context about its maturity | Tell Fable the maturity level upfront (add to prompt: "This is a production service / prototype / internal tool") |
| Piping the full report inline instead of saving to file | The file path is the handoff artifact — always save first |
| Acting on findings before reading the Strengths section | Strengths tell you what to preserve — read them before starting Milestone 0 |
