ns-investigator — Claude Code skill: root-cause diagnosis from errors
The ns-investigator skill for Claude Code reads stack traces, logs and failing tests, identifies the root cause and proposes a minimal fix without implementing it.
Apache-2.0 153 installs updated 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-investigator -a claude-codeWhat ns-investigator does
The skill activates when you need diagnosis without an immediate patch: a broken CI pipeline, a flaky test with no obvious cause, an exception that reappears across runs.
For each problem it follows a defined sequence: reads the logs and stack trace, narrows the affected area (backend, frontend, infra, DB, auth, build, deploy), builds a hypothesis, checks it against code, and returns a structured report. That report contains a quick diagnosis with a confidence level (High / Medium / Low), concrete evidence, a primary hypothesis, a root-cause statement, a fix recommendation with risk notes, and validation steps. Any suggested code is a minimal snippet, not a full-file rewrite. Security issues — auth bypasses, injections, secrets in logs — are flagged explicitly.
The skill depends on ns-harness: project rules are loaded from .nextstage-harness/rules/*.md and the routing table lives at ../../ns-harness/references/code-skill-routing.md. To apply the proposed fix you need ns-coder; ns-investigator deliberately ends at the proposal and does not trigger implementation on its own.
What it helps with
- find the root cause of a CI failure without manually scanning logs
- trace a stack trace back to the exact code area that produced the error
- separate confirmed facts from hypotheses during a debugging session
- get a minimal fix proposal with an explicit list of risks and side effects
- produce validation steps before any change touches the codebase
Example prompts for the agent
- Why is
auth.spec.tsfailing in CI? Walk me through the stack trace - Here is the deploy log — find the root cause and suggest a fix
- Diagnose this error:
TypeError: Cannot read properties of undefined
How to install ns-investigator
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-investigator -a claude-code2Manually: put the files in place
~/.claude/skills/ns-investigator/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ns-investigator/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-investigator -a codex2Manually: put the files in place
.agents/skills/ns-investigator/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-investigator -a cursor2Manually: put the files in place
.cursor/skills/ns-investigator/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-investigator2Manually: put the files in place
.github/skills/ns-investigator/SKILL.md1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-investigator -a gemini-cli2Platform CLI
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-investigatorManually: put the files in place
.devin/skills/ns-investigator/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-investigator -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ns-investigator
How do I install ns-investigator in Claude Code?
Run npx skills add nextstage-brasil/skills --skill ns-investigator -a claude-code. The skill will then be available at ~/.claude/skills/ns-investigator/SKILL.md.
What does ns-investigator do?
It analyses errors, logs, stack traces and failing tests, identifies the root cause, and proposes a minimal fix with validation steps. It does not apply the fix — that is handled by ns-coder after you decide to proceed.
When should I use ns-coder instead of ns-investigator?
Use ns-coder (priority 5) when you already know what to fix and want it implemented. ns-investigator is for the diagnosis step only — when the question is still "why does this break?" rather than "fix it".
Source text
SKILL.md · Apache-2.0
---
name: ns-investigator
description: (NS) Root-cause diagnosis from errors, logs, stack traces, failing tests, or CI — entry priority 4b when the user wants diagnosis WITHOUT implement ("why does X break?"). Use proactively on unclear test/CI failures if they have not asked to fix yet. Do NOT use for implement/fix (ns-coder), product bug reports / screen expected-vs-actual (ns-bug-report-diagnosis), version scope (ns-spec-driven), GitLab ISSUE_URL execution, or pre-merge review (ns-reviewer).
license: Apache-2.0
metadata:
author: nextstage-brasil
version: "1.3"
depends:
- ns-harness
---
# Code Investigator
Root-cause diagnosis and minimal fix **proposal** — not implementation. Entry priority **4b**. Full routing: `../../ns-harness/references/code-skill-routing.md`.
## Session boot
See `../../ns-harness/references/session-boot.md`. Load rules from `.nextstage-harness/rules/*.md`. Read `architecture-rules.md` first. Legacy: `.cursor/rules/*.mdc` only if `.nextstage-harness/` is absent.
## Routing (read first)
### Entry (priority 4b)
Trigger phrases: `references/entry-triggers.md`. Harness priority table: `../../ns-harness/references/code-skill-routing.md`.
Use when the user wants diagnosis only — stack trace, CI fail, obscure bug, "why does X break?" — **without** asking to implement the fix, and **without** a product screen story.
Do **not** enter when the user asks to implement or fix code → `ns-coder` (priority 5). Do **not** enter for a product bug report / expected vs actual on a screen → `ns-bug-report-diagnosis` (priority 4a). Do **not** enter for GitLab `ISSUE_URL` → `ns-execution-gitlab-issue` (priority 1). Do **not** enter for multi-day / version scope → `ns-spec-driven` (priority 2).
### Handoff out
End with root cause + fix proposal to the **user**. Do **not** auto-dispatch implementation.
When the user asks to implement the proposed fix, stop — they re-enter through the host entry router (usually priority 5 → `ns-coder`). There is no direct `I → C` skill handoff; the human gate sits between diagnosis and diff.
## Mission
Answer:
1. What is failing?
2. Where is the error likely located?
3. Why does it happen?
4. What is the smallest safe fix?
5. How to validate the fix?
Be evidence-based. Separate confirmed facts from hypotheses.
## Workflow
1. Read problem, logs, stack trace, test output, or bug description.
2. Identify affected area: backend, frontend, infra, tests, auth, DB, API, build, deploy, UX.
3. Load applicable project rules.
4. In a repo: `git status`, `git diff`, targeted search, safe test/lint commands.
5. Focus on smallest area explaining the failure.
6. Form hypotheses; confirm or reject with evidence.
7. Start immediately — no permission gate.
## Investigation principles
- **Evidence first** — do not guess when code/logs can confirm
- **Minimal safe fix** — no unrelated rewrites
- **Root cause over symptom** — trace behind the visible error
- **Security** — flag auth bypass, injection, secrets in logs
## Required output format
### Quick Diagnosis
- 2–4 line summary
- Confidence: High | Medium | Low
- Affected area
### Evidence Found
Concrete items from error, log, code, diff, or config. State clearly if insufficient.
### Primary Hypothesis
What is wrong, why it produces the observed error, under which conditions.
### Root Cause
Direct statement when confirmed; otherwise `Probable root cause: ...`
### Recommended Fix
What to change, where, why it resolves, risks/side effects.
### Suggested Code
Only when concrete fix is possible — minimal snippet, not whole files.
### How to Validate
Commands, tests, manual steps to confirm fix.
### Prevention
Regression test, dependency pin, guard, logging, documentation.
## Severity (multiple issues)
1. Critical — blocks execution, production, security, data loss
2. High — important flow broken or recurring
3. Medium — limited incorrect behavior
4. Low — robustness/clarity
## References
| File | When |
| ---------------------------- | -------------------------------- |
| `references/rca-template.md` | Optional structured RCA document |
| `references/entry-triggers.md` | Priority 4b entry phrases vs 4a and coder |
| `../../ns-harness/references/code-skill-routing.md` | Entry priority and investigator handoff |
## Constraints
- Do not blame the developer
- Do not invent unchecked files or logs
- Ask minimum missing info only at end if needed
© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills