BumpyClock/agent-templates / skills/programming
programming
UnverifiedImplement, debug, refactor, or review code with scoped changes and evidence.
references/refactoring/clean-refactoring.md
View on GitHub# Clean Refactoring
Use when the user asked for a refactor, or when the requested change cannot land coherently without consolidating an owner, adapter, or parallel path.
For duplication that the change does not depend on, leave the code and list it in the report.
Core rule: refactoring replaces the old shape with the simpler shape the codebase would want today. It should leave one concept with one clear owner and clear consumers.
## Workflow
1. Establish the behavior contract and relevant evidence before structural edits. Include outputs, errors, side effects, and required compatibility.
2. Identify the concept, current owners, and consumers. Include configuration, documentation, and string-based references where they can affect behavior.
3. Choose the target owner and representation. Use [Redesign from First Principles](../../../pstack/principle-redesign-from-first-principles/SKILL.md) when new constraints expose repeated exceptions.
4. Move consumers in coherent behavior-preserving units. Use [Migrate Callers Then Delete Legacy APIs](../../../pstack/principle-migrate-callers-then-delete-legacy-apis/SKILL.md) when one interface replaces another.
5. Assess the result through affected consumers against the behavior contract. Account for stale references and any retained bridge.
Use [Subtract Before You Add](../../../pstack/principle-subtract-before-you-add/SKILL.md) when a bounded removal simplifies the requested change.
For a discovered defect or new behavior, separate that work from the refactor contract.
## Rules
- Do not let sunk cost decide architecture. Size the refactor by end-state quality, behavior risk, and reviewability, not by how much old code exists.
- Search before building a new mechanism. Reuse, consolidate near-duplicates inside the refactor contract, extract shared core, or build new deliberately after seeing what exists.
- Prefer one shared primitive over duplicate adapters when their semantics match.
- Do not preserve dev-only compatibility by default. Unshipped scaffolding should move to the clean contract immediately.
- Preserve required public API, CLI, configuration, and stored-data compatibility unless the authorized migration replaces that contract.
- Reuse owned values in consumers and consistency checks. Preserve independent expectations for computational and external contracts in tests.
- When divergence was the bug class, make ownership visible in tests, debug output, logs, or stats.
- Use real or asymmetric fixtures/assets for orientation, geometry, layout, ordering, and framing bugs. Symmetric placeholders can hide flipped coordinate frames or swapped axes.
- Assess existing coverage before a refactor. Add tests only for material gaps and when justified.
- For a large reshape, compare old and new outputs on representative inputs when existing checks leave equivalence uncertain.
- Update docs/specs with the new invariant and owner, not a mechanical file list.
- If scope widens into unrelated behavior, slice it: land the shared contract first, then port consumers in reviewable passes.
## Smells
- Same business rule in two modules.
- Config read in many places with local defaults.
- Adapter that only renames fields between internal shapes.
- Test oracle computes the expected value by duplicating production logic.
- Compatibility wrapper with no removal trigger.
- "Temporary" branch older than the feature it supported.
- An abstraction hides no useful decision or invariant, regardless of caller count.
## Verification
- Relevant existing or revised checks cover paths that used to diverge.
- Old and new surfaces report or exercise the same source of truth.
- Stale owner/adapter path is deleted, or remaining bridge has explicit removal condition.
- Diff does not include unrelated cleanup.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |