typescript-clean-code

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.

Load	Unit	For
references/smells/tooling.md	the repository	First, in every review. Which smells a linter decides, so those become one "wire this into CI" finding instead of twenty hand-written ones
references/smells/rules.md	a line, a function	Per-line heuristics (C/E/F/G/N/T), plus the review posture and severity vocabulary that govern all four layers
references/smells/fowler.md	a modification	The twelve above — detection question, TypeScript remedy, and when NOT to fix for each
references/smells/typescript.md	a type	TS1-TS10: any leakage, assertion versus validation, exhaustiveness, strictness flags, branded types

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.

Workflow	For
workflows/code-review/workflow.md	Reviewing code for quality
workflows/pr-review/workflow.md	Reviewing pull requests
workflows/refactoring/workflow.md	Safe refactoring with tests (step 3 sweeps all twelve; steps 5-8 loop)
workflows/tdd.md	Test-driven development cycle
workflows/new-feature.md	Building new functionality
workflows/bug-fix.md	Fixing bugs properly
workflows/test-strategy.md	Planning test coverage
workflows/estimation.md	Estimating tasks (PERT)
workflows/deadline-negotiation.md	Handling unrealistic deadlines

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.