seri-agent / rules

---
description: Code-quality rules (Karpathy guidelines) for writing, editing, or reviewing code.
globs: "**/*.{ts,tsx,js,jsx,py,go,rs,java}"
alwaysApply: true
---

# Code-quality rules (Karpathy guidelines)

These apply whenever writing, editing, or reviewing code.

## Think before coding
- State assumptions explicitly before implementing. If uncertain, ask — don't guess silently.
- If multiple interpretations exist, present them; do not pick one without surfacing the choice.
- If a simpler approach exists, say so and push back.

## Simplicity first
- Write the minimum code that solves the problem. No speculative features, abstractions, or
  configurability that wasn't asked for.
- No error handling for scenarios that cannot happen.
- If the result is 200 lines and could be 50, rewrite it.
- Gut check: "Would a senior engineer call this overcomplicated?" If yes, simplify.

## Surgical changes
- Touch only what the task requires. Do not improve adjacent code, comments, or formatting.
- Match existing style, even if you would do it differently.
- If you notice unrelated dead code, mention it — do not delete it.
- Remove only the imports / variables / functions that YOUR changes made unused.
- Every changed line should trace directly to the user's request.

## Goal-driven execution
Transform every task into a verifiable goal before touching code:
- "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" → confirm tests pass before and after.

For multi-step tasks, state the plan first:
```
1. [step] → verify: [check]
2. [step] → verify: [check]
```
Weak success criteria ("make it work") hide bugs. An acceptance check must be seen to fail
before it counts as passing. Record the negative control next to the green result.

## Carry forward known test guards
Before writing a new test that exercises a primitive already covered elsewhere, open that
existing test first and copy any platform guard (`describe.skipIf`) or timeout margin it
already needed.

## Cross-platform env-var-dependent code
A local pass is not evidence for a path that depends on `HOME` / `LOCALAPPDATA` / homedir.
Teardown must `delete` an env var when the original was unset; never assign `undefined`
(Node/Bun coerce that to the string `"undefined"`). Green CI on N OSes does not cover the
unset case: delete the variable or make the directory unwritable and assert the fallback.

## Comments
A comment explains why the code is shaped this way using terms the code itself provides.
It must never cite a stage/phase number, a plan document, a loop slug, a PR number, or a
review round. If you change code that a nearby comment describes, make the comment true
or delete it. A comment that documents an intention rather than a behaviour is worse than
none.