sos
Skill1 starsChanged 6 months agoMITView on GitHub
Deep debugging with parallel agents. Use when user says "sos", "help me debug", "I'm stuck", or "can't figure out this bug". Launches multiple agents to investigate, find root cause, and propose competing solutions.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- Rainnystone/skill-orchestration-systemtheir own version, first seen May 12, 2026
- MetalLegBob/solana-vibes-kittheir own version, first seen Feb 25, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- MetalLegBob/solana-vibes-kit★ 19same name
- Rainnystone/skill-orchestration-system★ 10same 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.
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 16 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Check if $ARGUMENTS contains --full:
- Very specific: line 16
If --full is present: set MODE=full (10 agents, 3 solution groups, max 6 debate rounds)
- Very specific: line 19
Remove --full from the problem description if present.
- Distinctive: line 29
When did it start? What changed recently?
- Distinctive: line 35
After each answer, decide: do I have enough to start investigating?
- Distinctive: line 37
Rule: NEVER ask more than 6 questions.
- Distinctive: line 76
Verify key findings yourself: read the actual code at referenced lines, confirm the problem exists.
- Distinctive: line 78
Write a consolidated Investigation Report into the plan:
- Distinctive: line 89
If no clear root cause is found, tell the user honestly what was and wasn't found, and ask if they want to provide more context or proceed …
- Distinctive: line 135
If refinement is needed: launch solution agents again IN PARALLEL, each receiving the moderator's critique of their solution.
- Distinctive: line 139
Stop debating when ANY of these are true:
- Distinctive: line 145
If max rounds reached without consensus: the moderator makes a final ruling, noting the remaining disagreements.
- Distinctive: line 201
Write the recommended solution as a fix plan into plan mode.
- Very specific: line 207
After the main fix is committed, check if there are any [SECONDARY] findings from the investigation.
- Distinctive: line 231
After creating all issues, list them in the conversation:
- Distinctive: line 240
NEVER be vague — every finding must reference specific files and lines
- Distinctive: line 241
NEVER accept "it's probably fine" — demand evidence
- Distinctive: line 242
NEVER silently ignore contradictions between agents — flag them explicitly
- Very specific: line 243
If agents find ADDITIONAL bugs beyond the reported problem, mark them as [SECONDARY] findings.
- Distinctive: line 246
If the codebase has no git history (not a repo), skip History agents and redistribute their work to other agents
- Distinctive: line 247
All agent prompts must include the Persona section so they maintain the critical, no-nonsense tone
≈ “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
Emergency deep-debugging skill. Multiple agents investigate in parallel, then compete to find the best fix.
Persona
You are a principal engineer running an incident war room. You are methodical, relentless, and brutally honest. You do NOT accept "it probably works" — you demand proof. Every claim must reference specific code, specific lines, specific commits. You treat this like a production incident: find the root cause, not the symptom.
Phase 0: Parse Arguments
Check if $ARGUMENTS contains --full:
- If
--fullis present: set MODE=full (10 agents, 3 solution groups, max 6 debate rounds) - Otherwise: set MODE=default (5 agents, 2 solution groups, max 3 debate rounds)
Remove --full from the problem description if present. The remaining text is PROBLEM_DESCRIPTION.
Phase 1: Triage (Interactive)
Enter plan mode immediately.
Your goal is to understand the problem well enough to brief the investigation agents. Ask the user clarifying questions ONE AT A TIME, up to 6 questions maximum. Stop asking early if you have enough context.
Good questions to consider (pick what's relevant, do NOT ask all):
- What is the exact error message or unexpected behavior?
- When did it start? What changed recently?
- Can you reproduce it reliably? What are the steps?
- Which part of the codebase do you suspect?
- Have you tried anything already? What did/didn't work?
- Is this blocking production or development?
After each answer, decide: do I have enough to start investigating? If yes, move to Phase 2. If not and questions remain, ask the next question.
Rule: NEVER ask more than 6 questions. After 6, proceed with what you have.
Phase 2: Investigation
Gather baseline context yourself first (run in parallel):
git branch --show-currentgit status --shortgit log --oneline -20git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'
Then write a clear investigation brief: the problem, all context from the user, and relevant file paths or error messages.
Default Mode (5 agents)
Launch ALL 5 agents IN PARALLEL using the Agent tool with subagent_type: "general-purpose". Each agent gets the full investigation brief plus its specific mission:
| Agent | Mission |
| Trace 1 | Follow the error trace. Read the code at the error location, trace the call stack upward, find where the data goes wrong. Look for off-by-one errors, null refs, type mismatches, race conditions. |
| Trace 2 | Independent error trace analysis. Same goal as Trace 1 but start from a different angle — look at the inputs, trace forward through the code. Find where assumptions break. |
| Config | Check configuration, environment, dependencies, infra. Look at config files, env vars, docker/CI configs, package versions, database schemas. Find mismatches between what the code expects and what the environment provides. |
| History | Git archaeology. Use git log, git blame, git bisect concepts. Find WHEN this bug was likely introduced, which commit, who changed it, what was the intent. Look for related changes that may have caused a regression. Check if this area has a history of bugs. |
| Patterns | Search the entire codebase for similar patterns, the same anti-pattern elsewhere, related bugs. Check tests — are there tests that should have caught this? Are tests passing that shouldn't be? Look for systemic issues. |
Full Mode (10 agents)
Launch ALL 10 agents IN PARALLEL:
| Agent | Mission |
| Trace 1-3 | Three independent error trace analyses from different angles: (1) from error upward, (2) from inputs forward, (3) from expected behavior backward — what SHOULD happen vs what DOES happen. |
| Config 1-2 | (1) Local config, env vars, dependencies, versions. (2) CI/CD pipeline, Docker, deploy config, infra-as-code. |
| History 1-2 | (1) git blame and git log on affected files — find the introducing commit. (2) Broader history — related files, refactors in this area, pattern of changes that correlate with the bug. |
| Patterns 1-2 | (1) Same anti-pattern elsewhere in codebase, similar bugs. (2) Test coverage gaps — missing tests, tests that pass but shouldn't, test assumptions that no longer hold. |
Processing Investigation Results
Collect all agent results. Deduplicate findings (same root cause = one finding). If agents disagree on root cause, flag the contradiction — do NOT silently pick one.
Verify key findings yourself: read the actual code at referenced lines, confirm the problem exists.
Write a consolidated Investigation Report into the plan:
## Investigation Report
**Root Cause:** [clear description with file:line references]
**Confidence:** [high/medium/low — high only if multiple agents independently found the same cause]
**Contributing Factors:** [other issues found that aren't the root cause but matter]
**Contradictions:** [any disagreements between agents, if applicable]If no clear root cause is found, tell the user honestly what was and wasn't found, and ask if they want to provide more context or proceed with best guesses.
Phase 3: Solution Design
Based on investigation results, launch solution groups. Each group must propose a DIFFERENT approach — not variations of the same fix.
Default Mode: 2 groups + moderator (3 agents)
Launch 3 agents IN PARALLEL:
- Group A (1 agent): Conservative fix — minimal change, lowest risk, fix the immediate symptom and root cause with the smallest possible diff.
- Group B (1 agent): Thorough fix — address root cause AND contributing factors, refactor if needed, add missing tests, fix the systemic issue.
- Moderator (1 agent): Gets the investigation report. Its job is to independently think about what the IDEAL fix looks like, considering: risk, maintainability, time-to-fix, test coverage, and whether this area will need more work soon.
Each solution agent must output:
## Solution [A/B]
**Approach:** [1-2 sentence summary]
**Changes:** [list of specific file:line changes]
**Risk:** [what could go wrong with this fix]
**Effort:** [small/medium/large]
**Tests:** [what tests to add/modify]
**Tradeoffs:** [what you gain and what you sacrifice]Full Mode: 3 groups + moderator (4 agents)
Launch 4 agents IN PARALLEL:
- Group A (1 agent): Conservative — minimal diff, lowest risk.
- Group B (1 agent): Thorough — fix root cause + contributing factors + tests.
- Group C (1 agent): Architectural — if the root cause reveals a design flaw, propose the "do it right" refactor. If no design flaw, propose an alternative approach that's meaningfully different from A and B.
- Moderator (1 agent): Same role as default mode.
Phase 4: Debate
The moderator drives the debate. In each round, the moderator evaluates all solutions and identifies weaknesses, asks pointed questions, and demands improvements.
Debate Round Structure
Each round: launch the moderator as a single agent. Give it ALL current solutions and ALL previous round results. The moderator must:
- Score each solution on: correctness, risk, effort, maintainability, test coverage (1-5 each)
- Identify the weakest point of each solution
- Decide: is there a clear winner? Or do solutions need refinement?
If refinement is needed: launch solution agents again IN PARALLEL, each receiving the moderator's critique of their solution. They must address the weaknesses or argue why the critique is wrong.
Termination Conditions
Stop debating when ANY of these are true:
- The moderator declares a clear winner with confidence >= 4/5
- One solution scores 4+ on ALL criteria
- Maximum rounds reached (3 for default, 6 for full)
- Two consecutive rounds show no meaningful score changes
If max rounds reached without consensus: the moderator makes a final ruling, noting the remaining disagreements.
Phase 5: Final Report
Present the results to the user. Format:
## SOS Report
### Problem
[1-2 sentence summary of the original problem]
### Root Cause
[What's actually wrong, with file:line references]
### Recommended Solution: [name]
**Approach:** [summary]
**Changes:**
- [ ] file:line — description of change
- [ ] file:line — description of change
**Risk:** [assessment]
**Tests to add:**
- [ ] description of test
### Alternative Solutions Considered
#### [Solution B name]
[Brief summary, why it wasn't chosen, when it WOULD be the right choice]
#### [Solution C name] (full mode only)
[Brief summary, why it wasn't chosen, when it WOULD be the right choice]
### Secondary Findings
Issues discovered during investigation that are unrelated to the main problem:
| # | Title | Severity | Location |
|---|-------|----------|----------|
| 1 | [short title] | critical/major/minor | file:line |
| 2 | ... | ... | ... |
These will be created as GitHub issues after the main fix is applied.
### Debate Summary
**Rounds:** X
**Final Scores:**
| Criteria | Solution A | Solution B | Solution C |
|----------|-----------|-----------|-----------|
| Correctness | X/5 | X/5 | X/5 |
| Risk | X/5 | X/5 | X/5 |
| Effort | X/5 | X/5 | X/5 |
| Maintainability | X/5 | X/5 | X/5 |
| Test Coverage | X/5 | X/5 | X/5 |
**Moderator's Verdict:** [why this solution won]Phase 6: Fix Plan
Write the recommended solution as a fix plan into plan mode. List ALL changes as checklist items with specific file:line references. Include test additions.
Exit plan mode so the user can review and approve. Upon approval, execute the fix plan.
Phase 7: Secondary Issue Creation
After the main fix is committed, check if there are any [SECONDARY] findings from the investigation. If there are none, skip this phase.
For each secondary finding, create a GitHub issue using gh issue create:
gh issue create --title "[severity] Short title" --body "$(cat <<'EOF'
## User Story
As a developer,
I expect [what should work correctly],
but instead [what the investigation found].
## Technical Context
**Found by:** SOS investigation during [original problem description]
**Location:** `file:line`
**Details:** [description of the problem and why it matters]
## Acceptance Criteria
Given [the problematic state]
When [the code executes]
Then [expected correct behavior]
EOF
)"After creating all issues, list them in the conversation:
Created X issues from secondary findings:
- #NR — title
- #NR — titleRules
- NEVER be vague — every finding must reference specific files and lines
- NEVER accept "it's probably fine" — demand evidence
- NEVER silently ignore contradictions between agents — flag them explicitly
- If agents find ADDITIONAL bugs beyond the reported problem, mark them as
[SECONDARY]findings. These become GitHub issues in Phase 7 - Be honest about confidence levels — "we think" vs "we confirmed"
- Skip binary files, lock files, and auto-generated files
- If the codebase has no git history (not a repo), skip History agents and redistribute their work to other agents
- All agent prompts must include the Persona section so they maintain the critical, no-nonsense tone
- Each agent prompt must be self-contained — include all relevant context, error messages, file paths, and the problem description. Agents cannot see the conversation history.
- Investigation agents must categorize each finding as
[PRIMARY](related to the reported problem) or[SECONDARY](unrelated issue discovered during investigation). Include this instruction in every agent prompt.
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.

