implementation-principles

Files (4)

• SKILL.md
• openai.yaml · agents/
• performance-gates.md · references/
• release-checks.md · references/

SKILL.md (first lines)

# Implementation Principles

## Core Rule

Make the smallest coherent change that satisfies the requested behaviour and
acceptance tests. Prefer the repository's existing design, code, and
dependencies over introducing another way to solve the same problem.

## Before Coding

Search the relevant call paths, modules, types, helpers, configuration, tests,
and dependencies. Identify what can be called, composed, or extended before
designing anything new. Check whether configuration or a small change to an
existing responsibility already expresses the required behaviour.

## Escalation Order

Climb only as far as the behaviour needs, and stop at the first step that
holds:

1. No code at all, because the behaviour is already there or was never asked
   for.
2. Existing code in this repository: the helper, pattern, or extension point
   already written.
3. The standard library.
4. A native platform or framework feature.
5. A dependency the project already has.
6. New code, as the smallest thing that satisfies the behaviour.

Climb after understanding the problem, not instead of it. The smallest change
in the wrong place is a second defect, not a shorter diff. When two options at
the same step cost the same, take the one that handles the edge cases: less
code does not mean the flimsier algorithm.

When a request is more elaborate than the need it names, say what would cover
that need with less, and let the requester choose.

## Scope The Mechanism

The escalation order says where code may come from. Within a step, take the
narrowest mechanism that meets the constraint, and scope it to the case that
needs it.

One hard case does not set the strategy for its neighbours: unbounded-precision
arithmetic belongs in the function whose width is unbounded, not in the other
eight; a mutex covers the path that is concurrent, not the package; a cache
wraps the call that is expensive, not every call; reflection serves the case
whose type is unknown. Read the constraint as written, since "must not wrap" is
narrower than "arbitrary precision", and the narrower reading often has a
fixed-width answer already in the standard library.

For a primitive every caller routes through, per-call cost is part of the
contract rather than a tuning detail, because it multiplies by every call site.
Settle it once from a measurement, not an assumption. This is not the premature
optimization the Avoid list names: that rule excludes work unrelated to the
current requirement, and a shared primitive's cost is part of its requirement.

## Domain Shape

Name the data and its states before writing logic. Encode the domain in one
structure - a state machine, a typed model, a lookup table, a single validated
type - rather than repeating the same shape assumption as conditionals across
files. Where the language allows it, make the illegal state unrepresentable
instead of guarding against it at each call site.

This is subtractive. It replaces scattered branches with one authoritative
shape. It does not license a new layer or a speculative interface (see Avoid).

## Delivery Workflow

Work on one requested item at a time. Treat the specification and its
acceptance tests as the source of truth.

For each behaviour change:

1. Write the relevant behavioural test first and run it to confirm that it
   fails for the expected reason. Follow **testing-principles**; do not invent a
   new test when supported behaviour is unchanged.
2. Implement the smallest change that makes the test pass.
3. Refactor only when the refactoring gate below permits it.
4. Re-run the targeted test, then run all relevant tests, linters, formatters,
   type checks, and other project quality gates before declaring completion.

If a required quality gate cannot run, report that explicitly. Do not claim it
passed.

For project performance gates or meaningful runtime-cost changes, read
[performance gates](references/performance-gates.md).
For release preparation or a release PR, read
[release checks](references/release-checks.md).

## Root Causes

Fix the cause, not the symptom. Reproduce the failure first, then trace it
until you can name the line that is wrong. A guard that suppresses a symptom
hides the defect and outlives it: a nil check around a value that should never
be nil, a retry around a deterministic failure, a widened type, a tolerance
loosened until the assertion stops firing.

One wrong line can have many callers. When it sits in a shared function, fix
it there and check every caller: one correction in the shared function is a
smaller change than one per call site, and repairing only the path the report
names leaves its siblings broken.

Reviewers check declared gaps and limitations as well as the diff. A "known
gap" needs evidence: an assumption such as "retry restores the data" cannot
dismiss a defect. Distinguish a demonstrated non-defect from a mitigation
that leaves an issue unresolved. Fix or route real unresolved issues under
[bugfix routing](../bugfix/references/incidental-issues.md), retaining an owner
or blocker; listing a limitation alone does not resolve it.

## Prove It Works

Verify against the real artifact, not a proxy. "It compiles", a green build
alone, a file timestamp, or a summary of what was intended are not evidence.
Run the code path and read the actual value.

Where the check can be a script, write the script and keep its output, so a
reviewer can re-run the same comparison instead of taking your word for it.

From wtsi-hgi/agentskills, MIT.

More from wtsi-hgi/agentskills