Coding

Coding

Discover before assuming. Verify before shipping. Every coding failure traces to acting on assumptions instead of evidence, declaring done without verification, or burning context on noise.

Core Loop

Discover → Plan → Implement → Verify

• Discover — read the code, trace dependencies, understand what exists.
• Plan — define success criteria, scope the change, order the work.
• Implement — write minimal code, one change at a time, commit each.
• Verify — run the checks, confirm the requirement, show the evidence.

The threshold: if you can describe the diff in one sentence, skip planning. Otherwise, plan first.

The Assumption Interrupt

Apply this silently — don't narrate the check.

• Using a method, type, or interface without having read its definition
• Recalling an API from memory instead of reading current source
• Planning changes to code you haven't read in this session
• Assuming a method signature, type structure, or interface shape

When you catch one, read the source before continuing.

Discovery Protocol

Read the Scars

Intent leaves no trace in code, but change does. Each shape below is a question, never a conclusion — the provenance rule binds here, so nothing read off code shape is a fact until a witness outside the code confirms it.

• An exported symbol nobody calls — possibly a fossil of whatever replaced it. Look for the successor.
• Armor bolted on — a guard, a retry, a sanitizing pass, a defensive copy around code that would not obviously need one. Something may have failed here.
• A hack where a clean path exists — serializing an object to text and parsing it back where a copy would do. Ask what blocked the clean path.
• Redundant repairs — two layers fixing the same thing. One of them may be dead.

Chase each with git history, the tracker, or the person who owns the code. A confirmed answer narrows what your change must not break; an unconfirmed one stays a question and constrains nothing.

Planning Discipline

• Success criteria — restate the task as something you can check. "Add validation" becomes "invalid inputs have tests, and those tests pass." "Fix the bug" becomes "a test reproduces it, and that test passes." A criterion you cannot run is not a criterion, and it is what forces you back to the user mid-task.

• Scope — what files change, what stays untouched. Bound it explicitly. Don't "helpfully improve" adjacent code.

• Decomposition — before writing any code, write the ordered list of changes you will make, one commit each. This is where the work gets split. Splitting at commit time means untangling a diff that was never built to come apart, and that rarely succeeds — the pieces are already interleaved across the same files and lines.

  Name each entry by its kind of work, because a change carries only one kind: refactor, new code, integration, fix, formatting, docs. Two sources feed the list:

  • The task statement, before you read any code. "Implement and integrate X" is already two entries: the new code standalone, then the wiring that puts it to use.
  • Discovery, once you have read the code. If the existing code needs a refactor to make room, that refactor is entry one, committed on its own, before any new code exists.

  A dummy layer that integrates end to end and does nothing is usually entry one or two; after it, one capability at a time in dependency order — storage standalone and verified, then the handler that calls it, then the surface above.

  Then work the list one entry at a time. Never write code for the next entry until the current one is committed. That rule is what makes the plan binding — without it the list is a note you abandon at the first opportunity.

• Risks — what could break. If modifying shared code, trace all callers first.

Implementation Discipline

One Change at a Time

An uncommitted working tree is the unit nobody can review and nobody can bisect. Commit at each verified step during the work, not once at the end. A large change is not one hard review — it is a review nobody does, and the defect that survives it costs more than the whole change saved.

Atomic is a code boundary, not a task boundary. An atomic change is the smallest change that leaves the tree working: it builds, its tests pass, nothing is half-wired. It is not the smallest change that satisfies the request. One task is normally many atomic changes.

The second test catches what the first cannot see. A refactor and the feature it enables build and pass together, so deliverability alone keeps them in one diff — and the reviewer then separates "what moved" from "what is new" by hand, which is the review that silently does not happen. At equal correctness, take the finer split.

Both tests belong to planning. They decide the change list before code exists; here they only confirm the list held. Applying them for the first time to a finished diff is already the failure. If it happens, say so, salvage what separates cleanly, and start the next task from a change list.

Three things trigger a commit. Any one is enough, and they are not a sequence — most commits fire on the first.

Four rules qualify all three:

The git-commit plugin's commit skill carries the pipeline for each of these — unit boundaries, message, validation.

Stay Inside the Change

• Every changed line traces to the request. Run that test over the finished diff; a line that traces to nothing is scope creep that got in while you were somewhere else.
• Clean up the orphans your change created — an import, a variable, a helper that your edit made unused. Pre-existing dead code is not yours to delete: mention it and leave it.
• Wear one hat at a time. Refactor first with behavior identical, verify, then change behavior. A diff that does both can't be reviewed or bisected.

Write Simple Code

