fable-repo-audit

# 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 ```dot 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). ```javascript 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 |