Code Overhaul Review

Code Overhaul Review

Audit this codebase for maintenance, modernization, and overhaul. For every issue, state concrete tradeoffs, lead with an opinionated recommendation, and ask for input before assuming direction.

Health check, not feature review. Goal: identify highest-leverage changes for reliability, performance, maintainability, and dev velocity — then execute in disciplined order.

Stack detection: At the start of Step 0, scan the repo for language markers (\*.swift/Xcode projects, go.mod, package.json/tsconfig). For each stack detected, apply the matching addendum from the Language-Specific Addendums section below IN ADDITION to the generic section. For monorepos, apply multiple addendums and note which findings apply to which module/package.

Priority hierarchy

Context low? Step 0 > Impact/effort matrix > Test diagram > Recommendations > Rest. Never skip Step 0 or the matrix.

Engineering preferences

• DRY — flag repetition aggressively.
• Well-tested non-negotiable; too many > too few.
• "Engineered enough" — not fragile, not over-abstracted.
• More edge cases, not fewer; thoughtfulness > speed.
• Explicit over clever.
• Minimal diff: fewest new abstractions and files touched.
• Performance is a feature. Profile before and after.
• Prefer platform/stdlib over third-party when feasible.
• Deprecation warnings are bugs. Fix proactively.
• Build time matters. Justify anything that slows it.

Diagrams

ASCII art for data flow, state machines, dependency graphs, pipelines, decision trees — in plans and inline code comments. Embed where behavior is non-obvious: models, services, views/controllers, tests.

Diagram maintenance is part of the change. Stale diagrams are worse than none. Flag even outside scope.

BEFORE YOU START

Step 0: Scope Assessment

1. Repo health: Compiler/linter warnings, deprecation warnings, TODO/FIXME/HACK density, dead code, unused imports, test pass rate, build time. (Add stack-specific tools per addendum.) 2. Dependency landscape: All third-party deps, current vs. latest. Flag: >1 major behind, unmaintained (12+ months), replaceable by platform APIs. 3. Platform/language version floor: Determines which modern APIs are available, which workarounds can die. 4. Tech debt concentration: Top 3–5 files/modules by size, churn, coupling, bug history. 5. Complexity check: >15 files or >3 new abstractions → challenge scope.

Offer three modes:

1. SURGICAL: One theme, minimal blast radius, one session. 2. SYSTEMATIC: Section-by-section interactive, ≤4 issues per section. 3. FULL AUDIT: All sections, all issues. Phased roadmap.

Once chosen, commit fully. No silent scope reduction.

Review Sections

1. Architecture

Evaluate: module structure and boundaries (draw dependency graph), layering violations, data flow and sources of truth, concurrency/thread safety, routing/navigation consistency, scaling bottlenecks, security boundaries. For each major boundary: one realistic production failure and whether current code handles it. Identify where ASCII diagrams belong. Apply stack addendum.

STOP. AskUserQuestion. Do NOT proceed until user responds.

2. Code quality

Evaluate: file/folder organization, DRY violations, error handling gaps (cite file and line), naming consistency, tech debt hotspots, over-engineering and under-engineering, dead code, stale diagrams, linter/compiler warnings. Apply stack addendum.

STOP. AskUserQuestion. Do NOT proceed until user responds.

3. Tests

Diagram all critical flows, pipelines, state transitions, branching. For each: test exists? meaningful? edge cases covered? fast and reliable? Also: test distribution, execution time (flag slow tests), isolation, missing categories, mock strategy. Apply stack addendum.

STOP. AskUserQuestion. Do NOT proceed until user responds.

4. Performance

Evaluate: startup/launch time, memory footprint and leaks, response latency on hot paths, I/O patterns, network efficiency, build time, binary/bundle size. Apply stack addendum.

STOP. AskUserQuestion. Do NOT proceed until user responds.

5. Dependencies and modernization

Evaluate: outdated deps, replaceable deps, unmaintained deps, language modernization opportunities, toolchain hygiene, CI/CD health. Apply stack addendum.

STOP. AskUserQuestion. Do NOT proceed until user responds.

For each issue

• File/line references.
• 2–3 options including "defer."
• Per option, one line: effort, risk, blast radius, maintenance burden.
• Lead with directive: "Do B. Here's why:"
• Map to engineering preference in one sentence.
• AskUserQuestion: "We recommend [LETTER]: [reason]" then A) ... B) ... C) .... Label: NUMBER + LETTER (e.g., "3B").

Required outputs

Impact/effort matrix

                LOW EFFORT        HIGH EFFORT
           ┌─────────────────┬─────────────────┐
HIGH       │ DO FIRST         │ PLAN CAREFULLY   │
IMPACT     │ (quick wins)     │ (core overhaul)  │
           ├─────────────────┼─────────────────┤
LOW        │ IF TIME          │ SKIP / DEFER     │
IMPACT     │ (polish)         │ (not worth it)   │
           └─────────────────┴─────────────────┘

NOT in scope

Deferred work, one-line rationale each.

