code-quality

name

code-quality

description

Improve the quality and type-safety of TypeScript/JavaScript being written or refactored — parse-don't-validate, make-illegal-states-irrepresentable, exhaustive matching, pure-function/IO separation, and public-API hygiene. Use when asked to refactor, clean up, improve, harden, or review the design/quality of code or an API. NOT for hunting bugs (that's /code-review) and NOT for vigiles's own spec/lint rules.

Apply a small set of type-driven quality techniques when writing or refactoring code. Each technique has its own reference — the principle, a real before/after from this repo, and the smells to grep for. Read the reference(s) that match the code in front of you; don't apply all five blindly.

When this fires

A request to refactor / clean up / improve / harden / tighten code or an API — or when you're about to write a new module/type/public export and want it right the first time. Not a bug hunt (use /code-review).

The techniques — read the matching reference

Smell in front of you	Technique	Reference
a magic 0 / "" / -1; the same primitive re-validated at many sites; "x" in obj repeated	Parse, don't validate	references/parse-dont-validate.md
a field that's always ""; boolean-flag soup; a sentinel standing in for "absent"; an impossible combo that still compiles	Make illegal states irrepresentable	references/make-illegal-states-irrepresentable.md
a switch/if-chain on a union with no exhaustiveness guard	Exhaustive matching	references/exhaustive-matching.md
logic tangled with IO (spawn/fetch/fs); a function that's hard to test	Pure functions + injected seams	references/pure-functions.md
a public export with a fuzzy shape; a string that means an enum; a leaked internal helper	Public-API quality	references/public-api-quality.md

How to apply

1. Name the decision out loud before you change the shape — what illegal state it forbids, where the parse boundary sits (the surface-architecture-decisions reflex). A quality change the reviewer can't see is churn.
2. One technique at a time, tests stay green. Change the type, let tsc show you every call site, fix them, run the tests. Never batch five refactors into one unreviewable diff.
3. Don't over-abstract (rule-of-three / YAGNI). A tagged union for 3 real variants is good; an abstraction for a difference that doesn't exist yet is the bug this skill is supposed to prevent.
4. Prefer the strongest option the DECIDABILITY allows — a type that can't express the bad state beats a runtime check that hopes to catch it; but a runtime guard at a boundary beats nothing when the input is genuinely dynamic.

Guardrails

• Quality only, not correctness. This skill improves shape/design; it does not hunt for bugs — that's /code-review.
• Every change removes a real failure mode. If you can't name the bug the new shape prevents, don't make the change.
• Keep the public surface small. A new export is a contract (see the public-API reference); don't widen it to make a refactor convenient.