critical-self-review
Skill0 starsChanged 4 months agoMITView on GitHub
Applies graduated, context-aware structured skepticism to AI output to catch lazy reasoning, unstated assumptions, and hidden complexity—without drowning responses in boilerplate.
In this repository3 other files it gives its agents.
- microstep-plannerSkill
- root-cause-investigatorSkill
- test-runner-analyzerSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 36
If the current approach is more complex, justify the extra complexity with a specific reason.
- Distinctive: line 41
Not theoretical edge cases—realistic ones.
- Distinctive: line 47
Use only when the context indicates production use or when the user explicitly requests deep critique.
- Distinctive: line 94
If you cannot defend it, change it: Do not defend the indefensible.
- Distinctive: line 97
Do not create new requirements: If the user did not ask for tests, do not demand them here.
- Distinctive: line 98
Respect the user's time: If the Core Protocol finds nothing concerning, move on.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Critical Self-Review
You are your own skeptic. Before delivering output, subject it to internal review.
The goal is not to generate a wall of text, but to catch errors that feel "obvious in hindsight."
When to Apply
| Context | Action |
| Single pure function, no side effects, no state | Skip. Do a 10-second mental check. |
| Multiple functions, state, I/O, or architecture | Run the Core Protocol internally. |
| User explicitly asks for critique | Run the Core Protocol and summarize findings in 1-2 sentences. |
| Production-critical code (auth, payments, concurrency, data integrity) | Run the Full Protocol and append the Review Block. |
Core Protocol (Internal, ~30 seconds)
Answer these three questions honestly. If any answer makes you uncomfortable, fix the output
before sending it. Do not append this to your response.
- What am I assuming that could be wrong?
Unstated constraints, hidden dependencies, or "this will always be true" beliefs.
- What is the simplest correct solution?
If the current approach is more complex, justify the extra complexity with a specific reason. "The domain is complex" is not a reason.
- What input or change would break this?
Not theoretical edge cases—realistic ones. Empty collections, race conditions, requirement drift, or the user copy-pasting this into a different environment.
Full Protocol (Production-Critical Output Only)
Use only when the context indicates production use or when the user explicitly requests deep critique.
Append a Review Block of no more than 4 lines.
1. Assumption Audit
Name the top 2 unstated assumptions. If you cannot name 2, you have not thought hard enough.
2. Simplicity Check
State the simplest alternative you considered and why you rejected it with a specific dimensional
tradeoff (e.g., "rejected O(n²) because n > 10k; accepted O(n log n) with higher memory").
3. Failure Mode
What is the single most likely way this fails in production? Be specific. "A bug" is not an answer.
4. Design & Documentation Hygiene
Hunt for code smells (long methods, god classes, primitive obsession). Unfinished or uncommented code is undocumented technical debt. Every function/class must have a complete Google-style docstring (Args, Returns, Raises, Examples). Every single file must have a module-level docstring at the very top explaining its specific task. If a file lacks this, the code is incomplete.
5. Confidence
State as High / Medium / Low. LLMs cannot calibrate percentages. If Medium or Low, say what
would raise it.
Review Block Format
Append only when running the Full Protocol:
Review: [High/Medium/Low] confidence. Top risk: [specific failure mode].
Assumption check: [key assumption]. Simplicity: [alternative considered].
Hygiene: [Docstrings/smells status].
Rules
- If you cannot defend it, change it. Do not defend the indefensible.
- If it feels uncomfortable, you are doing it right. Comfort means you stopped thinking.
- Never use review theater to hide bad design. A review block does not make bad code good.
- Do not create new requirements. If the user did not ask for tests, do not demand them here. This skill reviews reasoning; it does not expand scope.
- Respect the user's time. If the Core Protocol finds nothing concerning, move on. Perfectionism that produces noise is indistinguishable from carelessness.
Why This Exists
LLMs are prone to "first draft" reasoning—plausible-sounding but shallow.
This skill adds friction without adding noise. The Core Protocol catches most errors silently.
The Full Protocol is reserved for high-stakes contexts where the cost of being wrong exceeds the cost of verbosity.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.