investigate

Files (1)

• SKILL.md

SKILL.md (first lines)

Systematically investigate and diagnose a bug or issue using structured root cause analysis.

Issue: the task/scope the user described when invoking this skill (if none given, ask or infer from context)

## Phase 1: Gather Evidence
- Grep for error messages, stack traces, related keywords in the codebase.
- Check recent git history for related changes. Clamp N to available history so this doesn't fail on repos with fewer than 5 commits: `N=$(( $(git rev-list --count HEAD) - 1 )); [ $N -gt 5 ] && N=5`; if `N` is 0 (single commit), fall back to inspecting `git log --oneline` / `git show`. Then `git log --oneline -$N` and `git diff HEAD~$N`.
- Read log files, error outputs, or console messages if provided.

## Phase 2: Reproduce
1. Identify the reproduction path from gathered evidence.
2. Runtime error → find the entry point (test, script, URL), run it, capture full output.
3. Build error → run the build, capture output.
4. Logic error → write a minimal failing test that demonstrates the bug.
5. Document: **Expected behavior** vs **Actual behavior**.

## Phase 3: Root Cause Analysis
Apply the **5 Whys**:
```
Why did [symptom] happen? → Because [cause 1]
  → Why? Because [cause 2] → ... → Because [root cause]
```
Identify: **Root cause**, **Contributing factors**, **Blast radius** (what else the same root cause affects).

## Phase 4: Fix
1. Implement the fix targeting the root cause (not symptoms).
2. If it touches multiple files, apply in dependency order.
3. Run the Phase 2 reproduction → verify it passes.
4. Run the full test suite → verify no regressions.

## Phase 5: Prevent
1. If no test existed for this case, write one.
2. Check for similar patterns elsewhere: `grep -rn "similar_pattern"`.
3. If systemic, suggest a lint rule or architectural change.

## Phase 6: Report
```
## Investigation Report
### Issue
[one-line description]
### Reproduction
[steps]
### Root Cause
[5 Whys result]
### Fix Applied
- [file:line] — [what changed and why]
### Tests Added
- [test file] — [what it covers]
### Prevention
- [recommendations]
```

## Rules
- NEVER guess. Every conclusion must be backed by evidence (log output, grep result, test failure).
- Reproduce FIRST, then diagnose. No fix without reproduction.
- Fix the root cause, not the symptom.
- Always add a test that would have caught this bug.
- If you can't reproduce, say so clearly and list what you tried.

From Hbin77/codex-kit, MIT.

More from Hbin77/codex-kit