What already exists

Underused utilities, helpers, or patterns already in the codebase.

Deferred work → Beads

bd create "<title>" -t <type> -p <priority> -d "<what, why, current state, where to start, prereqs>" -l "tech-debt,overhaul"

Ask before filing. Link with bd dep add.

Diagrams

Before/after dependency graphs, refactored data flow, state machines. Identify files needing inline diagrams.

Failure modes

Per modified codepath: one realistic failure → test covers it? error handling? user-visible or silent? No test + no handling + silent → critical gap.

Migration / rollback

Incremental or all-or-nothing? Rollback plan? Old/new coexistence? Verification?

Execution order

Numbered, respecting: (1) inter-change dependencies, (2) impact/effort priority, (3) tests before refactoring, (4) every step shippable.

Completion summary

╔════════════════════════════════════════════════╗
║           CODE OVERHAUL SUMMARY                ║
╠════════════════════════════════════════════════╣
║ Mode:                 ___                      ║
║ Stacks detected:      ___                      ║
║ Warnings:             ___ compiler, ___ deprec ║
║ Dead code:            ___                      ║
║────────────────────────────────────────────────║
║ Architecture:         ___ issues               ║
║ Code quality:         ___ issues               ║
║ Tests:                ___ gaps                 ║
║ Performance:          ___ issues               ║
║ Dependencies:         ___ outdated, ___ replace║
║────────────────────────────────────────────────║
║ Quick wins:           ___                      ║
║ Core overhaul:        ___                      ║
║ Beads filed:          ___                      ║
║ Critical gaps:        ___                      ║
║ Execution steps:      ___                      ║
╚════════════════════════════════════════════════╝

Add stack-specific rows from addendums (e.g., force-unwrap count, any count, race-clean status).

Retrospective learning

Git log: high-churn files, reverted commits, large "fix" commits, recurring patterns ("fix crash in…", "workaround for…"). Aggressive on historically problematic areas.

Formatting

NUMBER issues, LETTERS for options. Recommended first. One sentence per option. Pause after each section.

Unresolved decisions

List at end: "Unresolved decisions that may bite you later." Never silently default.

Anti-patterns

• Big bang rewrites → incremental.
• Refactoring without tests → characterization tests FIRST.
• Gold plating → health, not perfection.
• Chasing new hotness → solve concrete problems only.
• Breaking the build → every commit compiles and passes tests.

---

Language-Specific Addendums

Apply these when the corresponding stack is detected. For monorepos, apply all matching addendums and tag each finding with its module.

---

Addendum: iOS / Swift

Triggers: _.swift files, _.xcodeproj, \*.xcworkspace, Package.swift with Apple platform targets.

Step 0 additions

• Run: Xcode warnings count, SwiftLint violations, deployment target (min iOS version).
• Deployment target determines: SwiftUI API surface, structured concurrency availability, which UIKit workarounds can die.
• Dep audit specifics: SPM/CocoaPods/Carthage. Replaceable: Kingfisher→AsyncImage, Alamofire→URLSession async/await, SnapKit→modern AutoLayout, RxSwift→Combine/async-await, KeychainAccess→native keychain, SwiftyJSON→Codable, IQKeyboardManager→native keyboard avoidance.

Architecture additions

• State management consistency: @Observable vs ObservableObject vs @State — pick one per concern, not mix-and-match.
• Navigation: NavigationStack vs coordinator pattern vs mixed — consistent?
• Concurrency model: structured concurrency adoption boundary vs legacy GCD/completion handlers. Where is the migration line?
• Core Data / SwiftData stack health. Extension targets sharing code correctly?

Code quality additions

• Force-unwraps and implicitly unwrapped optionals — cite every one, these are crash sources.
• try? swallowing errors silently. Empty catch blocks.
• Retain cycle risks: missing [weak self] in closures, non-weak delegate properties.
• Unused @objc exposure, stale Storyboard/XIB connections, dead IBOutlets/IBActions.
• Massive ViewControllers/Views (>300 lines).
• Protocol-oriented over-engineering: protocol with one conformer, unnecessary associated types.

Test additions

• XCTest vs Swift Testing adoption. UI test reliability (flag >10s per UI test).
• Test host app dependency — can unit tests run without app launch?
• Core Data tests using in-memory stores? Network tests using URLProtocol mocks?
• Total suite time matters with large test counts — flag >60s.
• Missing: snapshot tests for complex layouts, accessibility audit tests.

Performance additions

• Launch: Pre-main (dylib loading, +load, static initializers) and post-main. Synchronous main-thread work in didFinishLaunching?
• Main thread: File I/O, JSON parsing, image decoding, Core Data fetches on main.
• Scrolling: Cell reuse, async image loading, Auto Layout ambiguity, offscreen rendering (cornerRadius + clipsToBounds).
• Media: Image downsample before display? PhotoKit fetch efficiency? Unnecessary format conversions?
• Build: Slowest files via -Xfrontend -debug-time-function-bodies. Complex type inference. SPM resolution time.
• Binary: Unused asset catalog entries, embedded resources that could be on-demand.

