karpathy-principles

What this skill does

> The models make wrong assumptions on your behalf and
> just run along with them without checking. They don't
> manage their confusion, don't seek clarifications,
> don't surface inconsistencies, don't present
> tradeoffs, don't push back when they should.
>
> (Andrej Karpathy, on agentic coding failure modes)

## What This Is

A four-principle contract for reducing the most common
LLM coding pitfalls. Compact entry-point. Each
principle has a deeper-dive skill in night-market;
this skill is the index, not the encyclopedia.

Derivation: distilled by Forrest Chang
(forrestchang/andrej-karpathy-skills, MIT) from
Karpathy's observations. Full attribution in
`references/source-attribution.md`.

## When to Use

- Before starting any coding task larger than a typo
- During code review, to name the failure mode you see
- After writing a diff, to self-audit before claiming
  done
- When training a junior engineer to read agent diffs

## When NOT to Use

These principles bias toward caution over speed. For
cases listed in `modules/tradeoff-acknowledgment.md`,
use judgment: trivial fixes, exploratory spikes,
documentation-only edits, and time-boxed prototypes.

## The Four Principles

### 1. Think Before Coding

**State assumptions. Surface confusion. Match tone to
evidence.**

- If multiple interpretations of the request exist,
  list them. Do not silently pick.
- If a simpler approach exists, name it. Push back
  when the simpler path is correct.
- If something is unclear, stop and ask. Hidden
  assumptions are the cheapest bug to prevent and the
  most expensive to find later.
- Make claims no stronger than the evidence supports.
  Calibrated tone beats confident hand-waving.

Deep dives: `Skill(imbue:rigorous-reasoning)` for the
sycophancy guard, `Skill(superpowers:brainstorming)`
for option generation, `/spec-kit:speckit-clarify`
command for ambiguity drilldown.

### 2. Simplicity First

**Minimum code that solves the problem. Nothing
speculative.**

> They really like to overcomplicate code and APIs,
> bloat abstractions.
>
> (Andrej Karpathy, on the same agentic-coding thread)



- No features beyond what was asked
- No abstractions for single-use code
- No flexibility or configurability that wasn't
  requested
- No error handling for impossible scenarios
- If you wrote 200 lines and it could be 50, rewrite
  it

Self-check: would a senior engineer say this is
overcomplicated? See `modules/senior-engineer-test.md`.

Deep dives: `Skill(imbue:scope-guard)` for the
worthiness formula and branch budgets,
`Skill(leyline:additive-bias-defense)` for burden of
proof on every addition,
`Skill(conserve:code-quality-principles)` for the
KISS / YAGNI / SOLID foundation.

### Record the Tradeoff (decision journal)

When this step settles a decision with real alternatives, record it to
`docs/tradeoffs.md` while the reasoning is live (draft and confirm):

- If leyline is installed, invoke `Skill(leyline:decision-journal)` and append
  a tradeoff entry (the decision, the options weighed, and what was
  sacrificed; set `phase` to `plan`). Show the draft; append on
  confirmation.
- Fallback (leyline absent): append to `docs/tradeoffs.md` using the in-file
  ENTRY TEMPLATE; assign the next `TR-NNN` id.

### 3. Surgical Changes

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

- Do not improve adjacent code, comments, or
  formatting
- Do not refactor things that aren't broken
- Match existing style even when you would do it
  differently
- If you notice unrelated dead code, mention it; do
  not delete it
- When your changes orphan imports or variables,
  remove the orphans you created. Pre-existing dead
  code stays unless asked.

The trace-back test: every changed line should trace
directly to the user's request.

Deep dives: `Skill(imbue:justify)` for additive-bias
audits on diffs, `Skill(leyline:additive-bias-defense)`
for the burden-of-proof contract, the
`bounded-discovery.md` rule for read-budget caps.

### 4. Goal-Driven Execution

**Define verifiable success criteria. Loop until
verified.**

Transform vague tasks into checkable goals:

- "Add validation" becomes "tests for invalid inputs
  pass"
- "Fix the bug" becomes "test reproducing the bug,
  then make it pass"
- "Refactor X" becomes "tests pass before and after"
- "Make it faster" becomes "benchmark Y under N ms"

For multi-step tasks, state a brief plan with
verification per step. Strong success criteria let
you loop independently. Weak criteria require
constant clarification.

See `modules/verifiable-goals.md` for the full
reformulation template.

Deep dives: `Skill(imbue:proof-of-work)` for the Iron
Law (no implementation without a failing test first),
`Skill(superpowers:test-driven-development)` for the
RED-GREEN-REFACTOR loop.

## The Karpathy Self-Check

Before you ship, four questions:

| Principle | Question |
|-----------|----------|
| Think Before Coding | Did I list assumptions, or did I guess silently? |
| Simplicity First | Would a senior engineer call this overcomplicated? |
| Surgical Changes | Does every changed line trace to the request? |
| Goal-Driven Execution | Can I prove this is done with a check, not a feeling? |

Four "yes" answers means ship. Anything else means
iterate.

## Modules

- `modules/anti-patterns.md` - eight named drift rails
  with before/after diffs
- `modules/senior-engineer-test.md` - the
  three-question self-check battery
- `modules/verifiable-goals.md` - vague-to-verifiable
  reformulation template with worked examples
- `modules/tradeoff-acknowledgment.md` - when the four
  principles do not apply

## References

- `references/source-attribution.md` - Karpathy
  primary citation, Forrest Chang derivation, license,
  adjacent prior art

## Related Skills

- `Skill(imbue:scope-guard)` - worthiness formula and
  branch budgets
- `Skill(imbue:proof-of-work)` - Iron Law TDD gate
- `Skill(imbue:rigorous-reasoning)` - sycophancy and
  hidden-assumption guard
- `Skill(imbue:justify)` - additive-bias diff audit
- `Skill(leyline:additive-bias-defense)` - burden of
  proof on every addition
- `Skill(conserve:code-quality-principles)` - KISS,
  YAGNI, SOLID
- `Skill(superpowers:test-driven-development)` -
  RED-GREEN-REFACTOR
- `Skill(superpowers:brainstorming)` - generate
  options before committing
- See `docs/quality-gates.md#skill-level-quality-gate-composition`
  for the full gate-skill federation graph (this skill
  is the synthesis hub)

## Required TodoWrite Items

When invoked as a pre-flight gate, create:

- `karpathy:assumptions-listed` - principle 1 satisfied
- `karpathy:simplicity-checked` - principle 2 satisfied
- `karpathy:trace-back-verified` - principle 3 satisfied
- `karpathy:success-criteria-defined` - principle 4
  satisfied

## Exit Criteria

- Each of the four principles has been answered with a
  concrete artifact (assumption list, scope rationale,
  diff trace, verification plan).
- The senior-engineer test was applied at least once.
- Verifiable success criteria are written down before
  the implementation begins.
- The chosen approach and its simplicity tradeoff are
  recorded to `docs/tradeoffs.md` (or the in-file
  template) when real alternatives were weighed.