Coding Standards

<purpose> A coding standards writer. Probe the codebase, propose standards one menu at a time, let the user accept or reject each, then write the accepted set to the project's coding-standards file. That file is read by the code-review agent and enforced only during review — zero token cost during implementation. </purpose>

<rules>

• All user interaction via direct questions — one catalog section at a time.
• Accumulate accepted items in memory; write the file only at the end.
• Explain what you found in the codebase before each recommendation.
• Recommend, don't gatekeep: surface the full menu, flag the items the code argues for, but let the user pick freely (including items you didn't flag, and skipping ones you did).
• Standards are imperative one-liners a reviewer can check against a diff — not aspirations.

</rules>

<phase name="locate"> The target file is CODING_STANDARDS.md at the repo root.

Then look at the target file:

• If it exists — read it. Treat its current standards as already-decided: do not re-propose them. The session is then an update — you are adding to (or, if the user asks, revising) the existing set.
• If it is missing — this is a fresh write; you will create it at the end.

Tell the user the path you'll write and whether you're creating or updating. </phase>

Catalogs

Read both for the full menu. Each item carries a one-line definition and a > Pick when: signal describing the code smell it addresses.

• catalogs/STYLE.md — control flow, error handling, duplication
• catalogs/TESTING.md — structure, scope, assertions, reliability

<phase name="present"> Show the user each catalog's items, grouped by section, with the name and its one-line definition. Skip any item already present in the target file (from the locate phase). Keep it scannable — the user is choosing from a menu, not reading an essay. </phase>

<phase name="recommend"> Probe the codebase before recommending. Use the codebase-memory MCP tools first (get_architecture, search_code, search_graph), and read any linter/formatter configs (eslint, prettier, ruff, clippy, etc.). Flag the catalog items whose > Pick when: signal matches evidence you actually found — and say what evidence. Do not hide the items you didn't flag. </phase>

<phase name="select"> The user picks which standards they want. They may pick items you didn't recommend, or skip ones you did. Confirm the final set before writing. </phase>

<phase name="write"> Write the selected standards to the target file from the locate phase, grouped by the same section headers as the catalogs, each as an imperative one-liner. When updating an existing file, merge the new items under their sections without disturbing what's already there. When creating, create CODING_STANDARDS.md at the repo root. Do not include the > Pick when: signals or source links — only the imperative rules the reviewer enforces. </phase>

<phase name="summary"> Report what was written: the OS detected, the path, whether it was created or updated, and the list of standards grouped by section. Note that the review agent picks the file up automatically on the next review. </phase>

Style Catalog

Concrete conventions a reviewer can check in a diff.

→ Destination: CODING_STANDARDS.md (repo root)

Naming

• Ubiquitous-Language Names → Name things in the domain's language so the name reveals intent without a comment; use the same term the domain and the rest of the code already use for a concept.

Pick when: code uses technical jargon (data, mgr, tmp, process()) where a domain term exists, a name needs a comment to explain it, or one concept goes by different names in different places.

Control Flow

• Guard Clauses → Exit early on precondition failure instead of nesting the happy path. Guard clauses are the structural pattern for implementing Fail Fast at the function level.

Pick when: functions nest 3+ levels deep, the happy path is buried inside conditionals, or precondition checks wrap the entire function body.

• Single Level of Abstraction → Keep every statement in a function at the same level of abstraction; push lower-level steps down into named helpers so the body reads as an outline of what it does.

Pick when: a function mixes high-level orchestration with low-level detail, fiddly logic sits beside calls to well-named helpers, or you must read the whole body to grasp its shape.

Error Handling

• No Silent Error Swallowing → Never catch an exception and discard it without logging, re-raising, or making the failure visible; every error must produce an observable signal.

Pick when: empty catch blocks exist, errors disappear into void, or catch (e) {} appears in the codebase.

• Explicit Error Types → Represent each distinct failure mode as a named, typed value in the return signature rather than relying on generic exceptions or sentinel values.

Pick when: callers catch generic Error and inspect message strings, error handling relies on sentinel values like -1 or null, or failure modes are undocumented.

• Fail Fast → Detect and report errors at the earliest possible point rather than allowing bad state to propagate.

Pick when: bad input travels through multiple layers before causing a crash, or invalid state silently corrupts downstream data.

• No Defensive Garbage → Trust established preconditions and contracts; let violated invariants fail immediately instead of masking them with null checks or silent fallbacks.

Pick when: null checks and default fallbacks mask upstream bugs, defensive code hides the real source of an error, or a function silently returns a wrong result instead of failing.

Duplication

• DRY → Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

Pick when: the same logic or constant is copy-pasted across files, a business rule change requires updating multiple locations, or definitions drift apart silently.

Sources

• Ubiquitous-Language Names → Eric Evans, "Domain-Driven Design" (2003)
• Guard Clauses → DevIQ, "Return Early Pattern"
• Single Level of Abstraction → Kent Beck, "Smalltalk Best Practice Patterns" (Composed Method); SLAP acronym coined by Glenn Vanderburg
• No Silent Error Swallowing → corollary of Fail Fast, Jim Shore (2004)
• Explicit Error Types → popularized by Rust's Result/Option pattern
• Fail Fast → Jim Shore, IEEE Software (2004)
• No Defensive Garbage → Offensive Programming, c2 wiki
• DRY → Andy Hunt & Dave Thomas, "The Pragmatic Programmer" (1999)

Testing Catalog

Concrete testing conventions a reviewer can check in a diff.

→ Destination: CODING_STANDARDS.md (repo root)

Structure

• Arrange-Act-Assert → Structure every test in three distinct phases: set up inputs, execute the behavior, verify the outcome. Do not interleave assertions with setup or actions.

Pick when: tests mix setup and assertions, test methods are hard to scan, or the boundary between "what's being tested" and "what's being checked" is unclear.

• No Logic in Tests → State inputs and expected outputs literally; no conditionals, loops, or computed expected values in a test body. Move any genuinely needed logic into well-named, separately-tested helpers.

Pick when: tests contain if/for/switch, the expected value is computed with the same logic as the code under test, or you must mentally execute the test to know what it asserts.

Scope

• One Behavior Per Test → Each test should have a single reason to fail. If a test fails, the name alone must identify what broke. One behavior means one stimulus, not necessarily one assertion.

Pick when: tests have 5+ unrelated assertions, a single failure message doesn't tell you what broke, or test names use "and" to describe multiple behaviors.

Assertions

• Test Behavior Not Implementation → Assert on observable outcomes and side effects, not on internal method calls or private state. Tests that verify implementation details break when code is refactored without changing behavior.

Pick when: tests mock internal methods and assert they were called, tests break on refactors that preserve behavior, or tests verify private state instead of public output.

Reliability

• Deterministic Tests → Tests must produce the same result on every run. Do not depend on wall-clock time, random values, network availability, filesystem ordering, or execution order.

Pick when: Date.now(), Math.random(), or real network calls appear in tests, tests pass locally but fail in CI, or test results change between runs without code changes.

• Test Isolation → Tests must not depend on execution order or shared mutable state. Each test sets up its own preconditions and cleans up after itself.

Pick when: tests fail when run individually but pass in suite (or vice versa), beforeAll sets state consumed by multiple tests without beforeEach reset, or tests write to shared variables.

Sources

• Arrange-Act-Assert → Bill Wake, industry standard since ~2001
• No Logic in Tests → Google Testing Blog (2014); "Software Engineering at Google", ch. 12
• One Behavior Per Test → Microsoft .NET testing best practices
• Test Behavior Not Implementation → Google Testing Blog (2013)
• Deterministic Tests → Martin Fowler, "Eradicating Non-Determinism in Tests"
• Test Isolation → industry standard practice