Code Quality Skill

Write code that is easy to review, understand, and change. Optimize for the next developer's mental load before optimizing for machine performance, because readable code is cheaper to change, debug, and trust — and most performance wins come from algorithmic choices and profiling, not micro-optimizations.

The three quality axes this skill targets, in priority order:

1. Readability — a reader understands the code top-to-bottom on first pass.
2. Maintainability — the next variant of a concept is a one-file, one-edit change; existing utilities are reused rather than re-invented; one concept has one canonical home.
3. Pragmatic performance — algorithmic wins by default, micro-optimizations only when a profiler points at them.

This skill applies in four modes:

1. Plan mode — invoked with Skill("code-quality", "plan"), before any code is written. Reads a plan.md (or proposed approach) and the existing codebase, and verifies the plan's structure follows the existing patterns and avoids predictable design-time risks (premature parallel maps, missing branded primitives, untyped error paths, parameter creep, neighbour mismatch). Returns findings only — no code edits. Used by autonomous-workflow Phase 1. See rules/plan-mode.md.
2. Authoring mode — when writing new code (e.g., GREEN phase of TDD, new features). Apply principles inline so the first version already meets the bar. Default mode when no argument is passed.
3. Review mode — invoked with Skill("code-quality", "code") or Skill("code-quality", "review"), after code is written. When refactoring, reviewing PRs, or being asked to "clean this up". Diagnose against the rules and propose targeted changes. Returns findings only — no code edits.
4. Simplify mode — invoked with Skill("code-quality", "simplify"), after a feature is implemented and tests are green. Runs the review pass, then applies mechanical refactors (Class M recipes from rules/refactor-recipes.md) one at a time behind Skill("confidence", "code") ≥ 90 % and a scoped fast-check, reverting on failure. Judgment-class recipes (Class J) stay as proposals. See rules/simplify-mode.md. Variants: simplify aggressive also auto-applies Medium-impact mechanical recipes; simplify dry-run reports without writing; simplify <path> scopes to a path instead of the diff.

Detect the mode from the $ARGUMENTS first token: plan → plan mode; code or review → review mode; simplify → simplify mode; anything else (including no argument) → authoring mode. The legacy convention "user said review or audit" still routes to review mode for ad-hoc invocations.

---

The Core Bet

Cognitive complexity — how hard code is to understand — is the single best proxy for long-term maintainability. SonarSource's research showed that cyclomatic complexity (path counting) misses what actually hurts humans: nesting, broken linear flow, and decisions that compound. So the rules below target cognitive load, not theoretical complexity scores. Full citations (SonarSource, Clean Code, Knuth, Alexis King, Gary Bernhardt) and the research grounding for each rule live in references/citations.md.

When in doubt, the heuristic is: can a reader understand this function top-to-bottom on one pass without backtracking? If yes, ship it. If they have to scroll, jump, or hold a stack of conditions in their head, fix it.

The maintainability counterpart: if I add the next obvious variant of this concept, how many files do I have to edit, and will the type system catch me if I miss one? One file with full type coverage is excellent; four hand-synchronised maps in four files is shotgun surgery — fix the structure before adding the variant. See rules/maintainability.md.

---

Quick Reference (load these patterns into working memory)

Stack-flagship patterns

A few of the highest-leverage stack-specific rules. Each rule file under rules/stacks/ carries its own Common Mistakes section — load the file when working in that stack.

---

Procedure

The skill operates in four modes — plan (validate a plan), authoring (writing new code), review (refactor / audit, findings only), and simplify (review then auto-apply mechanical recipes). Detect the mode from $ARGUMENTS per the table above; default is authoring.

Load rules/procedure.md for authoring (13-step checklist) and review (8-step pass). Load rules/simplify-mode.md for the simplify procedure (partition → confidence-gate → apply one recipe at a time → scoped fast-check → revert on failure → whole-suite verify at end).

---

Rule Files

Load only what's relevant to the code in front of you. Reading every rule file every time is wasted context. The skill is language-agnostic at its core — the table below splits into framework-neutral rules and stack-specific extensions. Load a stack file only when the code is in that stack.

Language-agnostic rules

Stack-specific rules

See rules/stacks/README.md for the index and the convention for adding a new stack.

---

Critical Rules (apply always)

These are non-negotiable because they reflect human cognitive limits, not style preferences.

1. Linear flow beats branching

A function that flows top-to-bottom — guards, then logic, then return — is always easier than one with deep branching. If you have if/else if/else spanning 30 lines, restructure.

2. Names carry the load

Code is read 10× more than it's written. A 30-character name that explains intent saves more time than the keystrokes it costs to type. Conversely, single-letter names are fine for tight scopes (loop indices, math formulas) where the meaning is unambiguous from context.

3. Functions describe one thing

