Clean Code
The twelve change-shape smells
Shotgun Surgery · Feature Envy · Data Clumps · Long Method · Divergent Change · Duplicated Code · Large Class · Long Parameter List · Primitive Obsession · Message Chains · Dead Code · Speculative Generality
You know each one and its refactoring. The value is the checklist, not the definitions — without the names a diff "looks fine"; with them you find the shape. Run all twelve against any change you review or write.
The smell catalog has four layers
Each examines a different unit, so each sees what the others miss.
A diff can satisfy every rule in rules.md and still be badly shaped — that is what
fowler.md is for. Reviewing a change means all four.
Review posture
Three rules that change output more than any catalog entry. Full text in
references/smells/rules.md → "Review posture".
- Approve when the change improves code health, not when it is perfect. There is no perfect code, only better code.
- A correct finding nobody acts on is a false positive. Scan broadly, report selectively — three actionable findings beat twenty true ones.
- Mark polish as ignorable. Conventional Comments labels —
issue,suggestion,nitpick,question,praise— with(blocking)/(non-blocking). An author who cannot tell which comments are optional treats all of them as mandatory, or none of them.
A review is done when all four layers have run, every surviving finding carries
a label and (for an issue) a fix, and the report states how many findings were cut
as unlikely to be acted on.
Contested rules
Three rules in these references are positions with live counter-arguments, marked contested where they appear. Present both sides and prefer the author's demonstrated reasoning over the number:
- Function length —
references/functions/rules.mdRule 1. Detect by "can I name each section?"; the "2-5 lines" figure over-extracts when applied literally. - Comments —
references/comments/rules.md. Keep rationale, invariants, and non-obvious why; delete restatement and stale comments. - G23 polymorphism —
references/smells/rules.md. An exhaustiveswitchover a discriminated union is idiomatic TypeScript, not a smell.
Workflows
Load the workflow.md, then its step files in order. Each step names the references
it needs and updates stepsCompleted in the output document's frontmatter, so a
compacted context resumes from the last completed step via step-01b-continue.md.
References
references/<topic>/ holds rules.md (the rules), examples.md (curated
TypeScript bad/good pairs — prefer these over inventing your own), and
knowledge.md (concepts).
Code quality: naming · functions · classes · comments · error-handling · unit-tests · formatting · smells
Professional practice: professionalism · saying-no · commitment · coding-practices · tdd · practicing · acceptance-testing · testing-strategies · time-management · estimation · pressure · collaboration
Load the topic's rules.md before advising on it, and cite the rule you applied —
the design problem it names, not the metric that pointed at it. Where a reference
contradicts your general knowledge, the reference wins: it carries this skill's
TypeScript adaptations and thresholds.
guidelines.md maps symptom → reference file and task → workflow.
