design-cleanup
Sweep the current branch for leftovers of an abandoned design after a significant mid-work decision change, and rewrite the affected code, comments, tests, and docs so the result reads as if it had been designed this way from the beginning. Use when the user says "design cleanup", "clean up the old approach", "erase the journey", says a design decision changed and asks to clean up after it, or after a pivot in approach mid-branch. This is a rewrite pass over the code touched by the decision only — not a general refactoring or bug-hunting pass.
- Installs
- 3.5K
- Last 24h
- +46
- Trending rank
- #3572
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/gjkim42/kanon-repo --skill design-cleanup- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads design-cleanup automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Design cleanup — make the tree read as designed-this-way
Why this skill exists
When a design decision changes mid-work — a different approach, a renamed concept, a replaced mechanism — the branch tends to keep fossils of the abandoned design: dead branches, shims that only served the old path, names shaped by the old concept, comments narrating the change, tests pinning behavior that no longer matters. The diff may show the journey; the final tree must not. This skill hunts those fossils down and rewrites the result as if the current design had been there from the beginning.
Step 1 — Establish the decision
State the decision as one line: "the design is X; the abandoned approach was Y". Take it from the user or the session context. If it is not stated, reconstruct it from the branch diff and commit messages, then confirm the one-line summary with the user before making sweeping edits — cleanup against a misread decision destroys correct code.
Step 2 — Determine scope
- Compute the branch diff:
git diff $(git merge-base HEAD origin/main)...HEAD(fall back toorigin/develop, thendevelop). - The cleanup covers only code touched by the decision: the changed files that implement it, plus files that reference the renamed or removed concepts (find them by grepping for the old names).
- Everything else is out of bounds. This skill is not a license for unrelated refactors, formatting passes, or opportunistic improvements.
Step 3 — Hunt the leftovers
Check each category against the in-scope files:
- Dead code: branches, parameters, feature flags, config keys, and helpers that only the abandoned path used.
- Shims and indirection: adapters, wrappers, and abstraction layers that existed only to bridge the old design to the new one.
- Names and structure: identifiers, files, and modules shaped by the
old concept —
newParser,handleV2,legacyFoo, or a module layout organized around a concept that no longer exists. - Comments and docstrings: anything describing the old design or narrating the change — "previously", "instead of", "now we", "changed from X to Y". Descriptions must state only the current design.
- Tests: tests that pin the abandoned behavior, transitional states, or the shape of the old API. Rewrite them for the intended behavior of the current design; do not keep them green by accident.
- Docs: README sections, ADRs, diagrams, and examples that describe the old mechanism. Update in place — no "migration note" additions.
- TODOs: items left for the old plan.
Step 4 — Rewrite, don't patch
- Rename to the current concept everywhere, not just where it is cheap.
- Delete dead code outright; never comment it out or gate it "just in case". Git history holds the old version.
- Collapse indirection that no longer earns its keep.
- Rewrite affected comments, docstrings, and docs to describe only the current state.
Step 5 — Verify and report
- Run the project's build and tests; the cleanup must not change behavior of the surviving design.
- Grep the resulting branch diff for history words as a smoke check:
previously|instead of|no longer|old |new |V2|legacy— hits are candidates to fix, not automatic violations; judge each. - Grep the whole tree for the abandoned names to confirm no dangling references remain.
- Report what was removed, renamed, and rewritten, grouped by the categories above, and call out anything suspicious that was left alone because it fell outside the decision's scope.
FAQ
What does the design-cleanup skill do?
Sweep the current branch for leftovers of an abandoned design after a significant mid-work decision change, and rewrite the affected code, comments, tests, and docs so the result reads as if it had been designed this way from the beginning. Use when the user says "design cleanup", "clean up the old approach", "erase the journey", says a design decision changed and asks to clean up after it, or after a pivot in approach mid-branch. This is a rewrite pass over the code touched by the decision only — not a general refactoring or bug-hunting pass.
How do I install design-cleanup?
Run npx skills add https://github.com/gjkim42/kanon-repo --skill design-cleanup in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/design-cleanup/ (personal) or .claude/skills/design-cleanup/ (project).
Which AI agents can use design-cleanup?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is design-cleanup safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains design-cleanup?
It is published by gjkim42 in gjkim42/kanon-repo. It has 3,500 recorded installs.
More from gjkim42/kanon-repo
review-all
gjkim42/kanon-repo
Run a two-agent code review: spawn two fresh, clean-context agents that examine the SAME committed branch diff in parallel. One agent runs Codex's native codex review --base command, while the other independently reviews the code against Google's "What to look for in a code review" guidance. Merge both outputs into one agreement-ranked report. Use this whenever the user asks for "review-all", a second-opinion review, a dual review, a cross-check before a PR, or a maximum-confidence review of committed branch changes. Do not use it to APPLY fixes; it is review-only.
api-review
gjkim42/kanon-repo
Review the current Kelos branch, or an explicitly specified PR, issue, or diff, for Kubernetes API and CRD design quality. Use when asked for a Kelos API review, CRD/API compatibility review, Kubernetes API convention review, or review of changes under api/, generated CRDs, examples/, or self-development/ manifests. Default to the current branch when no target is specified. This skill is review-only.
gjkim-instruction
gjkim42/kanon-repo
Create and maintain gjkiminstruction.md, the root document for a loop-engineering effort. The document holds only the minimum requirements and confirmed decisions, and deliberately leaves everything else open so that later iterations are not locked into early guesses. Use whenever the user mentions gjkiminstruction.md, a root document or root doc for a loop, loop engineering, starting a long-running agent loop on a goal, or asks to record a requirement or a confirmed decision for such an effort. Also use at the start of a loop iteration to check what is already decided versus still open.
pre-session-end
gjkim42/kanon-repo
Use this skill PROACTIVELY when the user indicates they are done working, ending the session, wrapping up, or saying goodbye. Also use when significant work has been completed and the user hasn't explicitly asked to continue. Analyzes the session to evolve skills/commands/agents and propagates useful project permissions to global settings.
address-pr-review
gjkim42/kanon-repo
Review the comments on a PR and address the findings that are valid and required. Use when the user says "address-pr-review", asks to address the PR review, handle or apply the review comments or review feedback on a PR, or fix what the reviewers asked for. Defaults to the PR for the current branch when none is named. This skill changes code; it is not a review pass.
pr-finish
gjkim42/kanon-repo
Finish an open PR by batching review feedback, applying valid fixes, running verification, pushing once per batch, and monitoring CI with bounded waits. Use when the user asks to update code until PR review comments are handled, review-all has no valid blocking findings, and required checks pass.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.