Modernization additions

• Structured concurrency: async/await, actors, task groups.
• @Observable macro (iOS 17+), #Preview macros, @Entry for EnvironmentValues.
• Typed throws (Swift 6), strict concurrency checking readiness.
• Xcode hygiene: unused build phases, stale schemes, code signing drift, build settings at wrong level.

Summary additions

Add rows: Min iOS target, Swift version, force-unwrap count, SwiftLint violations.

Extra anti-pattern

• UIKit-to-SwiftUI migration without a boundary strategy → define the bridge pattern once, use everywhere.

---

Addendum: Go

Triggers: go.mod, \*.go files.

Step 0 additions

• Run: go vet, staticcheck, golangci-lint, govulncheck ./..., go mod tidy drift check.
• Go version in go.mod determines: range-over-func (1.23+), log/slog (1.21+), errors.Join (1.20+), generics depth, loop variable fix (1.22+).
• Dep audit specifics: go list -m -u all. Replaceable: gorilla/mux→stdlib 1.22+ routing, logrus→log/slog, pkg/errors→fmt.Errorf %w, testify→stdlib testing, go-playground/validator→custom, gorm→sqlc/sqlx, cobra→stdlib flag for simple CLIs.

Architecture additions

• Package boundaries: internal/ usage correct? Circular dep risks?
• Interface pollution: too many interfaces defined by implementor rather than consumer. Accept interfaces, return structs.
• Dependency injection: wire, manual, or scattered init()?
• Graceful shutdown chain: signal → context cancellation → resource cleanup.
• Error propagation: sentinel vs typed vs wrapping — consistent?
• Context: values vs cancellation — abuse?

Code quality additions

• Unchecked errors: _ = foo() — cite every one unless justified with comment.
• Naked returns in complex functions.
• Package-level globals and init() abuse.
• Naming: Go conventions (MixedCaps, 1-2 char receivers, lowercase single-word packages). Stuttering (user.UserService).
• Over-engineering: interfaces with one implementation, unnecessary generics, Options pattern for 2 config values.
• Under-engineering: 2000+ line files, >5 params, any/interface{} where generics clarify.

Test additions

• Table-driven tests consistent? t.Helper() used? Subtests with t.Run()?
• Integration tests tagged //go:build integration?
• Race detector: go test -race passing? This is a gate, not optional.
• Benchmarks for hot paths (BenchmarkX). Fuzz tests for parsers (FuzzX).
• Golden files for complex output. testdata/ organized?
• Mocking: interfaces at boundaries only, not mocking everything. httptest for handlers.

Performance additions

• CPU: Unnecessary allocations in tight paths, reflection in hot code, regexp compilation inside loops (compile once as package var), string concat in loops (strings.Builder).
• Memory: Goroutine leaks (unbounded spawn without context cancel), sync.Pool opportunities, slice pre-alloc (make([]T, 0, cap)), string↔[]byte in hot paths.
• Concurrency: Mutex contention (RWMutex? atomic?), channel buffer sizing, goroutine fan-out without limits (errgroup), context propagation gaps.
• I/O: Connection pool sizing, prepared statement reuse, N+1 queries, HTTP client reuse (not per-request), response body not closed, bufio for files.
• Build: CGO (slows build, complicates cross-compile), unnecessary go generate.
• Binary: -ldflags "-s -w", -trimpath, unused dep bloat.

Modernization additions

• Generics replacing interface{}/codegen where it clarifies (only with >2 concrete types).
• range-over-func (1.23+), log/slog, errors.Join, loop variable fix (1.22+) — remove workarounds.
• iter package (1.23+), any/comparable constraints.
• Toolchain: Makefile/Taskfile hygiene, golangci-lint config freshness, CI (test, vet, lint, race, vulncheck).

Summary additions

Add rows: Go version (mod), go vet issues, staticcheck issues, govulncheck findings, unchecked errors, race clean Y/N.

Extra anti-patterns

• Over-interfacing → one-method interfaces are Go's sweet spot, not the starting point.
• Premature generics → only when >2 concrete types and pattern is proven.

---

Addendum: Web / JavaScript / CSS

Triggers: package.json, tsconfig.json, _.js, _.ts, _.jsx, _.tsx, _.css, _.scss, \*.html files.

Step 0 additions

• Run: tsc --noEmit errors, ESLint/Prettier violations, npm audit, bundle size (total + per-route).
• TypeScript strict mode on? If not, migration path is high-priority.
• Browser floor (browserslist) determines: CSS nesting, :has(), container queries, structuredClone, AbortSignal.any, Promise.withResolvers.
• Dep audit: npm outdated. Replaceable: moment→Temporal/date-fns, lodash→native (Array.at, Object.groupBy, structuredClone), axios→fetch, classnames→clsx/template literals, uuid→crypto.randomUUID, node-fetch→native fetch (Node 18+).

Architecture additions

