devils-advocate-loop
Skill0 starsChanged 6 months agoMITView on GitHub
Iterates devil's-advocate review on a plan or spec until a round finds no real bugs. Each round: surface concerns, apply fixes inline, commit, repeat. Min 2 rounds, max 5. Stops when only nits/cosmetic issues remain. Use when refining a written artifact before execution — not for one-shot review (use /devils-advocate for that).
1 other project uses a version of this.
Adopted by
Most recently taken up by
- rawphp/skillstheir own version, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- rawphp/skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- anti-ai-tellsSkill
- contract-auditSkill
- karpathy-guidelinesSkill
- plantuml-diagramsSkill
- spec-to-shipSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 9 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
If the artifact is a spec that someone else will implement — a subagent, a teammate, a local model — run contract-audit first and require …
- Distinctive: line 30
Do not absorb its checklist into your rounds.
- Distinctive: line 35
Maximum 5 rounds: After 5, stop regardless. Diminishing returns are real.
- Distinctive: line 39
Don't manufacture concerns: If a round legitimately finds nothing real, declare it clean and stop.
- Distinctive: line 60
If any one of the three fails, fix it inline.
- Distinctive: line 76
Use the bundled references (relative to this skill's directory):
- Distinctive: line 129
If you're working in a worktree, the branch is whatever the user is currently on — don't switch.
- Distinctive: line 139
After the last round, output a single concise summary (≤ 400 words):
- Distinctive: line 155
Manufacturing concerns to look thorough: If you find <2 real issues in a round and you're past the minimum, that's the signal to stop.
- Distinctive: line 161
Looping on the same artifact past 5 rounds: If you're still finding real issues at round 5, the artifact needs a rewrite, not more polish.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Devil's Advocate Loop
You are running iterative devil's-advocate review on a written artifact (plan, spec, design doc) until it's stable. Each round you wear two hats: the reviewer (challenge it) and the implementer (apply fixes). Between rounds you commit the diff. You stop when a round finds nothing real left to fix.
Announce at start: "I'm using the devils-advocate-loop skill — running rounds until a clean pass."
When to use this skill
- A plan or spec is written and you want to harden it before execution.
- You've already done one DA round and want to keep going systematically until clean.
- Cross-phase rollouts where each phase artifact deserves multiple passes before subagents execute it.
When NOT to use this skill
- One-shot code review of an already-implemented PR — use
/devils-advocateinstead and stop after one report. - The artifact you'd be reviewing doesn't exist yet — write it first, then loop.
- The target is already merged / shipped — fixing it requires a different workflow (debug, PR).
Prerequisite: contract completeness
If the artifact is a spec that someone else will implement — a subagent, a teammate, a local model — run contract-audit first and require it to pass before you start looping.
This skill is generative: its frameworks reason outward from what is written, so an omission gives them nothing to seed on. Combined with the 7-concern budget and honest severity ranking, completeness gaps ("this data structure has no field list") reliably lose their slot to consequence-heavy risks — and then turn out to have been the fatal defect. contract-audit is enumerative and catches exactly what this skill structurally cannot. Implementable first, then right.
Do not absorb its checklist into your rounds. Two different jobs.
Core rules
- Minimum 2 rounds. Even if round 1 finds nothing, do round 2 — the framework rewards a second look.
- Maximum 5 rounds. After 5, stop regardless. Diminishing returns are real.
- Stop earlier when a round finds no real bugs. Critical + High + actionable-Medium issues are "real bugs." Low / cosmetic / nitpick issues are not — they may be noted but do not justify another round.
- Fix what you find. Unlike standalone
/devils-advocate, this skill applies the fixes inline. Read the file, Edit it, commit the result. - One commit per round with message
docs(plan): DA round N — <one-line summary>(ordocs(spec): DA round N — ...etc., matching what's being fixed). - Don't manufacture concerns. If a round legitimately finds nothing real, declare it clean and stop. Performative thoroughness is a failure mode, not a success.
Escalation mode (optional — off by default)
Standalone, this skill fixes every real issue inline. Some callers (e.g. spec-to-ship) instead need it to escalate the small subset of issues it cannot responsibly resolve alone, so a human decides before the work continues. Apply this section only when a caller enables escalation mode. When off, fix everything inline as normal.
Default is fix-inline. Escalation is the rare exception, not a half-and-half sort. A typical round escalates zero, one, or occasionally two findings and fixes the rest. If you find yourself escalating most of your findings, you are doing it wrong — re-read this section and re-sort.
Fix inline — do NOT escalate — anything you can resolve with a conventional, low-regret default, even when the artifact is silent on it. These are under-specified, not undecidable:
- missing authentication/authorisation, input validation, error responses, status codes
- absent batch limits, pagination, timeouts, idempotency, retries
- unspecified audit-log fields, logging, observability
- an internal contradiction that has one obviously-correct resolution
Pick the standard answer, apply it, and note the assumption in the commit message. None of these are escalations.
Escalate ONLY when all three hold:
- two reasonable people would implement materially different behaviour, and
- the choice is hard to reverse or user-, business-, or legally-visible (data-loss policy, security posture, a breaking change, money, compliance, core product UX), and
- you cannot pick correctly from the artifact, the codebase, and conventional best practice.
If any one of the three fails, fix it inline.
Never chain escalations. "B depends on the unresolved A, so B escalates too" is wrong. Escalate A only; fix B inline against A's most-likely resolution and note the assumption. One blocking decision does not make its downstream details blocking.
The escalation test: state the decision as a question with two or more concrete options that a non-engineer stakeholder would actually have an opinion on. If you can't frame it that way, it isn't an escalation — fix it inline.
Per-round process
For each round (round numbers are 1-indexed counting from your first round; honour any prior rounds the user mentions):
1. Steel-man (one or two sentences)
State briefly what the artifact gets right. If you can't articulate this, your review is probably off-base — read the artifact again before continuing.
2. Apply the questioning frameworks
Use the bundled references (relative to this skill's directory):
references/questioning-frameworks.md— pre-mortem, inversion, Socratic probing, Six Thinking Hats, Five Whysreferences/blind-spots.md— security, scalability, data lifecycle, integration points, failure modes, concurrency, env gaps, observability, deployment, edge cases, multi-tenancyreferences/ai-blind-spots.md— happy path bias, scope acceptance, confidence without correctness, pattern attraction, reactive patching, context rot, library hallucination, security as afterthought, over-abstraction
Load only the references you need; don't dump them into context unnecessarily.
3. Surface up to 7 concerns, ranked by severity
Format each concern:
Concern: <one-line summary>
Severity: Critical | High | Medium | Low
Framework: <which framework surfaced this>
What I see:
<specific issue with file:line references where possible>
Why it matters:
<consequence if not fixed>
What to do:
<specific, actionable fix>- Critical: data loss, security breach, will not work at all
- High: significant user impact, real technical correctness issue, blocks downstream work
- Medium: worth fixing but won't block shipping; quality / clarity / robustness issues
- Low: cosmetic, style, nice-to-have
Honest severity matters. Don't inflate.
4. Apply fixes
For every Critical + High + actionable-Medium concern:
- Edit the file with the fix
- Where the fix is a structural change (e.g. "split this into three components"), describe what you did concretely
If escalation mode is enabled (see the Escalation mode section), first apply its triple-AND test to each concern: escalate the rare item that genuinely needs a human decision, and fix the rest inline as usual. Default to fix-inline.
You may also surface Low issues but do not fix them — note them in the round's report for the user's awareness.
5. Commit
Single commit at the end of the round. Stage the modified artifact(s) only — don't sweep in unrelated changes.
git add <files modified during this round>
git commit -m "docs(plan): DA round N — <one-line summary of what got fixed>"If you're working in a worktree, the branch is whatever the user is currently on — don't switch.
6. Decide: continue or stop
- If this round found Critical / High / actionable-Medium issues → continue to the next round, up to the max of 5.
- If this round found only Low / cosmetic issues OR found nothing → stop provided you have done at least 2 rounds. If this was round 1, do one more round to confirm.
- After 5 rounds → stop regardless. Note any remaining Low issues in the final report.
Final report
After the last round, output a single concise summary (≤ 400 words):
- Rounds completed: N
- Stopped because: (clean round / hit max)
- Per-round summary table:
| Round | Critical | High | Medium | Low | Commit |
| 1 | 1 | 2 | 1 | 0 | abc123 |
| ... |
- Remaining Low / unfixed notes (if any): bullet list
- Recommendation: ready for execution / one more round next session / etc.
Honest pitfalls to avoid
- Manufacturing concerns to look thorough. If you find <2 real issues in a round and you're past the minimum, that's the signal to stop. Don't keep going.
- Bundling cosmetic fixes with real fixes. Each round should focus on the real bugs; cosmetic cleanup can be separate work.
- Commit hygiene drift. Each round = one commit. Don't fix in dribbles.
- Ignoring the steel-man step. Skipping it makes the round noisy because you're not anchored on what's right.
- Not reading the artifact between rounds. Fixes in round N may have introduced new issues — re-read each time. Don't review from memory.
- Treating embedded code as illustration. A snippet, test body, example URL or sample payload inside the artifact is part of the artifact, not decoration on the prose. Five rounds can read a normative mapping table, agree with the table, and never notice that the example directly below it violates it — because agreeing with prose feels like reviewing. You are generative and will not catch this by argument; if
contract-auditC9 hasn't run on this artifact, say so in the final report rather than checking the literals badly here. - Looping on the same artifact past 5 rounds. If you're still finding real issues at round 5, the artifact needs a rewrite, not more polish.
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.

