Modified Karpathy Guidelines

Modified Karpathy Guidelines

Tradeoff: prioritize correctness and clarity over speed.

1. Think Before Coding

• State assumptions explicitly.
• If multiple valid interpretations exist, present options.
• Classify risk (low|medium|high) by security, data integrity, availability, blast radius.
• For medium/high risk, define mitigations before coding.

2. Simplicity First

• Do not add unrequested features.
• Avoid speculative abstractions/configurability.
• Prefer the smallest behavior-preserving solution.
• For each simplification, cite how behavior is preserved (test/check/requirement).
• Do not add new external dependencies without explicit human approval or a documented pre-approved policy.
• For dependency changes, cite the approval source/policy in the final response.

3. Goal-Driven Execution

• Convert requests into verifiable outcomes.
• For multi-step work, provide a dependency plan:

T1: <step> -> depends_on: [] -> verify: <artifact/check>
T2: <step> -> depends_on: [T1] -> verify: <artifact/check>

4. Verification Contract

• Run at least one task-relevant verification step.
• Code/config changes: run executable checks.
• Feature work: add or update automated tests for new behavior, including at least one edge/failure path when feasible.
• Review-only tasks: run deterministic evidence collection (for example diff/file inspection) and disclose unverified runtime behavior.
• Run stack-relevant quality gates before completion (at minimum lint, typecheck, and targeted tests when available).
• For dependency or security-sensitive changes, run available security checks (for example dependency vulnerability scan or SAST) and report results; if unavailable, disclose explicitly.
• Report commands/checks run and outcomes.
• If checks cannot run, explain why and list unverified items.

5. Scope Traceability

• Keep every change in-request or required fallout.
• Do not perform unrelated cleanup.
• If DRY conflicts with scope, preserve scope and document deferred refactor.

6. Blocker Protocol

• Ask at most 3 high-impact clarifying questions.
• Proceed with assumptions only when not safety-critical.
• If ambiguity affects security/auth/compliance/data integrity/destructive operations, stop and request clarification.
• If blocked, report blocker, impact, attempts, next options.

7. Regression Discipline

• Bug fix: add or identify reproducer when feasible.
• Refactor: verify behavior parity.
• If regression test is infeasible, provide deterministic alternative verification.

8. Acceptance Checklist

Internal self-check (not required user-facing format unless editing this guideline):

1. Sections ## 1 through ## 8 remain present and ordered.
2. DRY and scope precedence are explicit.
3. Verification rules include evidence/unverified disclosure.
4. Dependency approval policy is respected.
5. Simplification claims include behavior-preservation rationale.
6. Feature work includes tests for added behavior (and edge/failure path when feasible).
7. Quality gates include lint/typecheck/tests and security checks, or explicit unverified disclosure.