• Component hierarchy (draw tree). State management: local vs global, prop drilling vs context vs store — consistent?
• Data fetching: per-component vs route-level vs centralized? Caching/dedup? Loading/error states?
• API layer: fetch calls scattered or centralized?
• SSR/SSG/CSR boundaries if applicable. Error boundary placement.
• Build config complexity. Environment handling.

Code quality additions

JS/TS:

• `any` types — cite every one, these defeat TypeScript.
• as assertions bypassing safety. Loose equality (==).
• Uncaught promise rejections. Missing error boundaries.
• Barrel file bloat killing tree-shaking. Unused exports (ts-prune).
• Component files >300 lines.

CSS:

• Specificity wars, !important proliferation.
• Magic numbers without custom properties. Duplicated values needing design tokens.
• Unused CSS. Inconsistent naming (BEM vs utility vs random).
• z-index: documented scale or chaos? Media queries: scattered or centralized?
• CSS-in-JS vs stylesheets vs utility — consistent approach?

HTML/Accessibility:

• Semantic HTML (div soup?). ARIA: missing or wrong. Keyboard nav, focus management, color contrast, alt text, form labels, heading hierarchy.

Test additions

• Unit (Jest/Vitest) for logic. Component (Testing Library) for behavior — flag getByTestId overuse, prefer getByRole/getByText.
• E2E (Playwright/Cypress) for critical paths. Visual regression for complex layouts.
• MSW for network mocking — consistent? Snapshot tests: useful or noise?
• Accessibility tests (axe-core). Suite speed: flag >30s total, >5s individual.

Performance additions

• Core Web Vitals: LCP (critical rendering path), CLS (images without dimensions, font flash, dynamic injection), INP (long tasks, heavy handlers).
• Bundle: Per-route splits, tree-shaking effective?, dynamic imports for below-fold, duplicate deps, source-map-explorer analysis.
• Loading: Critical CSS inlined? Render-blocking resources? Font strategy (font-display, preload)? Images (WebP/AVIF, srcset, lazy load, explicit dimensions)?
• Runtime: Unnecessary re-renders (missing memo where measured), DOM thrashing, event listener cleanup, Web Worker opportunities, requestAnimationFrame for visual updates.
• Caching: Service worker strategy, HTTP headers, CDN, stale-while-revalidate, asset fingerprinting.
• Network: API waterfall (sequential→parallel), overfetching, missing pagination.

Modernization additions

• CSS: native nesting (drop preprocessor nesting), container queries, :has(), View Transitions, Popover API, <dialog> (drop modal libs), color-mix(), @property.
• TS: strict mode path, satisfies, template literal types, discriminated unions, using (5.2+).
• Platform: structuredClone, Object.groupBy, Set methods, import attributes.
• Toolchain: bundler currency (Webpack→Vite?), Node version, package manager consistency, monorepo tooling, preview deployments.

Summary additions

Add rows: Framework, TS strict Y/N, any count, ESLint violations, bundle size (gzip), npm audit vulns, LCP.

Extra anti-patterns

• Premature abstraction → don't build a component system for 3 buttons.
• CSS reset whack-a-mole → fix the specificity model, not symptoms.
• any as escape hatch → every any is deferred debt with compound interest.
• Framework churn → migrate when solving a concrete problem, not for novelty.

Changelog

Semver: MAJOR for protocol-breaking changes, MINOR for additive features, PATCH for clarifications and fixes.

The current version is recorded in the YAML frontmatter of SKILL.md.

2.1.0 — 2026-04-20

Closes ambiguities and fills capability gaps surfaced by independent grading against the rubric. Rubric-level behavior is unchanged; enforcement and schemas are tightened.

Added

• Security integration block under Step 2 — trust-boundary pass in Section 1, secrets-in-code grep in Section 2, auth-test verification in Section 3, vulnerability scan in Section 5. Security never gets its own section.
• Dirty-working-tree advisory in preflight using git status --porcelain | wc -l; audit proceeds but metrics are flagged as committed-state-only.
• Retrospective-learning tiers in Step 0.6 — tier-1 ⚑ hotspot auto-promotes to DO FIRST; tier-2 promotes one matrix cell.
• Counting rule for required outputs — Approved = A/B only; Defer → NOT in scope; SURGICAL-skipped sections show —.
• De-duplication rule — a root cause crossing sections is filed in the most-consequential one with inline See also <id> cross-references.
• Three-part finding ID — <section>.<finding><letter> (e.g., 3.2B); pre-approval references use <section>.<finding>.
• Mandatory-scan statement on addendum bullets — every bullet in a matching addendum sub-section is a scan item, not a suggestion.

Changed

