mcpField
N
ns-code-investigator

ns-code-investigator

github.com/nextstage-brasilDevelopment054 installsUpdated 6d ago
Repository

About ns-code-investigator

ns-code-investigator is a skill for evidence-based diagnosis of code failures and proposing minimal fixes, without implementing them. It is intended for requests to explain bugs, stack traces, or CI failures and returns a structured analysis with validation steps.

Key features

  1. 01Analyzes logs, traces, and test output
  2. 02Loads applicable project rules
  3. 03Tests hypotheses against repository evidence
  4. 04Proposes a minimal safe fix
  5. 05Provides validation and prevention steps

Use cases

  1. 01Diagnosing a CI failure without requesting code changes
  2. 02Tracing the cause of a stack trace
  3. 03Investigating an unexplained bug before implementation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nextstage-brasil/skills --skill ns-code-investigator

After installing, type/ns-code-investigatorin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

evals/
evals.json
references/
entry-triggers.md
rca-template.md

Details

From the project README

Code Investigator

Root-cause diagnosis and minimal fix proposal — not implementation. Entry priority 4. Full routing: ../ns-harness/references/code-skill-routing.md.

Harness discovery

See ../ns-harness/references/harness-discovery.md. Load rules from {harness_root}/rules/*.md. Read architecture-rules.md first. Legacy: .cursor/rules/*.mdc only if {harness_root} is absent.

Routing (read first)

Entry (priority 4)

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.

Do not enter when the user asks to implement or fix code → ns-code-coder (priority 5). 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-code-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

FileWhen
references/rca-template.mdOptional structured RCA document
references/entry-triggers.mdPriority 4 entry phrases vs coder
../ns-harness/references/code-skill-routing.mdEntry 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

Comments

Markdown supported