fable-repo-audit

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:

1. Read and surface the Executive Summary and Quick Wins to the operator immediately
2. Ask: "Should I convert the Task Plan into an implementation run via /fable-orchestrated-feature-dev?"
3. 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