mcpField
C
code-investigator

code-investigator

github.com/nextstage-brasilDevelopment046 installsUpdated 5d ago
Repository

About code-investigator

Code Investigator is a skill for diagnosing software failures and identifying root causes. It emphasizes evidence, minimal safe fixes, validation steps, and a structured account of confirmed facts and hypotheses.

Key features

  1. 01Inspect logs, code, and test output
  2. 02Load applicable project rules
  3. 03Trace causes with evidence
  4. 04Recommend minimal safe fixes
  5. 05Provide validation steps

Use cases

  1. 01Diagnosing a failing test
  2. 02Tracing an error from logs to code
  3. 03Planning and validating a focused fix

Install

Copy the command and run it in a terminal.

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

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

Bundled filesevals/evals.jsonreferences/rca-template.md

Details

From the project README

Code Investigator

Find root cause, explain failure clearly, propose minimal safe fix with validation steps.

Harness discovery

See ../nextstage-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.

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
code-reviewerAfter fix, before merge

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