anti-spiral
Skill24 starsChanged 2 months agoMITView on GitHub
Stagnation detector + persona switcher. Triggers when the same file is edited 3+ times for the same issue, the same hypothesis fails 3+ times in mcp_think, the auditor returns BLOCK twice in a row, or test pass rate plateaus across attempts. Detects 4 stagnation patterns (Spinning, Oscillation, NoDrift, DiminishingReturns) and switches to one of 5 personas (Hacker, Researcher, Simplifier, Architect, Contrarian) to break the loop.
In this repository43 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- anti-spiralSkill
- auto-orchestrateSkill
- b-plan-runnerSkill
- cookSkill
- dashboard-handoffSkill
- grillSkill
- idea-intakeSkill
- impact-checkSkill
- improvement-conjectureSkill
- incremental-evalSkill
- operatorSkill
- oracleSkill
- orchestrateSkill
- paper-to-planSkill
- pdfSkill
- planning-workflowSkill
- prompt-transformSkill
- rag-toolsSkill
- seeSkill
- sequential-opus-orchestratorSkill
- spec-evalSkill
- teachSkill
- auto-orchestrateSkill
- b-plan-runnerSkill
- cookSkill
- dashboard-handoffSkill
- grillSkill
- idea-intakeSkill
- impact-checkSkill
- improvement-conjectureSkill
- incremental-evalSkill
- operatorSkill
- oracleSkill
- orchestrateSkill
- paper-to-planSkill
- pdfSkill
- planning-workflowSkill
- prompt-transformSkill
- seeSkill
- sequential-opus-orchestratorSkill
- teachSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 6 are distinctive, and 1 is 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.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
When triggered, EXECUTE THIS PROTOCOL — do not freestyle:
- Distinctive: line 22
Stop the current line of attempt.
- Distinctive: line 23
Call mcp_think(step_type="status", content="anti-spiral triggered: <which-pattern>", topic="anti-spiral") to log the pivot.
- Distinctive: line 26
Read the last 5 mcp_think entries on the active topic.
- Distinctive: line 68
If user rejects: ask which persona they prefer or whether to halt and review with them directly.
- Distinctive: line 70
If user approves: proceed with new attempt.
- Very specific: line 76
Every persona switch writes a row to workflow/sessions/{session_id}/anti-spiral.log: <timestamp> | <pattern> | <from-persona> | …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Anti-spiral protocol
Trigger conditions (any one):
- Spinning: same file edited >=3 times for the same BLOCK / error message / fix attempt.
- Oscillation: code reverted then re-added then reverted (any 2-cycle within a phase).
- NoDrift: >=15 minutes of effort without any test moving from FAIL to PASS or any BLOCK clearing.
- DiminishingReturns: test pass rate plateaus or decreases across 2+ EXECUTING -> AUDITING cycles.
When triggered, EXECUTE THIS PROTOCOL — do not freestyle:
STEP 1 — STOP
Stop the current line of attempt. Do not write more code in the current direction.
Call mcp_think(step_type="status", content="anti-spiral triggered: <which-pattern>", topic="anti-spiral") to log the pivot.
STEP 2 — DIAGNOSE Read the last 5 mcp_think entries on the active topic. Look for:
- Repeated hypotheses (same observation/hypothesis over multiple steps): Spinning.
- Hypotheses that contradict each other across steps: Oscillation.
- Hypotheses with no plan_action that improved verify outcome: NoDrift.
- Diminishing test-pass deltas: DiminishingReturns.
Pick the dominant pattern. (If two are tied, pick Spinning > Oscillation > NoDrift > DiminishingReturns.)
STEP 3 — PERSONA SWITCH Map pattern to persona:
Spinning -> SIMPLIFIER Oscillation -> ARCHITECT NoDrift -> RESEARCHER DiminishingReturns -> CONTRARIAN
(Default Hacker persona is what the main model is doing now. Hacker is the one we are pivoting AWAY from.)
Persona definitions — use as the system prompt frame for the next implementation attempt:
HACKER (default — what we already are) "Get it working. Match the failing test. Move fast. Standard CLAUDE.md rules apply."
SIMPLIFIER "Delete code. The current path is too complex. Re-approach with the smallest possible diff that satisfies the test. If the current implementation is >50 LOC and broken, candidate for total rewrite from scratch with <30 LOC. Question every abstraction; question every helper. Prefer one inline function over a class hierarchy. Pseudo-code first, then code."
ARCHITECT "Step back. The bug is structural, not local. Read the surrounding subsystem. Re-plan at a higher level. Identify which contract is being violated; identify what the right boundary is. Often: a function in the wrong module; a state machine missing a transition; an interface that should be split. Output a re-design proposal first, then implement after user approval."
RESEARCHER "Look outside the codebase. Search for prior art: WebSearch, paper-ingestor, similar projects in elai.map. Read the relevant ELAI spec sections (docs/specs/guide/steps/phase-*.txt). Question: 'Has someone solved this exact problem? Where? How?' If we are using a library, READ ITS SOURCE. If a paper is cited, ingest it via paper-ingestor. Only after grounding, attempt fix."
CONTRARIAN "Challenge the plan's premise. The B-N file or the test we are trying to pass might be wrong. Generate the OPPOSITE hypothesis to whatever the current direction is. If we believe X causes Y, examine if Y causes X. If we believe a fix needs to add code, examine if it needs to delete code. If the test asserts a value, question whether the asserted value is correct. Output: 'The plan assumes X. The test assumes Y. What if X is wrong?'"
STEP 4 — PROMPT REGENERATION
Spawn prompt-engineer agent with the new persona frame prepended to the task description:
"PERSONA: <persona name>. <persona definition above>. Original task: <original task>."
Pass session_id and the current B-N file. The prompt-engineer respects the persona instruction.
Show the new prompt to user. Ask: "Pivot to <persona> persona. Approved?" (CLAUDE.md hard rule: no unsolicited approach changes — user must approve each persona switch.)
If user rejects: ask which persona they prefer or whether to halt and review with them directly.
If user approves: proceed with new attempt. Reset mcp_think topic via mcp_think_reset(topic="anti-spiral") and start fresh.
STEP 5 — TIMEOUT Cap: max 2 persona switches per phase. If 2 switches don't resolve, stop and write workflow/sessions/{session_id}/SESSION_HANDOFF.md with a "Stuck" section enumerating: original direction, what each persona attempted, why none worked. Surface to user: "Phase blocked by sustained anti-spiral after 2 persona switches. Recommend: human review of B-N feasibility or scope reduction."
LOGGING
Every persona switch writes a row to workflow/sessions/{session_id}/anti-spiral.log:
<timestamp> | <pattern> | <from-persona> | <to-persona> | <reason-1-line>
EXAMPLE Symptom: same fn signature edited 4 times in 20 minutes; same error E0277 appears each time. Pattern: Spinning (same edit, same error). Pivot: SIMPLIFIER. Prompt: "The current fix is too complex. Delete the helper function we added in the last 4 attempts. Inline its logic. Match the test in <30 LOC."
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.

