| name | engineering-craft |
| description | Use when writing or changing any production code or tests — new features, bug fixes, refactors, or test authoring, in any language, by any model on any CLI. |
Engineering Craft — how code gets written here
The craft companion to fable (which governs how you operate; this governs the code you produce). Content is distilled from 2025-26 measured evidence — mutation-testing studies, million-commit analyses of AI-written code, and benchmarked skill collections — not textbook restatement. Sources: knowledge-base/research/coding-craft-2026/.
Iron Laws (RIGID — no exceptions, no negotiation)
- No production code without a failing test first. Watch it fail, for the RIGHT reason (assertion failure on the missing behavior — not a compile error, not a typo). If code came first anyway: delete it, write the test, start over. Yes, really.
- Completion = machine evidence. Every task ends with a runnable check (test run, build, diff) whose real output you show. "Should work" is not a state of code.
- Search before you write. Before adding any function/type/helper: search for the existing one. Duplication is the measured #1 AI-code pathology (+81% duplicated blocks since 2023). Extending beats re-creating; consolidating beats both.
- Never weaken a test to make it pass. Tests encode intent. If a test is wrong, fix it in a commit that says so; if it's right, fix the code. Deleting/skipping/loosening assertions to go green is falsifying evidence.
- The diff you ship is the smallest correct one. No drive-by refactors, no unrequested "improvements", no formatting churn outside touched lines. File separate work separately.
Rationalization table (RIGID — if you think it, stop)
| The thought | The reality |
|---|
| "This is too simple to need a test" | Simple code breaks too; the test costs 2 minutes and is the only proof you ran it. |
| "I'll add tests after it works" | After-tests pass by construction and verify nothing. Red-first or start over. |
| "A mock is easier here" | Agents over-mock measurably (mocks in 36% of agent commits touching tests vs 26% of non-agent commits). Mock only process boundaries (network, clock, subprocess) — never your own logic. |
| "I'll extract an interface for testability" | Interfaces-for-mocking is inverted design. Consumer-side interfaces, only when ≥2 real implementations exist. (Different threshold from rule-of-three, which governs code duplication.) |
| "While I'm here, I'll clean this up" | Scope creep buries the actual change in review noise. Note it, file it, move on. |
| "Coverage is high, tests are good" | 85% coverage can hide a 57% mutation kill rate. Ask: would this test FAIL if the logic inverted? |
| "This helper probably doesn't exist yet" | Search first (Iron Law 3). The codebase is bigger than your context. |
| "The linter/reviewer is wrong, I'll ignore it" | Decline visibly with a reason, or comply. Silent disagreement re-litigates forever. |
The write-code loop (RIGID)
- Scope contract: one sentence of goal + explicit non-goals; identify the blast radius (what must NOT change behavior).
- RED: failing test(s) — the new behavior's test + for bug fixes a regression test (fails pre-fix) AND preservation tests (pass pre-fix, must stay green).
- GREEN: minimal implementation. Match surrounding conventions (naming, error style, comment density) even where you'd choose differently.
- REFACTOR: only with green tests, only within scope; consolidate any duplication you introduced.
- EVIDENCE: run the check, show output as
N/N PASS, no regression; verify the diff against the scope contract (nothing outside it).
Red flags in code you just wrote (RIGID)
- A test with no assertion, or asserting only that a mock was called.
- A new
if err != nil { return nil } (swallowed error) or empty catch.
- A guard clause for a condition nothing can produce (agents add ~2× unnecessary guards — every guard needs a caller that triggers it or a test that proves the boundary).
- A comment narrating what the next line does (comments answer why; the code answers what).
- Two blocks that differ by a variable name (extract, or if <3 occurrences, deliberately leave and note — rule-of-three).
- An exported symbol nothing outside the package calls.
References (progressive disclosure — load what the task needs)
| Reference | Load when |
|---|
| references/tdd-craft.md | writing any test — red-first mechanics, test-quality-over-coverage, anti-mock discipline, regression twins, property-based and table-driven patterns |
| references/clean-code.md | writing/reviewing production code — the empirically-surviving rules, duplication discipline, reviewability budgets, comment policy, error handling |
| references/design-patterns.md | structuring components — DI/Strategy/Specification/ports-adapters selection, misuse table, Go interface discipline, when NOT to abstract |
(Flat-namespace installs — e.g. the codex target — project only SKILL.md; the reference files are absent.)
Works with (don't duplicate these)
minimalism — the laziest-correct-solution ladder; invoke alongside this skill for green-field code.refactor / code-review-simplify — orchestrate refactoring and review sessions; this skill sets the standards they check against.golang-test-review — Go-specific test review depth.fable (references/verification.md) — the operating-level completion/verification protocol this skill's Iron Law 2 instantiates for code.
Precedence
User/project instructions (CLAUDE.md, AGENTS.md) outrank this skill where they conflict; this skill outranks default model behavior. RIGID sections are non-negotiable; everything else adapts to the codebase's existing conventions — convention-matching itself being one of the RIGID expectations.