• SURGICAL finding cap set to 3 per chosen section (previously uncapped inside that section).
• Checkpoint timing unified: .code-overhaul/resume.md is written after the user resolves the section-close AskUserQuestion (Approve or Pause), not before; Revise does not rewrite the checkpoint.
• Per-finding AskUserQuestion removed. The Finding Template now produces a Recommendation letter; Approval/override is batched at the section-close question. This eliminates up to 20 prompts per full audit.
• Defer option now carries explicit zero labels (effort: 0, risk: 0, blast radius: 0, maintenance: 0, reason: <one line>) so the label grammar is uniform across all three options.
• Module-tag slug priority rewritten as an ordered list: directory → package name → AskUserQuestion confirmation.
• Pause-exception wording changed from "before any finding is recorded" to "with zero approved findings" (covers the all-Defer case).
• Resume schema expanded: written_at (ISO-8601), findings[] with id/tag/title/chosen. The undefined snapshot: field was removed.

Protocol-breaking

• Resume files written by 2.0.x are readable but missing written_at and findings[]; the skill treats them as stale and prompts fresh-vs-resume.

2.0.0 — 2026-04-20

Full rewrite. Removes ambiguous instructions and aligns the skill with the rubric under eval/. 1.x is preserved only in git history.

Added

• Preflight step that probes for bd, git, and a prior resume file, with explicit fallbacks per missing tool.
• Step 0 table — every repo-health metric now has a runnable measurement command and a threshold. Stack addendums extend the table with stack-specific metrics.
• Step 0.5 scope-risk heuristic (SMALL / MEDIUM / LARGE buckets) that feeds a recommendation into Step 1.
• Step 0.6 retrospective learning — historically buggy files, reverts, large "fix" commits; a file appearing in all three lists is a tier-1 target.
• Degenerate-repo handling — no tests, no git history, single-file, no deps each have explicit per-section instructions.
• Scope-drift rule — expansion requests require a mode re-prompt, never silent widening.
• Explicit `Finding Template` — NUMBER+LETTER scheme with required fields (evidence, options with S/M/L effort/risk/blast/maintenance, directive letter, mandatory AskUserQuestion).
• Fixed section-close question — one canonical question with three option branches (Approve / Revise / Pause).
• Output templates for Impact/Effort matrix, NOT in scope, What already exists, Deferred work → Beads (with bd-absent fallback), Diagrams, Failure modes, Migration/rollback, Execution order, Completion summary, Unresolved decisions.
• Characterization-tests-first hard gate in Execution order: any recommendation touching untested code produces a characterization-test step ahead of the change.
• Failure-mode review as a required non-skippable output; no-test + no-handling + silent → critical gap with priority uplift.
• Resume behavior — .code-overhaul/resume.md checkpoint after each section; resume argument re-enters at next_section.
• Batched beads confirmation — single AskUserQuestion covering all proposed bd create commands with File all / Skip selected / File none.
• Monorepo tagging format — every finding begins with [<module>] using short lowercase slugs.
• Conventions glossary — directive vs soft verbs, evidence requirement, module tags, context-tight priority order.
• eval/ directory with RUBRIC.md, GRADER.md, SCENARIOS.md used to validate changes to the skill.

Changed

• description rewritten to front-load the trigger action and include natural-language invocation phrases.
• argument-hint added ([surgical|systematic|full|resume] [path]).
• allowed-tools slimmed to Read/Grep/Glob/Bash (AskUserQuestion is built-in).
• All soft verbs (consider, evaluate, should) removed from mandatory steps.
• Stack addendums reorganized to mirror the generic structure one-to-one: Step 0 additions → Architecture → Code quality → Tests → Performance → Modernization → Summary additions → Anti-pattern(s).
• Dependency classification (outdated vs replaceable vs unmaintained) made explicit in Section 5.

Removed

• Vague "Offer three modes" phrasing — replaced by an explicit AskUserQuestion invocation with fixed options.
• Unbounded "STOP. AskUserQuestion." placeholder — replaced by the fixed section-close question with branch logic.
• Orphaned "Retrospective learning" section — reassigned to Step 0.6 with defined output.

Protocol-breaking

• Sessions/resume files from any 1.x snapshot are ignored. Start fresh after upgrading.

1.0.0 — 2026-02

Initial release. Five review sections, three modes, stack addendums for iOS/Swift, Go, and Web. No preflight, no resume, no fixed output templates beyond the Impact/Effort matrix and Completion Summary. Kept in git history only.

Grader prompt

You are an independent grader. You have not seen the development history of this skill. Your job: score skills/code-overhaul/SKILL.md against skills/code-overhaul/eval/RUBRIC.md.

Procedure

1. Read the full rubric first. 2. Read the full SKILL.md. 3. For each criterion C1..C13:

• Quote the specific lines in SKILL.md that justify a pass (or the absence if failing).
• Score 0 or 1. No half credit.
• If a criterion requires multiple things (e.g., "all of: A, B, C"), all must be present to earn the point.

4. Sum the scores. 5. Report in this exact format:

# Grade: <N>/13

## C1. Frontmatter conformance — <PASS|FAIL>
<one-sentence justification citing SKILL.md:line or a quoted snippet>

## C2. Argument parsing and mode routing — <PASS|FAIL>
...

...through C13...

## Gaps to fix
- Numbered list of specific missing elements, one per failing criterion. For each gap, quote the exact text that would earn the point if added.