The function name should be a complete description of what it does. If the honest name is validateAndPersistAndNotifyUser, you have three functions.

4. Don't pre-build for futures that haven't arrived

Configuration parameters, abstraction layers, and feature flags for hypothetical needs all add cognitive load today with no benefit until the hypothetical arrives — and most never do. Build for the case in front of you; refactor when the second case shows up.

5. Comments explain WHY, never WHAT

A comment that restates the code is noise. A comment that captures a non-obvious constraint, a subtle invariant, or "we tried X and it broke because Y" is gold. If you're tempted to write a comment, first try to rename or extract until the code says it itself.

6. Optimize after measuring

Knuth: "premature optimization is the root of all evil." Until a profiler points at a hot path, prefer the readable version. Only ~3% of code drives performance; the other 97% should be optimized for the human reader.

7. Validate at boundaries, trust internally

Validate user input, external API responses, and untrusted data at the edge. Don't add defensive null checks throughout internal code — they hide real bugs by silently swallowing impossible states. If a value can't be null at this point in the code, don't pretend it can.

8. Reuse before creating

Before writing a helper, type, constant, or formatter, search the codebase for one that already exists. A second implementation of the same concept is worse than the first — behaviours drift, bugs get fixed in only one copy, and the next reader does not know which one is canonical. Reusing existing code is never premature.

9. One source of truth for union-type metadata

When a union or enum has associated data (labels, colours, icons, flags, defaults), put it in one record keyed by the union with structured values — not in N parallel maps. Adding a new variant must be a single edit, and the type system must catch you if you miss a field. Four hand-synchronised maps over OrderStatus are a bug waiting to ship.

10. Minimise the change footprint

A maintainable change touches few files, all type-checked. Before adding a new variant of a concept, ask: "if I add the next one, how many places do I need to edit, and will the compiler tell me if I miss one?" If the answer is "many" or "no", restructure first — usually by consolidating parallel maps, hoisting a duplicated constant, or co-locating data with the operations on it. See rules/maintainability.md §3.

11. Make illegal states unrepresentable

The cheapest place to catch a bug is the place the bug cannot exist. Lift constraints into the type system: discriminated unions for state machines, exhaustive switch with assertNever, branded primitives, refined types (NonEmptyArray<T>). Runtime guards that the type system could enforce are noise that drifts. See rules/abstraction.md §2.

12. Pure core, impure shell

Decision logic is pure: no I/O, no time, no randomness, no global state. Side effects live in a thin shell at the edges. Pure code is the cheapest to test and reason about; impure code is unavoidable but should be small enough to verify by integration tests. Inject the clock, RNG, fetcher, and ID generator rather than calling them directly. See rules/architecture.md §3 and rules/correctness.md §7.

13. Total functions over throw-for-missing

A function is total when every input has a defined output. Return null for absent-by-design and Result<T, E> for expected failures; reserve throw for programmer errors and unexpected I/O failures. Sentinels (-1, "", 0) lie — every sentinel collides with a real value the next caller will hit. See rules/api-design.md §4.

14. Test-first for new code

When authoring a new function, module, or behaviour, invoke the tdd skill (Skill('tdd')) to drive the implementation through a strict RED → GREEN → REFACTOR cycle. Apply the rules in this skill silently in GREEN; apply them explicitly in REFACTOR. Skip the handoff only for trivial edits, refactors of existing code, or when the user opts out. See rules/testability.md.

15. Pair with ux for UI files

When authoring or reviewing files that render UI (*.tsx, *.jsx, *.vue, *.svelte, React Native screens), invoke the ux skill (Skill('ux')) for the WCAG 2.2, semantic HTML, and platform-guideline pass. Accessibility lives in ux, not here — this skill defers. Apply the locator-stability subset from rules/testability.md (UI Testability section) so accessible names also serve E2E test stability. Skip only for non-UI files or pure refactors that don't touch markup. When invoked under autonomous-workflow Phase 3, ux runs there directly — do not double-invoke; rely on the phase-level call.

---

When Things Conflict

When principles pull against each other, load rules/tradeoffs.md for the tiebreakers (readability vs. performance, DRY vs. clarity, reuse vs. premature abstraction, short vs. clear naming, guard clause vs. single-return, co-location vs. layered folders).

---

Output Contract

In review mode, structure findings as a ## Code Quality Review: [target] block with sections for High / Medium / Low impact, plus required Maintainability findings whenever the reviewed code introduces or extends union types, enums, shared constants, or utilities, and required Correctness / Testability findings whenever it involves retryable operations, money, dates, async I/O, resource handles, or non-trivial pure logic. Load rules/output-contract.md for the full template.

In authoring mode, just write the code (or hand off to tdd first for new code). Apply the principles silently. Don't narrate every guard clause — the user sees clean code in the diff.