# diagnosing-root-causes

The diagnosing-root-causes skill traces bugs, regressions, and CI/CD failures from supplied evidence, then produces a reviewed root-cause report. Use it when a problem report needs investigation rather than guesswork.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 122 installs · ★ 3 repo stars
- Author: b-mendoza
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/b-mendoza/agent-skills/tree/HEAD/skills/diagnosing-root-causes/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/diagnosing-root-causes

## What it does

Give the skill an issue description and materials such as logs, repository paths, CI output, or a commit range. It classifies the report, asks for clarification when needed, then routes evidence gathering, causal analysis, and report review to three subagents. The final conclusions are tied to supporting evidence.

The workflow follows a finite state machine. Investigation is read-only by default, and the skill never performs Tier C actions, even with approval; approval can produce a handoff for a person instead. That boundary matters if you expect the agent to change code or run a risky operation. When the environment has no subagent tool, the phases run in one context, so the report review is not independent.

Provide the problem and its supporting materials to start. Reproduction steps, environment details, and the issue source can add context. Reports end with `ready`, `blocked`, `needs-validation`, or `escalated`; early stops use `needs-input` or `error`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/diagnosing-root-causes/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/diagnosing-root-causes/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/diagnosing-root-causes/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/diagnosing-root-causes/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install b-mendoza/agent-skills skills/diagnosing-root-causes
```

2. **Manually: put the files in place**
- File: `.github/skills/diagnosing-root-causes/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/b-mendoza/agent-skills --path skills/diagnosing-root-causes
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/diagnosing-root-causes/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/b-mendoza/agent-skills/tree/HEAD/skills/diagnosing-root-causes/SKILL.md

## When to use it
- trace an application crash from logs
- investigate a regression after a code change
- identify why a CI/CD pipeline fails
- check whether a bug report has enough evidence
- prepare a reviewable root-cause report

## Example prompts
- Investigate the application failure using `logs/build-42.txt` and separate confirmed findings from hypotheses.
- Find why the CI/CD pipeline failed after the dependency update using the supplied logs and commit range.
- Review this bug report and ask for the missing details needed to investigate it.

## Similar
- [principle-fix-root-causes](https://affpapa.org/en/nevibecode/skills/principle-fix-root-causes.md) — skill · 10800 installs
- [root-cause-analysis](https://affpapa.org/en/nevibecode/skills/markpitt-root-cause-analysis.md) — skill · 107 installs
- [root-cause-analyst](https://affpapa.org/en/nevibecode/agents/root-cause-analyst.md) — subagent · ★ 23950 repo stars
- [022-root-cause-analysis](https://affpapa.org/en/nevibecode/skills/022-root-cause-analysis.md) — skill · 144 installs
- [why](https://affpapa.org/en/nevibecode/skills/neolabhq-why.md) — skill · 1300 installs
- [rca-debugger](https://affpapa.org/en/nevibecode/agents/rca-debugger.md) — subagent · ★ 880 repo stars

From the same set: [b-mendoza/agent-skills](https://affpapa.org/en/nevibecode/by/b-mendoza/agent-skills.md) — 12 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
