Audit an area of the codebase and propose the smallest structural moves that improve it - untangle boundaries, kill duplication, fix seams, break cycles. Produces a prioritized plan and decision records, not a rewrite.
SkillScore68Maintained
Automatic
◆Coding pack
Last verified 8/13/2026
What it changes
Passed 13 of 19 test cases with the skill, and 12 of 19 without it.
Without skill64%
With skill68%
Checks it passed that the model alone missed
Reference using module-map for the initial one-screen visualization.
Recommend mapping current system entry points before proposing changes.
Warn against premature indirection unless the duplicated logic drifts over time.
and 2 more in the full report
3 fixed12 passed either way5 still failing2 broke
Pass-rate lift
+5 pp
Tokens
-23%
Agent turns
0%
Response time
-44%
Model gemini-3.6-flashMeasured 8/13/2026v115 of 22 cases passed with skill · 19 comparable
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 3 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 3
Prompt
Here is our user authentication module auth_service.py. It has become messy and has circular dependencies with user_repository.py. Go ahead and refactor the source code right now to rewrite both files into clean classes.
What was checked, without and with the skill
Checked
Without skill
With skill
Refuse to execute immediate source code rewrites before producing a diagnostic plan.
Missed
Passed
case-04 · gemini-3.6-flash · 8/13/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md45 linessingle file
improve-architecture
Invest in the shape of the system a little at a time rather than paying for a
rewrite later. This skill diagnoses and proposes; it does not rewrite on its own.
Method
Map first. Get the current shape before judging it - entry points,
modules, data flow, who calls whom. Reuse module-map for the one-screen
view; do not skip to opinions.
Find the strain. Look for the load-bearing problems, not style nits:
God modules that everything imports and nothing can change safely.
Leaky boundaries - a module reaching into another's internals instead of
its surface.
Duplicated logic that drifts (the same rule implemented three ways).
Wrong seams - the code is split where it does not bend and fused where it
does.
Cyclic dependencies.
A shape that fights the domain (see domain-modeling - boundaries in code
should track boundaries in the language).
Propose the smallest move. For each problem, the least change that
relieves it: extract a boundary, collapse a duplicate, invert a dependency,
move a seam. Prefer a sequence of safe steps over one big cut.
Rank by leverage. Order the moves by pain relieved over effort. Say which
are safe now and which need a test net first (pair with tdd).
Record the big calls. For a structural change a future reader would
question, write a decision record in docs/decisions/NNNN-slug.md: context,
choice, alternatives rejected, why.
Guardrails
Diagnose, do not rewrite. The deliverable is a plan the user approves before
any code moves.
No churn for taste. A move must relieve a named strain; "cleaner" is not a
reason.
Three similar lines beat a premature abstraction - do not trade duplication
for indirection unless the duplication actually drifts.
Keep behavior fixed. Structural moves are refactors; land them behind green
tests.