Rules

• Be strict. A gesture toward a criterion is not enough — the text must actually enforce it.
• If the skill uses should, could, consider, or evaluate where the rubric requires a hard directive, that criterion fails. Soft verbs inside the Conventions glossary or illustrative quotes are fine.
• Cite line numbers when quoting (SKILL.md:NNN).
• Do not grade generously because earlier versions of the skill passed. Grade the current text as-is.
• Do not rewrite the skill. Only grade.
• If the SCENARIOS.md walk-throughs under eval/ would fail for the current skill text, that is a strong signal that at least one criterion is failing — find it.

Running a grader against a real audit

This grader scores the skill's text. To score an actual audit run against a real repository, use SCENARIOS.md as the test matrix: for each scenario, execute the skill, then score whether the resulting audit:

1. Passed every rubric criterion that the scenario exercises. 2. Produced all required outputs with the schemas specified. 3. Respected mode scoping (SURGICAL touched only the chosen section; SYSTEMATIC capped at 4 findings per section; FULL exhausted addendum checklists). 4. Emitted a valid .code-overhaul/resume.md at each section break. 5. Produced runnable bd create commands (or the correct fallback). 6. Did not introduce soft-verb instructions into user-facing output.

Report scenario results as S<N>: PASS|FAIL — <one-line reason>.

code-overhaul SKILL.md rubric

13 criteria, 1 point each. Target: 13/13.

Each criterion lists what the SKILL.md must contain to earn the point. A grader reads skills/code-overhaul/SKILL.md and scores 0 or 1 per criterion with a one-sentence justification. Half credit is not allowed — either the SKILL.md has it or it doesn't. This keeps iterations honest.

---

C1. Frontmatter conformance

The YAML frontmatter uses the official Claude Code skill schema for discovery and invocation.

Pass if all of:

• name: uses lowercase hyphen-case and matches the skill directory name.
• description: opens with a directive verb (the action the skill performs) and contains natural-language trigger phrases a user would say (e.g., "review this codebase", "audit this repo").
• argument-hint: lists the valid modes plus resume, matching the invocation section.
• allowed-tools: names every shell / file tool the skill actually calls (Read, Grep, Glob, Bash). AskUserQuestion may be omitted (built-in).

C2. Argument parsing and mode routing

The skill accepts explicit modes and routes interactively when none is passed.

Pass if all of:

• surgical, systematic, full, and resume are each named explicitly.
• Path argument behavior is documented (defaults to current directory).
• If a mode is passed explicitly, the interactive mode prompt in Step 1 is skipped.
• Resume reads a persisted file and skips to the recorded section.

C3. Preflight environment detection with fallbacks

Before any audit work, the skill probes the environment and specifies concrete fallback behavior for every missing tool.

Pass if all of:

• A preflight block enumerates tool checks (bd, git), repo-root resolution, and a working-tree cleanliness probe.
• The bd: absent fallback specifies what the Deferred-work output becomes instead (plain checklist) and requires an explanatory line.
• The git: absent fallback specifies skipping retrospective learning with a stated note.
• Dirty-tree handling is stated explicitly (print an advisory, do not abort).
• Preflight results are surfaced as a visible table before Step 0.

C4. Executable Step 0 with measurements and thresholds

Step 0 is a concrete measurement pass, not a prose checklist.

Pass if all of:

• Every generic metric has a runnable shell command (or explicit delegation to "stack-specific").
• Every metric has a threshold or an informational label (the grader can answer "what counts as a finding?").
• The output shape is a table printed before Step 1.
• A repo-size bucket (SMALL / MEDIUM / LARGE) is computed from the measurements.
• Retrospective-learning queries (git history) are specified with exact git commands.

C5. Stack detection, addendum application, and monorepo tagging

The skill auto-activates stack-specific addendums and keeps monorepo findings unambiguous.

Pass if all of:

• At least three addendums (iOS/Swift, Go, Web/JS/CSS) are present.
• Each addendum lists Triggers (file markers) that a shell glob can evaluate.
• Each addendum mirrors the generic structure: Step 0 additions → Architecture → Code quality → Tests → Performance → Modernization → Summary additions → Anti-pattern.
• Monorepo tag format is specified exactly (e.g., [<module>] with lowercase slug) and required on every finding when >1 stack matches.

C6. Scope commitment and drift handling

Mode selection is blocking; scope changes are not silent.

Pass if all of:

• Step 1 calls AskUserQuestion with a fixed question, three labelled options (A/B/C), and a recommendation seeded from the repo-size bucket.
• The skill explicitly blocks further work until the user responds.
• A scope-drift rule is documented: if the user requests expansion mid-audit, the skill re-issues the mode question before complying.
• Mode caps are numeric and explicit: SURGICAL ≤ 3 findings for the chosen section, SYSTEMATIC ≤ 4 per section, FULL no cap.
• SURGICAL mode additionally asks which section to run.

C7. Finding schema is mandatory and complete

Findings use a single shape; free-form findings are forbidden.

