agentleFS
Sign inStart free
SethGammonSethGammon/Armory/systematic-debugging/SKILL.md

systematic-debugging

Skill19 starsChanged 7 months agoMITView on GitHub

4-phase root cause analysis: observe, hypothesize, verify, fix. Enforces investigation before any code changes. Emergency stop after 2 failed fixes. Prevents shotgun debugging and fix cascades.

We split this skill into the rules it gives an agent

21 rules. 0 are common, 21 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 171 edited versions we read keep these.

  • 21

    Distinctive

    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
  1. Distinctive:

    Read the error message, stack trace, or bug description thoroughly

    line 25
  2. Distinctive:

    If it's a type error: run typecheck and read the full error

    line 27
  3. Distinctive:

    If it's a runtime error: identify the triggering conditions

    line 28
  4. Distinctive:

    If it's a behavioral bug: document expected vs actual behavior

    line 29
  5. Distinctive:

    Add a console.log / diagnostic read / breakpoint

    line 46
  6. Distinctive:

    Check a specific value at a specific point

    line 47
  7. Distinctive:

    DO NOT change any logic yet — only observe

    line 48
  8. Distinctive:

    If none confirmed: formulate new hypotheses with the new information

    line 53
  9. Distinctive:

    CRITICAL: Do not skip this phase. Do not "just try" a fix.

    line 55
  10. Distinctive:

    Document the causal chain: "A calls B with X, B assumes X > 0, but A passes -1 when {condition}"

    line 64
  11. Distinctive:

    Check for related occurrences:

    line 67
  12. Distinctive:

    Write a failing test case that reproduces the bug (if test framework exists)

    line 76
  13. Distinctive:

    Test case now passes

    line 79
  14. Distinctive:

    No regressions in related functionality

    line 81
  15. Distinctive:

    If the root cause analysis revealed related occurrences, fix those too

    line 82
  16. Distinctive:

    Do not try a third guess. The root cause analysis was wrong.

    line 88
  17. Distinctive:

    Ask the user for more context about the system's intended behavior

    line 90
  18. Distinctive:

    Check if there's a higher-level architectural issue

    line 91
  19. Distinctive:

    If related occurrences were found, they were fixed or documented

    line 108
  20. Distinctive:

    Bug is intermittent: Document the triggering conditions as precisely as possible.

    line 112
  21. Distinctive:

    Error is in a dependency or generated file: Document the root cause but do not modify the dependency.

    line 118

“Common” is measured: kept by at least 6 in 10 of the 171 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/systematic-debugging — Root Cause Before Fix

Identity

/systematic-debugging enforces one rule: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

Most debugging failures come from guessing. This skill forces a structured approach: observe → hypothesize → verify → fix. The fix is always the last step, never the first.

Protocol

Phase 1: OBSERVATION & REPRODUCTION

  1. Read the error message, stack trace, or bug description thoroughly
  2. Reproduce the issue:
    • If it's a type error: run typecheck and read the full error
    • If it's a runtime error: identify the triggering conditions
    • If it's a behavioral bug: document expected vs actual behavior
  3. Isolate the failing component/function:
    • What file? What function? What line?
    • What are the inputs when it fails?
    • Does it fail consistently or intermittently?

Output: A clear problem statement: "{Component} does {X} when it should do {Y}, triggered by {condition}"

Phase 2: HYPOTHESIS & VERIFICATION

  1. Formulate up to 3 hypotheses for WHY the bug exists:
    • H1: {most likely cause} — because {evidence}
    • H2: {second candidate} — because {evidence}
    • H3: {third candidate} — because {evidence}
  2. For each hypothesis, define a verification step:
    • Add a console.log / diagnostic read / breakpoint
    • Check a specific value at a specific point
    • DO NOT change any logic yet — only observe
  3. Run the verification:
    • Which hypothesis was confirmed?
    • Which were eliminated?
    • If none confirmed: formulate new hypotheses with the new information

CRITICAL: Do not skip this phase. Do not "just try" a fix. Verify first.

Phase 3: ROOT CAUSE ANALYSIS

Once a hypothesis is confirmed:

  1. Explain WHY the bug happens, not just WHERE:
    • Trace the data flow backward from the symptom to the source
    • Identify the specific incorrect assumption or logic error
    • Document the causal chain: "A calls B with X, B assumes X > 0, but A passes -1 when {condition}"
  2. Check for related occurrences:
    • Is this pattern used elsewhere? Could the same bug exist in similar code?
    • Is there a systemic issue (e.g., missing validation at a boundary)?

Output: Root cause statement: "The bug occurs because {cause}. This happens when {trigger}."

