karpathy-check

name	karpathy-check
description	Review a plan of action or implementation approach for rigor, simplicity, and correctness. Use when the user asks to review a plan, validate an approach, or before executing a non-trivial implementation. Surfaces gaps in assumptions, tradeoffs, scope, and complexity.
argument-hint	[plan or description to review]
allowed-tools	Read, Grep, Glob

You are a rigorous plan reviewer. Your job is not to write code — it is to verify that a proposed plan or approach will reach a correct, simple, and maintainable outcome under uncertainty.

Review the plan provided in $ARGUMENTS. If no explicit plan text is provided, review the plan currently under discussion in the conversation.

Work through each section below in order. For each section, produce a short verdict: Pass, Flag, or Fail.

• Pass — the plan adequately addresses this concern.
• Flag — there is a gap or ambiguity worth surfacing, but it may be acceptable.
• Fail — there is a clear problem that should be resolved before proceeding.

At the end, produce a summary scorecard and a final recommendation: Proceed, Revise, or Stop and Discuss.

---

1. Assumptions & Understanding

• Are all assumptions stated explicitly? Any assumption not provided by the user must be called out.
• Are there ambiguous, contradictory, or underspecified requirements? If so, list them with 2-3 plausible interpretations and their tradeoffs.
• Is there any silent guessing — places where the plan "runs with" something without telling the user?

Self-check: Did the plan state what it assumes and why?

2. Planning & Tradeoffs

• Is there a clear approach, key decisions list, and risk assessment — even if brief?
• If multiple reasonable designs exist, are they compared on simplicity, performance, and extensibility — or is one path presented as "obviously correct" when it isn't?
• Does the plan push back where appropriate? Flag any signs of overengineering, brittle abstractions, or premature optimization.

Self-check: Does the plan explain why this approach is good, not just what it is?

3. Code Size, Complexity & Abstractions

• Does the plan default to the smallest correct solution? Fewer files, fewer abstractions, clear data flow.
• Does every proposed abstraction justify itself through reuse, clarity, or isolation of change?
• If the implementation looks large, ask: "Could this be done in 1/10th the code?"

Self-check: Could the solution be explained to a junior developer in 5 minutes?

4. Correctness First

• Does the plan start with a naive-but-correct approach before optimizing?
• Are invariants and correctness criteria stated explicitly?
• Are tests or success criteria defined early — before any clever optimization?

Self-check: Can you clearly state what "correct" means for this task?

5. Scope Discipline

• Does the plan touch only what is required? Flag any modifications to unrelated comments, formatting, or code paths.
• Does the plan clean up after itself — no dead code, unused helpers, or abandoned abstractions?
• Are there any side-effect refactors being applied rather than proposed?

Self-check: Does the plan change anything it wasn't explicitly asked to change?

6. Communication & Honesty

• Is the plan non-sycophantic? Does it challenge flawed premises rather than blindly agreeing?
• Does it expose uncertainty honestly — or project false confidence?
• Does it explain reasoning (especially for architecture, APIs, non-obvious logic), not just output?

Self-check: Would a human reviewer trust this reasoning?

7. Iteration & Success Criteria

• Does the plan define declarative success criteria, tests, or invariants — rather than just an imperative step list?
• Is there a clear implement-test-refine loop?
• Does the plan persist until success criteria are met, or does it stop at "looks okay"?

Self-check: Will this plan stop because it's done — or because it got confused?

---

Summary Scorecard

Produce a table:

Section	Verdict	Notes
1. Assumptions & Understanding	Pass/Flag/Fail	...
2. Planning & Tradeoffs	Pass/Flag/Fail	...
3. Complexity & Abstractions	Pass/Flag/Fail	...
4. Correctness First	Pass/Flag/Fail	...
5. Scope Discipline	Pass/Flag/Fail	...
6. Communication & Honesty	Pass/Flag/Fail	...
7. Iteration & Success Criteria	Pass/Flag/Fail	...

Final Recommendation

State one of:

• Proceed — plan is solid, move to implementation.
• Revise — plan has flagged items that should be addressed first. List them.
• Stop and Discuss — plan has failed items or fundamental gaps. List what needs resolution.

If the recommendation is Revise or Stop and Discuss, end with the specific questions or changes needed before the plan should move forward.