tac-karpathy-discipline

The full skill.

Original instructions from the publisher’s SKILL.md

# Karpathy Coding Protocol — TAC Express Edition

> Adapted from Andrej Karpathy's observations on LLM coding pitfalls.
> Bias: caution over speed. For trivial one-liners, use judgment — not every change needs full rigor.

---

## PRINCIPLE 1 — Think Before Coding

Don't assume. Don't hide confusion. Surface trade-offs.

**Before writing a single line:**
1. State assumptions explicitly. If uncertain about scope, data shape, or intent — ASK.
2. Surface ambiguity. If the request has multiple valid interpretations, present them. Never pick silently.
3. Push back when warranted. If a simpler approach exists, say so. If the ask violates The Fourteen Laws, name the violation and propose the compliant alternative.

**TAC Express checks BEFORE coding:**
- Which package does this belong in? (`packages/ui` / `packages/services` / `packages/database` / `apps/web` / `apps/dashboard`)
- Does this violate any of The Fourteen Laws?
- Is a forbidden package about to be installed?
- Is business logic ending up in a component instead of `packages/services`?
- Am I about to call Supabase directly from a component (LAW 6/8)?
- Does the status update need a TrackingEvent insert (ADR-004)?

```
❌ "Update the shipment status" → sets shipment.status directly
✅ Flags: ADR-004 says status is event-derived. Inserts a TrackingEvent instead.

❌ "Add a filter" → writes filter logic in the component
✅ Moves filter logic to packages/services, passes result as prop
```

---

## PRINCIPLE 2 — Simplicity First

Minimum code that solves the problem. Nothing speculative.

- No features beyond what was asked
- No abstractions for single-use code
- No error handling for impossible scenarios
- If you write 200 lines and it could be 50 — rewrite it

**TAC Express–specific simplicity rules:**
- Don't pre-build multi-variant CVA components when only one variant is needed yet
- Don't create a service function for something called only once from one place
- Don't add loading/error states to a component that has no async data yet
- Don't add Zod schemas for data that isn't user-facing input yet
- Don't create new CSS tokens when existing ones already express the intent

---

## PRINCIPLE 3 — Surgical Changes

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

**When editing existing files:**
- Do NOT "improve" adjacent code, comments, or formatting
- Do NOT 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, and functions that your changes made unused
- Do NOT remove pre-existing unused code unless explicitly asked

**TAC Express–specific surgical rules:**
- Don't reorder exports in `packages/ui/src/components/index.ts` unless the task requires it
- Don't rename CSS custom properties you didn't introduce
- Don't touch `apps/web/app/layout.tsx` fonts unless the task is font-related (ADR-005)
- Don't "clean up" `globals.css` tokens while fixing a layout bug
- Don't switch `var(--token)` to inline hex while "just fixing padding"

---

## PRINCIPLE 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 → make them pass" |
| "Fix the bug" | "Write a test that reproduces it → make it pass" |
| "Make it look better" | "Apply Violet Grid token pattern → verify no raw colors" |
| "Integrate the service" | "Mock at DB boundary → unit test passes → integration test passes" |

**TAC Express verification ladder (run in order):**
```
1. pnpm typecheck             → zero TypeScript errors
2. pnpm lint --max-warnings 0 → zero ESLint warnings
3. pnpm test                  → all tests pass
4. pnpm build                 → succeeds in all packages
5. Browser check              → feature works end-to-end in dev
6. Visual review              → Violet Grid token compliance, no hardcoded values
```

---

## Quick Decision Matrix

| Task Type | Mode | Apply Principles |
|-----------|------|-----------------|
| Obvious 1-liner / typo fix | Speed | 3 only |
| Bug fix | Caution | 1 + 3 + 4 |
| New feature | Full rigor | All 4 |
| Refactor | Caution | 1 + 2 + 3 + 4 |
| Code review | Full rigor | All 4 |
| Design/token change | Full rigor | 1 + 3 + Law compliance |

---

## Violation Response Protocol

When asked to do something that violates The Fourteen Laws:

```
"I can't do that — it violates [LAW X].

What you asked: [restate request]
Why it violates: [brief explanation]
Compliant approach: [concrete alternative]"
```

Never silently comply with a violation. Always name it and propose the fix.

---

## Worktree & artifact hygiene (end-of-session teardown)

> Added 2026-05-18 after the post-#162 follow-up surfaced an inert
> `tac-whatsapp-sends-102/` directory sitting at the repo root — a stale
> clone from a previous worktree-style session that nobody tore down.
> Inert directories at the repo root pollute grep, pollute `git status`,
> and make worktree-list inspection misleading.

### At the start of a session that creates a worktree

1. Use `git worktree add` to a path **outside the repo root**
   (`C:/tac/tw-<short-task-name>` is the established convention —
   see existing `tw-dod`, `tw-launch`, `tw-prodscope`, `tw-sb1` …)
   OR use the harness `Agent({ isolation: "worktree" })`, which
   auto-cleans on no-op.
2. Never `git clone` a sibling copy of the repo *inside* the primary
   clone's directory. The repo root is for the primary working tree only.

### At the end of every session

Whenever the session created a worktree, before declaring the run done:

1. **List worktrees:** `git worktree list`.
2. **Identify the ones this session created.** Branch name + path
   should match.
3. **For each whose PR is merged or abandoned:**
   - `git worktree remove <path>` — drops the worktree.
   - `git branch -D <branch>` — ONLY if the branch is fully merged
     or deliberately abandoned. Otherwise keep it.
4. **If a stale non-worktree directory exists inside the repo root**
   (an old clone, a scratchpad copy, an untracked sibling repo):
   - Verify it is NOT a registered worktree (`git worktree list`
     does not show it AND `<dir>/.git` does not exist).
   - Confirm with the owner before deleting if there's any chance
     it contains uncommitted work.
   - Otherwise `rm -rf <dir>` — repo-root pollution is a real cost.

### Sentinel against recurrence

If the same untracked-stale-directory artifact appears again across
sessions, that's a `tac-skillify` trigger — convert this section into
a hooked cleanup step rather than written discipline. Until then, the
written rule + end-of-session checklist is the floor.