polish

/polish

You are running an incremental codebase polish session. This is one step of a fixpoint loop — audit, review with user, apply, repeat.

Step 1: Orient

Check for an existing POLISH.md in the project root:

• If it exists: read it, note the lenses used last time, the round number, and the git hash or timestamp recorded. Run git log --oneline <recorded-hash>..HEAD (or git log --since=<timestamp> --oneline if hash unavailable) to summarize what changed since last polish. Present this summary to the user before anything else: what changed, which lenses were run last time.
• If it does not exist: note this is a fresh session.

Also check the project type: Rust library, CLI tool, web frontend, CLAUDE.md / documentation, etc. Infer from the file structure.

Step 2: Agree on lenses

Present the user with lens options based on project type. Suggest a preset but let them choose or customize. Do not proceed until confirmed.

Universal lenses

These apply to any codebase:

• api-clarity — public surface legibility from an external consumer's perspective: naming, ergonomics, discoverability
• api-gaps — public surface completeness: missing operations, asymmetric coverage, things you'd expect to exist that don't
• consistency — are patterns, contracts, error handling, and validation applied uniformly across analogous components? (goes beyond naming — behavioral consistency)
• doc-coverage — public items documented? examples work? links valid?
• ui-text — audit UI-visible strings (status bars, tooltips, dialogs, labels). Flag text that exists outside the functional inventory: labels, inputs, navigation, non-visible status, errors with remediation. Tutorials, narration of visible state, encouragement, and redundant descriptions are noise — recommend deletion, not rewording.
• error-surface — error types complete, meaningful, and consistent?
• completeness — what inputs or cases does this code silently accept that it should validate or reject?
• adversarial — make the strongest case against this code
• overfit — code over-tuned for one specific scenario at the cost of generality, correctness at edge cases, or readability; algorithms or data structures chosen for a benchmark that doesn't represent real usage
• interaction-model — from a user's perspective, what standard capabilities or flows for this kind of software are missing, broken, or incomplete? Compare against the established interaction conventions of the software category, not just the codebase's own API surface.
• affordance-design — Good UI answers "what can I do here?" from its own structure. Interactions are typed (commands, gestures, ambient signals, navigation) and each type earns a surface suited to it — forcing everything into command-form is itself a smell. Audit for: surfaces that force hunting instead of scanning; irrelevant items dimmed when they should be absent; layout that shifts unpredictably within a mode; and search or palette load-bearing for primary workflows instead of serving as a long-tail fallback. When a surface feels overwhelming, the fix is fewer composable primitives, not better filtering over a messy graph.
• legacy-debt — unannotated legacy code: stale patterns, commented-out blocks, deprecated paths, or dead code with no comment explaining why it's still present. Priority: unannotated legacy actively poisons agent context — an agent seeing an unexplained old pattern treats it as signal and copies it
• incomplete-migrations — in-progress transitions where old and new patterns coexist without a clear signal about which is canonical: type/struct renames where both names still appear, call sites not yet updated after an API change, mixed import styles, half-migrated error handling, TODOs referencing an in-flight refactor. Severity scales with breadth — a migration spread across dozens of files where old patterns dominate by count is the worst case: a cold agent surveys the codebase, concludes the old pattern is the house style, and copies it forward, making the migration harder to complete with every session