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".

1. Approve when the change improves code health, not when it is perfect. There is no perfect code, only better code.
2. A correct finding nobody acts on is a false positive. Scan broadly, report selectively — three actionable findings beat twenty true ones.
3. 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.md Rule 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 exhaustive switch over 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.