Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nextstage-brasil/skills --skill ns-investigator -a claude-code
Open on GitHub

What 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.ts failing 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-code

2Manually: put the files in place

~/.claude/skills/ns-investigator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ns-investigator/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set20

The whole set →
ns-langgraph-agents ns-langgraph-agents — a skill for Claude Code, Codex, Cursor and other platforms that guides LangGraph.js agent-api development from initial bootstrap through graph-spec sync. CX Codex +1 171installs ns-execution-gitlab-issue ns-execution-gitlab-issue executes GitLab issues end-to-end with worktree isolation, automated status changes, atomic delivery, and merge requests. CX Codex +1 165installs ns-requirements-enricher ns-requirements-enricher turns one GitLab issue or a pasted scope into an implementation brief for a coding agent, grounded in the existing code, with blocking questions kept in chat. CX Codex +1 163installs ns-best-practices ns-best-practices runs security header audits, checks basic accessibility, and reviews UI against Web Interface Guidelines. Generates structured findings with file locations. CX Codex +1 154installs ns-frontend-design ns-frontend-design — a skill for Claude Code, Codex, Cursor and other agents that builds production UI with deliberate typography, hierarchy and motion. Activates on pages, components, dashboards, forms and analytics views. CX Codex +1 153installs ns-autonomous ns-autonomous — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI that takes a local plan or pasted text and runs it autonomously inside an isolated worktree. CX Codex +1 152installs ns-e2e-tests The ns-e2e-tests skill structures Cypress end-to-end work across devices and keeps tests in a separate project. Use it when adding or refactoring specs. CX Codex +1 151installs ns-backend-tests ns-backend-tests — a skill for writing and running PHPUnit unit and integration tests directly in your IDE. Runs only in Docker containers, helping you quickly test a new Laravel project or rewrite existing tests. CX Codex +1 151installs

Project sponsors

Companies that keep this analytics open