git:20261021.f7f992d to git:20261022.c5514d3

---

name: implementation-standards

description: "Engineering criteria for implementation: SOLID, Clean Code, patterns, comment anchors, quality signals and simplification-first debt."

license: MIT

---

# Implementation standards

> Load this skill before writing or reviewing code. It is the **source of engineering criteria**;

---

## SOLID

- **S** — one reason to change per class; one use case per application service.

- **O** — extend through composition, polymorphism and dependency injection before inheritance.

- **L** — subtypes must be substitutable without breaking invariants; prefer composition.

- **I** — keep interfaces small and specific to their consumer; no god interfaces.

- **D** — dependencies point toward the domain; high-level modules do not depend on low-level ones.

- Supporting concepts: cohesion, low coupling, encapsulation.

## Design patterns

- Apply them **only when the problem justifies it** and they reduce complexity.

- Premature abstraction is debt, just like duplication.

- Common: Factory, Strategy, Repository, Specification, Observer, Builder.

## Clean Code

- Meaningful names that reveal intent; no cryptic abbreviations.

- Small functions that do one thing.

- No dead, commented-out or unrefactored code.

- DRY with judgment: do not abstract for the sake of abstracting.

## Comment anchor (mandatory)

- Comments explain **why**, never what or how.

- Reference an **ADR** (`adr/NNNN-...`) or functional documentation.

- **Never** reference `openspec/specs/` (they are deltas that get archived).

- **Never** reference roadmaps, planning documents or other projects as the justification.

- If no ADR anchors the decision, the comment is **self-contained**: decision and reason, here and now.

## Quality controls are signals, not goals

- Do not delete blank lines, split methods without cohesion or add trivial tests to pass a number.

- Do not raise the CRAP threshold so a change passes.

- Do not exclude files with real logic from coverage or CRAP.

- If a touched file has pre-existing lint violations, resolve them; do not leave debt "because it was

not mine".

- If a limit is close, **refactor** or **document why** in the commit.

## Technical debt: simplification first

1. Extract Method / Extract Class.

2. Decompose Conditional / Replace Conditional with Polymorphism.

3. Introduce Parameter Object / Preserve Whole Object.

- Protected by the existing tests (green before and after).

- Additional tests are a **complement**, not a substitute for reducing complexity.

- Do not mask a complex method with tests that only cover the happy path.

## Tests

- Test behavior, not implementation details.

- No disabled tests, magic sleeps or trivial assertions.

- Cover error paths and business rules, not only the happy path.