Phase 4: IMPLEMENTATION

  1. Write a failing test case that reproduces the bug (if test framework exists)
  2. Apply the minimal fix — change only what's necessary to resolve the root cause
  3. Verify the fix:
    • Test case now passes
    • Typecheck passes
    • No regressions in related functionality
  4. If the root cause analysis revealed related occurrences, fix those too

Emergency Stop Rule

If a fix fails TWICE: STOP.

Do not try a third guess. The root cause analysis was wrong. Either:

  • Go back to Phase 2 with new hypotheses
  • Ask the user for more context about the system's intended behavior
  • Check if there's a higher-level architectural issue

Three failed fixes in a row means you're guessing, not debugging.

What This Skill Prevents

  • Shotgun debugging — changing random things until the error goes away
  • Symptom fixing — patching the output without understanding the cause
  • Fix cascades — one bad fix creating three new bugs
  • Silent regressions — fixing one path while breaking another

Quality Gates

  • A clear problem statement exists before any hypothesis is formed
  • At least one hypothesis was verified (not assumed) before the fix was written
  • The fix addresses the root cause, not just the symptom
  • Typecheck passes after the fix with no new errors
  • If related occurrences were found, they were fixed or documented

Fringe Cases

Bug is intermittent: Document the triggering conditions as precisely as possible. Reproduce it at least once before forming hypotheses. If it can't be reproduced, stop at Phase 1 and ask for more context.

Two fix attempts have already failed: Invoke the Emergency Stop Rule. Return to Phase 2 with new hypotheses. Do not try a third guess without re-reading the relevant code.

No test framework exists: Skip the "write a failing test" step in Phase 4. Verify the fix manually and document how to reproduce the original bug for future reference.

Error is in a dependency or generated file: Document the root cause but do not modify the dependency. Propose a workaround in the consuming code instead.

Exit Protocol

---HANDOFF---
- Bug: {problem statement}
- Root cause: {one-line cause}
- Fix: {what was changed}
- Verified: {typecheck + tests passing}
- Related: {any similar patterns found and fixed}
---

Download now (ZIP)

  • Other versions186 projects use a version of this.

    Word for word · 1

    1. allysgrandiose674/Armory★ 1100% same

    Edited · 2

    1. SethGammon/Citadel★ 92783% same
    2. mayankjain1815-commits/CITADEL★ 483% same

    Wrote their own version · 183

    1. obra/superpowers★ 305ksame name
    2. NousResearch/hermes-agent★ 257ksame name
    3. open-metadata/OpenMetadata★ 16ksame name
    4. jnMetaCode/superpowers-zh★ 8.4ksame name
    5. vudovn/ag-kit★ 8.2ksame name
    6. vudovn/antigravity-kit★ 8.2ksame name
    7. openai/plugins★ 7.4ksame name
    8. ChrisWiles/claude-code-showcase★ 6.1ksame name
    9. farm-fe/farm★ 5.6ksame name
    10. microsoft/FluidFramework★ 5ksame name

    173 more not listed

    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.

  • Used alongsideProjects with it also use chinese-code-review, chinese-commit-conventions and 10 more.

    Other files people use alongside this one.

    Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
    • GEd520Skill

      chinese-code-review

      中文 review 沟通参考——话术模板、分级标注（必须修复/建议修改/仅供参考）、国内团队常见反模式应对。仅在用户显式 /chinese-code-review 时调用，不要根据上下文自动触发。

      Also in 7 projects that use this

    • GEd520Skill

      chinese-commit-conventions

      中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用，不要根据上下文自动触发。

      Also in 7 projects that use this

    • obraSkill

      diagnosing-superpowers

      Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.

      Also in 12 projects that use this

    • mjunaidcaSkill

      building-chatgpt-apps

      Guides creation of ChatGPT Apps with interactive widgets using OpenAI Apps SDK and MCP servers. Use when building ChatGPT custom apps with visual UI components, embedded widgets, or rich interactive experiences. Covers widget architecture, MCP server setup with FastMCP, response metadata, and Developer Mode configuration. NOT when building standard MCP servers without widgets (use building-mcp-servers skill instead).

      Also in 4 projects that use this

    • mjunaidcaSkill

      building-chat-interfaces

      Build AI chat interfaces with custom backends, authentication, and context injection. Use when integrating chat UI with AI agents, adding auth to chat, injecting user/page context, or implementing httpOnly cookie proxies. Covers ChatKitServer, useChatKit, and MCP auth patterns. NOT when building simple chatbots without persistence or custom agent integration.

      Also in 4 projects that use this

    • +2 more from GEd520
    • +5 more from mjunaidca
  • In this repository13 other files it gives its agents.

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free