Code Cleanup Audit

Code Cleanup Audit

Overview

Use this skill to produce an evidence-backed cleanup audit only. The output is a backlog of suspected or confirmed problems for human review, not an implementation plan that silently edits code.

Non-Negotiable Guardrails

• Do not modify files.
• Do not call apply_patch, formatters with write mode, generators, codemods, install commands, migration commands, or any command whose purpose is to change the workspace.
• Do not create branches, commits, pull requests, or issue tickets unless the user explicitly asks after reviewing the audit.
• If the user asks for fixes before seeing the audit, first produce findings and ask which items to implement.
• If a command unexpectedly changes files, stop, report the changed paths, and ask how to proceed.
• Preserve unrelated dirty worktree changes; treat them as user-owned.

Audit Workflow

1. Establish repository context:

   • Read AGENTS.md first.
   • Read architecture and convention docs that directly govern the touched codebase, especially dependency boundaries, ADRs, and package conventions.
   • Run git status --short and note existing dirty files.
   • Inventory apps/packages with read-only commands such as find, rg --files, pnpm -r list --depth -1, and package manifest reads.

2. Build a map before judging:

   • Identify package boundaries, public exports, app entry points, runtime adapters, shared schemas, tests, and docs.
   • Trace imports through package names, not only filenames.
   • Compare implementation structure against documented allowed dependencies.
   • Prefer rg over slower search tools.

3. Inspect for cleanup categories:

   • Architecture violations: forbidden imports, cross-package relative imports, app-layer logic in shared packages, runtime-specific code in core/shared, browser-unsafe code in web/client/shared.
   • Stale compatibility: deprecated fields, fallback branches, migration shims, legacy aliases, duplicate old/new APIs, TODOs that preserve obsolete behavior, no-op adapters, unused feature flags.
   • AI-generated code smells: over-broad abstractions, fake extensibility, duplicated helpers, inconsistent naming, hand-rolled utilities where a project utility exists, speculative layers, uncalled code, verbose comments explaining obvious code, guessed data shapes.
   • Type and schema weakness: any, unsafe casts, unchecked unknown, interfaces where runtime validation is required, schema/type drift, missing boundary parsing.
   • Error and runtime behavior smells: swallowed errors, broad catch, impossible states represented as optional fields, missing cancellation/timeout handling, fragile env assumptions.
   • Test and validation gaps: core behavior without tests, snapshots masking behavior, tests that only assert mocks, missing negative cases for boundary rules.
   • Documentation drift: docs or AGENTS rules contradicted by code, public API exports not reflected in docs, stale startup/quality commands.

4. Validate suspected issues:

   • Read surrounding code and tests before reporting.
   • Run read-only validation where useful: pnpm lint, pnpm typecheck, pnpm test, focused Vitest commands, pnpm build only when build behavior is relevant.
   • Use existing ESLint boundary rules as evidence when available.
   • Distinguish confirmed problems from cleanup candidates that need product or architectural judgment.

5. Report without fixing:

   • Lead with findings ordered by severity.
   • Include file path and line or precise code location for each finding.
   • State the violated rule or smell, why it matters, evidence, confidence, and suggested cleanup direction.
   • Mark every item as one of: confirmed, likely, or needs human decision.
   • Include "Do not modify until confirmed" language when handing off.

Severity Standard

• Critical: Can break runtime behavior, violate security/privacy boundaries, corrupt data, or cause CI/build failure.
• High: Violates documented architecture, creates wrong package dependency direction, or preserves misleading/dead public API that future agents will copy.
• Medium: Increases maintenance cost through duplication, stale compatibility, weak validation, or untested shared behavior.
• Low: Local readability or consistency issue with limited blast radius.

Do not report pure preference, cosmetic style, or speculative rewrites unless tied to a concrete maintenance, correctness, boundary, or future-agent-copying risk.

Recommended Commands

Use commands like these as applicable. Keep them read-only.

bashCopy code
git status --short
find apps packages docs -maxdepth 3 -type f | sort
rg --line-number "TODO|FIXME|deprecated|legacy|compat|shim|fallback|no-op|noop|any\\b|as unknown|as any" apps packages docs
rg --line-number "from ['\"]\\.\\./\\.\\./|from ['\"]\\.\\./\\.\\./\\.\\./|@pragma/(client|server|core|runtime)" apps packages
pnpm -r list --depth -1
pnpm lint
pnpm typecheck
pnpm test

Before running expensive repository-wide commands, prefer focused reads and explain why the command is useful.

Output Format

Return:

1. Findings

   • Severity
   • Status: confirmed, likely, or needs human decision
   • Location
   • Problem
   • Evidence
   • Cleanup direction, without editing code

2. Cleanup backlog

   • Group related findings into reviewable batches.
   • Call out which batches are safe mechanical cleanup versus architecture decisions.

3. Non-findings and constraints

   • Mention important suspected issues that were checked and rejected.
   • Mention commands run and commands intentionally skipped.

4. Human confirmation needed

   • List the exact decisions needed before any code changes.