implement

What this skill does

# Implementation

Verification-driven coding with tight feedback loops. Distilled from 21,321 tracked operations across 64+ projects, 612 debugging sessions, and 2,476 conversation histories. These are the patterns that consistently ship working code.

**Core insight:** Verify in tight loops, roughly every 2-3 edits. 73% of fixes go unverified across the dataset, which is the single biggest quality gap. Sessions that maintain a tight verify cadence avoid the debugging spirals that the rest of this skill is designed to prevent.

**How to read this skill:** the loop and the heuristics below are calibrated for non-trivial implementation work. Trivial fixes (config, typo, single-line) shouldn't drag through five phases. Use judgment, scale planning to scope, and skip what doesn't apply. The Code Discipline section is principles that bias toward caution; for one-line changes, just make the change.

## The Loop

Implementation work composes from five things that must all be true by the time a chunk ships. Not a fixed order; the graph below shows the natural dependencies and the loop-backs that are routine in practice.

```dot
digraph implement {
    rankdir=LR;
    node [shape=box];

    "ORIENT" [style=filled, fillcolor="#e8e8ff"];
    "PLAN" [style=filled, fillcolor="#fff8e0"];
    "IMPLEMENT" [style=filled, fillcolor="#ffe8e8"];
    "VERIFY" [style=filled, fillcolor="#e8ffe8"];
    "COMMIT" [style=filled, fillcolor="#e8e8ff"];

    "ORIENT" -> "PLAN";
    "PLAN" -> "IMPLEMENT";
    "IMPLEMENT" -> "VERIFY";
    "VERIFY" -> "IMPLEMENT" [label="fix", style=dashed];
    "VERIFY" -> "COMMIT" [label="pass"];
    "COMMIT" -> "IMPLEMENT" [label="next chunk", style=dashed];
}
```

- **Oriented.** Existing code is read before anything gets touched. `Grep → Read → Read` is the dominant opening across the dataset. Sessions that read 10+ files before the first edit require fewer fix iterations downstream. Blind changes are the most expensive way to start.

- **Planned.** Decomposition exists at the right scale. Trivial fixes don't need a plan; features benefit from a task list; epics earn a research swarm. The decision is "what's proportional," not "always plan."

- **Implemented.** Work happens in batches of roughly 2-3 edits, then verifies. Follow the dependency chain. Edit existing files 9:1 over creating new ones; that's the observed ratio in successful sessions. Fix errors as they surface; accumulating them creates cascade-debugging.

- **Verified.** Typecheck is the primary gate, fast and cheap; run it between batches. Tests fit naturally after feature-complete. Full suite before commit.

- **Committed.** Atomic chunks, committed as you go. Stage specific files, commit, loop back to the next chunk. Many small commits per session is the pattern that consistently outperforms one mega-commit at the end. See **Commit Cadence** below for message anatomy.

**Trajectories that compose these:**

- **Typo fix**: Oriented (read the file) → Implemented → Verified (typecheck) → Committed. No Planned needed.
- **Standard feature**: Oriented → Planned → Implemented → Verified → Committed → loop back into Implemented for the next chunk.
- **Bug with cascade**: Oriented → Implemented → Verified (fails) → re-Implemented → Verified (passes) → Committed. The dashed VERIFY → IMPLEMENT edge above is this case.
- **Epic with phases**: Oriented → Planned (decomposition) → (Implemented → Verified → Committed) per phase → re-Oriented when the next phase changes the picture.

---

## Code Discipline

Principles that shape how you move through the loop, not steps to execute. Adapted from Karpathy's [observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls: models "make wrong assumptions on your behalf and just run along with them without checking ... really like to overcomplicate code and APIs, bloat abstractions ... implement a bloated construction over 1000 lines when 100 would do."

These principles bias toward caution because that's where models drift. For trivial fixes, the calculus inverts; apply judgment, not the full discipline.

### Think before coding

Don't assume. Don't hide confusion. Surface tradeoffs.

| Situation                               | Action                            |
| --------------------------------------- | --------------------------------- |
| Multiple interpretations of the request | Present them; don't pick silently |
| A simpler approach is plausible         | Say so; push back when warranted  |
| Something is unclear                    | Stop; name what's confusing; ask  |
| You hold a load-bearing assumption      | State it explicitly               |
| Inconsistency between request and code  | Surface it before proceeding      |

ORIENT (read the code) is the prerequisite. This principle is what to do with what you find: name the gaps, don't paper over them.

### Simplicity first

Minimum code that solves the problem. Nothing speculative.

| Don't                                          | Do                                           |
| ---------------------------------------------- | -------------------------------------------- |
| Add features beyond what was asked             | Solve exactly the stated problem             |
| Build abstractions for single-use code         | Inline first; abstract when reused           |
| Add "flexibility" or configurability not asked | Hardcode now; parameterize on demand         |
| Handle errors for impossible scenarios         | Trust internal invariants; validate at edges |
| Write 200 lines when 50 would do               | Rewrite tighter                              |

The test: would a senior engineer call this overcomplicated? If yes, simplify.

### The judo move

Simplicity first is defensive: don't add bloat. The judo move is offensive: when bloat is already mounting, hunt the restructuring that makes it vanish. Same behavior, dramatically simpler shape, a design that feels inevitable in hindsight.

Mounting complexity is the cue, not the cost of doing business. When a change starts sprouting special cases, a function won't stop growing, or you reach for a cast to make the types agree, stop and look for the move before pushing through. Models drift toward elaborating complexity; the discipline is to reach for the eraser first.

| Smell                                                     | The judo move                                                          |
| --------------------------------------------------------- | ---------------------------------------------------------------------- |
| New `if` bolted onto an unrelated flow for one case       | Pull the case behind its own abstraction, or reframe so it can't arise |
| A wrapper that just forwards to another function          | Delete it; call through directly                                       |
| The same conditional copy-pasted across call sites        | Extract the decision into one home: a helper, a type, a model          |
| Feature logic living in a shared/util module              | Move it to the module that owns the concept, its canonical home        |
| `any`/`unknown`/casts smoothing over a shape you distrust | Make the type honest; let the contract carry the invariant             |
| Generic "magic" hiding a simple data-shape assumption     | Boring, explicit, direct code beats clever indirection                 |
| Independent async steps run in sequence                   | Run them in parallel; let related state land atomically                |

The test: are you **deleting** complexity or **relocating** it? Rearranging the same concepts into tidier piles isn't a judo move; removing a concept, a branch, a layer, or a mode is. If the diff only moved the mess, keep looking.

### Surgical changes

Touch only what you must. Clean up only your own mess.

| Rule                                                   | Why                                             |
| -----------------------------------