From 24eb5e2bb2fa934914dcc215ddf8d5b8b2140267 Mon Sep 17 00:00:00 2001
From: Jiayuan <forrestchang7@gmail.com>
Date: Tue, 27 Jan 2026 22:35:52 +0800
Subject: [PATCH] docs: expand README with detailed Karpathy skills content

Add comprehensive explanations of the four principles:
- Think Before Coding: explicit reasoning and assumption surfacing
- Simplicity First: anti-patterns and the "senior engineer" test
- Surgical Changes: editing vs cleaning up your own changes
- Goal-Driven Execution: imperative to declarative transformation table

Also add sections for measuring effectiveness, customization guidance,
and tradeoff notes for trivial vs non-trivial tasks.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 101 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7bbba6b..2720ee7 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ From Andrej's post:
 
 ## The Solution
 
-Four principles in one file:
+Four principles in one file that directly address these issues:
 
 | Principle | Addresses |
 |-----------|-----------|
@@ -23,6 +23,73 @@ Four principles in one file:
 | **Surgical Changes** | Orthogonal edits, touching code you shouldn't |
 | **Goal-Driven Execution** | Leverage through tests-first, verifiable success criteria |
 
+## The Four Principles in Detail
+
+### 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+LLMs often pick an interpretation silently and run with it. This principle forces explicit reasoning:
+
+- **State assumptions explicitly** — If uncertain, ask rather than guess
+- **Present multiple interpretations** — Don't pick silently when ambiguity exists
+- **Push back when warranted** — If a simpler approach exists, say so
+- **Stop when confused** — Name what's unclear and ask for clarification
+
+### 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+Combat the tendency toward overengineering:
+
+- 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 200 lines could be 50, rewrite it
+
+**The test:** Would a senior engineer say this is overcomplicated? If yes, simplify.
+
+### 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting
+- Don't refactor things that aren't broken
+- Match existing style, even if you'd do it differently
+- If you notice unrelated dead code, mention it — don't delete it
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused
+- Don't remove pre-existing dead code unless asked
+
+**The test:** Every changed line should trace directly to the user's request.
+
+### 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform imperative tasks into verifiable goals:
+
+| Instead of... | Transform to... |
+|--------------|-----------------|
+| "Add validation" | "Write tests for invalid inputs, then make them pass" |
+| "Fix the bug" | "Write a test that reproduces it, then make it pass" |
+| "Refactor X" | "Ensure tests pass before and after" |
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let the LLM loop independently. Weak criteria ("make it work") require constant clarification.
+
 ## Install
 
 **Option A: CLAUDE.md (recommended)**
@@ -52,3 +119,36 @@ From Andrej:
 > "LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."
 
 The "Goal-Driven Execution" principle captures this: transform imperative instructions into declarative goals with verification loops.
+
+## How to Know It's Working
+
+These guidelines are working if you see:
+
+- **Fewer unnecessary changes in diffs** — Only requested changes appear
+- **Fewer rewrites due to overcomplication** — Code is simple the first time
+- **Clarifying questions come before implementation** — Not after mistakes
+- **Clean, minimal PRs** — No drive-by refactoring or "improvements"
+
+## Customization
+
+These guidelines are designed to be merged with project-specific instructions. Add them to your existing `CLAUDE.md` or create a new one.
+
+For project-specific rules, add sections like:
+
+```markdown
+## Project-Specific Guidelines
+
+- Use TypeScript strict mode
+- All API endpoints must have tests
+- Follow the existing error handling patterns in `src/utils/errors.ts`
+```
+
+## Tradeoff Note
+
+These guidelines bias toward **caution over speed**. For trivial tasks (simple typo fixes, obvious one-liners), use judgment — not every change needs the full rigor.
+
+The goal is reducing costly mistakes on non-trivial work, not slowing down simple tasks.
+
+## License
+
+MIT