Pass if all of:

• A Finding Template block appears with: three-part ID (section.finding), module tag, problem statement, evidence (path:line or command), 2–3 options each with effort/risk/blast-radius/maintenance labelled S/M/L, a Defer option with zero labels (effort: 0, risk: 0, blast radius: 0, maintenance: 0), and a Recommendation letter with an engineering-preference rationale.
• The template states that recommendations are batched — approval/revision is handled by the section-close AskUserQuestion rather than one prompt per finding.
• The template is referenced from every review section (1–5) or the template is defined before the sections and explicitly stated as mandatory for all sections.
• "No free-form findings" or equivalent exclusion is stated.

C8. Section pauses are enforced with fixed questions and branches

Every section ends with a blocking, schema'd AskUserQuestion.

Pass if all of:

• A single fixed section-close question is defined verbatim and reused for every section.
• Three options (Approve / Revise / Pause) are enumerated with their consequences.
• Branch logic is specified: Approve → next section; Revise → re-emit affected findings and re-ask; Pause → jump to Completion Summary with Status: paused.

C9. Required outputs have concrete templates

Every required output has a fixed shape so runs are comparable.

Pass if all of:

• Impact/effort matrix: ASCII quadrant template with ID slots.
• NOT in scope: markdown table with | id | finding | reason |.
• What already exists: bulleted list with path:line citations required.
• Deferred work → Beads: bd create command template AND fallback checklist spec.
• Failure modes: table with codepath | failure | test? | handling? | visible? plus critical-gap escalation rule.
• Migration/rollback: table scoped to L blast-radius items with incremental | rollback | coexistence | verification.
• Execution order: numbered steps with [blocked-by: …] [ships-alone: …] annotations.
• Completion summary: ASCII box with every listed row.

C10. Beads integration with verified syntax, fallback, and batched confirmation

The skill's beads usage is correct and degrades gracefully.

Pass if all of:

• The bd create command uses real flags in long or short form (--title/positional, --type, --priority, --description, --labels).
• bd dep add is shown for linking dependent issues.
• Batch confirmation is required (single AskUserQuestion covering all proposed issues with File-all / Skip-selected / File-none), not one prompt per issue.
• bd-absent fallback is specified with the exact advisory line to print.

C11. Characterization-tests-first and failure-mode gates

Two non-negotiable gates bind the skill's output:

Pass if all of:

• Execution order explicitly states: if a recommendation touches untested code, the first step is the characterization-test plan (not the change).
• A failure-mode table is required output and cannot be skipped.
• The rule no-test + no-handling + silent → critical gap is stated, with the priority-uplift consequence.

C12. Degenerate-repo and edge-case handling

The skill behaves sensibly on unusual repos instead of drifting.

Pass if all of:

• no tests detected → Section 3 becomes a test-creation plan; refactor-of-untested-code is blocked.
• no git history → Step 0.6 is skipped with a printed note.
• single-file or near-empty repo → SURGICAL only; SYSTEMATIC/FULL refused with a stated reason.
• no dependency manifest → Section 5 output is the single stated line.

C13. Resume behavior with checkpoint persistence

The audit is resumable and version-aware.

Pass if all of:

• After each section-close AskUserQuestion resolves (Approve or Pause, not Revise), the skill writes .code-overhaul/resume.md.
• The resume file schema lists at minimum version, mode, target, written_at, completed_sections, next_section, and a findings list capturing id, tag, title, chosen.
• resume invocation reads the file, reprints completed findings in compact form, and resumes at next_section.
• Resume files whose written_at is older than 7 days trigger a fresh-vs-resume AskUserQuestion prompt.

---

Scoring

Total = sum of criteria. Pass = 13/13.

Partial matches score 0. No partial credit. A skill that says "should" where it must say "must", or that gestures toward a requirement without enforcing it, fails the relevant criterion.

Eval scenarios

Sample inputs to sanity-check the skill end-to-end. A grader is not required to run these — they exist so a human or a secondary agent can walk through and verify the skill gives sane answers. Every scenario below lists the expected behavior against the current rubric. If the skill diverges, that's a rubric-failing bug.

---

S1. SURGICAL — single-section audit on a medium Go repo

Input: /code-overhaul surgical ~/Work/api-service

Repo profile: ~250 Go files, 18k LOC, has go.mod, go vet clean, no staticcheck present, go test -race passes.

Expected:

• Preflight detects bd: ok, git: ok, no resume file.
• Step 0 runs with Go addendum: lists go vet: 0, staticcheck: n/a (not installed), govulncheck if installed, go version from go.mod, churn/fix-pattern lists.
• Scope-risk bucket: MEDIUM.
• Step 1 is skipped (mode passed on invocation). The skill asks instead: "Which section?" with five options.
• User picks 2 Code quality. Only Section 2 runs.
• Findings use the NUMBER+LETTER template; staticcheck absence becomes a Section 2 finding (tooling gap), not a silent skip.
• .code-overhaul/resume.md is written at section close with completed_sections: [2].
• Completion Summary has Mode: surgical, Status: complete, Dependencies: — (not scanned).