Agents overcomplicate by default. Before writing new code, climb the reuse ladder and stop at the first rung that holds. The ladder runs after you understand the problem — read the code the change touches and trace the real flow first, then climb. It shortens the solution, never the reading: a small diff you don't understand is laziness dressed up as efficiency.

Two rungs hold → take the higher one and move on.

Follow Existing Patterns

Search the codebase for an existing pattern before inventing one. Match the error handling, the testing patterns in adjacent tests, and the naming conventions. Read CLAUDE.md and the lint config for project-specific rules. When two patterns contradict, pick one (more recent, more tested), explain the choice, and flag the other for cleanup — never blend them into an average. If you think an existing convention is harmful, surface it; don't fork it silently.

Read references/patterns.md when writing error paths, introducing a seam for testability, reshaping a function whose body reads worse than it works, or improving existing code rather than changing its behavior.

Naming

A name is read at every use site; a comment is read once — so a vague name is the defect that forces the explanation above it. Read references/naming.md when naming a new symbol, when writing a diagnostic a user will read, when a comment's payload would fit in an identifier, or when a name in code you touch reads two ways. It carries the naming rules and the limits on renaming what already exists.

Comments

The default is zero comments, and it is not a judgment call. Five kinds may exist and nothing outside the list does: a doc comment on a public symbol, the justification on an escape hatch, shortcut:, constraint:, why?:. There is no sixth kind and no "this one is genuinely useful" exception.

Before writing a comment, climb the routing ladder and stop at the first rung that holds: a better name, a test, a doc comment, a rule in the project's rule document, a design note in the architecture doc, one of the five markers, or drown it. Drown is the default verdict and it is silent.

Read references/comments.md before writing, repairing, or reviewing any comment or doc comment. It carries the full closed set, the marker grammar, the provenance rule for a WHY, the doc-comment contract, and the repair scope.

Debugging

Read references/debugging.md when a test fails, a bug is reported, or behavior surprises you — before proposing a fix. It carries the ordered protocol, the multi-component localization step, and the counter that turns a third failed fix into a design question rather than a fourth fix.

Verification Discipline

Verification is the highest-leverage activity in the loop. Code that "looks right" but hasn't been run is unverified.

Never Silence the Signal

A failing check is information about the code, not an obstacle to green. Make checks pass by fixing the code — never by weakening the check.

Before Declaring Done

1. Run the tests. If none cover the code you changed, write them. If you modified existing behavior, run the full relevant suite, not just the new tests.
2. Check both axes. Spec: does it do what was asked — the success criteria from planning — not merely something plausible? Standards: does it follow this repo's conventions (CLAUDE.md, lint and type config, ADRs)? Check them separately: code can satisfy every convention and implement the wrong thing, and a correct result can still violate the conventions.
3. Review your own diff as if it were someone else's. Leftover debug code, comments outside the five kinds, docs describing the old contract, missing error handling, hardcoded values, uncovered edge cases, dead code from earlier attempts.
4. Type-check and lint. Don't ship with known warnings.
5. Disclose gaps. "Done" means fully verified. "Done, but I didn't verify X" beats a silent gap.

Evidence, Not Assertion

Every claim below needs its own proof. The third column is what people submit instead.

The last two are the ones most often asserted and least often checked. An absence you cannot show a sweep for is an absence you do not claim, and an agent's success report is a claim like any other.

Self-Verification Patterns

• Write a failing test first, then implement until it passes.
• A test must be able to fail. One that cannot fail when the business logic changes is testing nothing.
• Use subagents for fresh-context review — they catch mistakes you'll miss in the context where you wrote the code.
• For UI changes, exercise the feature in a browser. Type checks and test suites verify code correctness, not feature correctness; if you can't test it, say so rather than claiming success.
• For refactors, verify identical behavior before and after.

Context Management

• Don't pre-load files "just in case" — retrieve context when the need for it arrives, not before.
• After two failed corrections on the same issue, start fresh rather than accumulating failed approaches in context.
• If you're losing track of what you've tried, say so. Silent degradation wastes more time than admitting it.

Application

Apply these disciplines silently. Don't narrate the protocol, announce which step you are on, or report a check that found nothing.

When writing code: run discovery, work the change list, commit as each trigger fires, verify before reporting.

When reviewing code: cite the specific violation with file:line and show the fix. Don't lecture.

If the codebase contradicts a rule here, follow the codebase and flag the divergence once. The comment default is the exception: a commented-out-everything codebase is a convention you neither match nor sweep. Match the code's patterns, not its prose.

Integration

This skill runs before the language skill and again before you declare done. It governs the shape of the work — what to read, how to split it, when to commit, what may be a comment, what proves completion. The language skill governs syntax, idiom, toolchain, and which symbols need a doc, and it wins on anything language-specific.

Return to the verification protocol above before declaring any task complete.