ns-investigator

Imported from nextstage-brasil/skills (skills/ns-investigator/SKILL.md). Install upstream with npx skills add nextstage-brasil/skills --skill ns-investigator. Copyright stays with the author (Apache-2.0).

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

Constraints

• Do not blame the developer
• Do not invent unchecked files or logs
• Ask minimum missing info only at end if needed