---

S2. SYSTEMATIC — iOS/Swift app, full walk-through

Input: /code-overhaul systematic ~/Work/PhotoApp

Repo profile: SwiftUI + some UIKit, Package.swift with iOS 16 deployment target, 800 Swift files, 42 force-unwraps, SwiftLint present.

Expected:

• Preflight: all green.
• Step 0 runs with iOS/Swift addendum: Xcode warnings, SwiftLint violations, force-unwrap count, try? count all appear in the table.
• Bucket: MEDIUM.
• Step 1 recommends B) SYSTEMATIC. User confirms.
• All five sections run; each capped at 4 findings.
• Section 2 lists force-unwraps as a finding with a table of path:line occurrences, options include A) Replace top-20 offenders with guard/if-let, B) Add linter rule + fix-forward, C) Defer.
• After each section, the fixed section-close question fires; user answers A each time.
• .code-overhaul/resume.md is overwritten after every section.
• Final outputs include Failure-modes table with at least one no/no/silent row marked ⚠ and priority-uplifted in Execution order.
• Completion Summary contains iOS-specific rows (Min iOS target, Swift version, Force-unwrap count, SwiftLint violations).

---

S3. FULL AUDIT — Web monorepo with two stacks (Node + Go)

Input: /code-overhaul full ~/Work/platform

Repo profile: root has package.json (Next.js front-end in web/), plus go.mod in services/api/. Both Web/JS/CSS and Go addendums apply.

Expected:

• Preflight: all green.
• Step 0 table has both Go rows and Web rows, side by side.
• Bucket: LARGE → recommendation C) FULL, but the skill flags a time warning.
• All five sections run with no finding cap. Every finding is prefixed [web] or [api] (or [services/api] if the skill uses directory names). Inconsistent tags across findings is a rubric-failing bug.
• Dependency graph in Section 1 shows web↔api boundary and any HTTP/RPC contract.
• Failure-mode table rows are scoped per codepath with module tags.
• Deferred work → Beads emits runnable bd create commands, with --labels "tech-debt,overhaul", and bd dep add between inter-stack items.
• Single batched AskUserQuestion fires before any bd create runs.

---

S4. No tests + no git history (degenerate repo)

Input: /code-overhaul ~/tmp/prototype

Repo profile: fresh directory, three .py files, no tests, no .git, no manifest.

Expected:

• Preflight: git: absent, bd: absent.
• Step 0 runs partial: file count, LOC, platform version; skips churn, retrospective learning, dependency drift with n/a (no git history) and n/a (no manifest).
• Degenerate-repo advisory printed: Retrospective learning: n/a (no git history). and No third-party dependencies detected.
• Step 1: the skill offers SURGICAL only (single-file / near-empty refusal rule).
• Section 3 becomes "Test creation plan". Any subsequent refactor recommendation must be blocked behind characterization-tests-first.
• Deferred-work output is a markdown checklist (bd absent) with the advisory line at the top.

---

S5. Resume after a pause

Input (first run): /code-overhaul systematic ~/Work/tool → user hits Pause after Section 2.

Input (second run, later): /code-overhaul resume ~/Work/tool

Expected first run:

• .code-overhaul/resume.md contains mode: systematic, completed_sections: [1, 2], next_section: 3, snapshot: <path>.
• Completion Summary is emitted with Status: paused at section 2.

Expected second run:

• Preflight: resume: available.
• Skill reprints a compact form of Section 1 + Section 2 findings, restates chosen mode, resumes at Section 3.
• The fixed section-close question fires at the end of Section 3 and the resume file is overwritten with completed_sections: [1, 2, 3].
• If the resume file is >7 days old, the skill asks fresh-vs-resume before reprinting.

---

S6. Scope drift mid-audit

Input: Mid-SURGICAL audit on Section 4 (Performance). User types "also check the test suite."

Expected:

• Skill does not silently add Section 3 findings.
• Skill re-issues the Step 1 mode question, framed: "That expands scope. Switch mode to [systematic] or keep scope and queue the test-suite review as a follow-up?"
• User response drives behavior. If keep-scope, test-suite request becomes a queued bead in the Deferred-work output.

---

S7. bd present but the command fails

Input: /code-overhaul systematic ~/Work/svc where bd create returns non-zero (e.g., Dolt server misconfigured).

Expected:

• Skill surfaces the error inline and offers: A) Retry, B) Switch to checklist fallback, C) Skip filing. The batched confirmation is still single-shot.
• If the user picks B, the skill emits the markdown checklist with the bd-absent advisory line and completes.
• The skill does not silently re-prompt per-issue.

---

Using these scenarios

A secondary agent walking these scenarios should record a one-line result per scenario:

S1: PASS — surgical scoped to Section 2, resume written, tooling gap captured as finding
S2: PASS — all five sections, iOS rows in summary, force-unwrap finding surfaced
...

Any FAIL result must cite the rubric criterion the scenario violates.