Systematic Investigation
Path convention: Commands below assume cwd is $CLAUDE_PROJECT_DIR (project root). Prefix paths with "$CLAUDE_PROJECT_DIR/" when invoking from subdirectories.
Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
Skill wiring
- Reads memory: canonical
.meowkit/memory/fixes.json and architecture-decisions.json; fall back to matching generated Markdown views only when JSON is absent. See .claude/rules/memory-read-rules.md.
- Writes: a diagnostic report only, under
tasks/reports/**; the hook enforces this path. mk:fix owns remediation and any memory capture after a fix.
Plan-First Gate
Investigation precedes planning for bug fixes:
- Confirm root cause FIRST (Iron Law)
- After root cause confirmed, hand off to
mk:fix. If the remedy affects more than two files, mk:fix requests an approved bug-fix plan using supported plan-creator syntax.
Skip: Investigation itself doesn't need a plan — it produces the input for planning.
When to Use
- User reports errors, bugs, unexpected behavior
- "debug this", "fix this bug", "why is this broken"
- "investigate this error", "root cause analysis"
- Troubleshooting why something stopped working
Process
- Run preamble — load
references/preamble.md and execute the startup bash block
- Collect symptoms — read error messages, stack traces, reproduction steps
- Investigate root cause — load
references/debugging-methodology.md and follow Phase 1-3. For recurring patterns or complex failures, load references/rca-method-selection.md for methodology selection. Load references/rca-anti-patterns.md to avoid common RCA mistakes.
- Check alternatives — test the strongest competing explanation before declaring a root cause.
- Write diagnostic report — save only to
tasks/reports/{timestamp}-investigation-{slug}.md; include the required output contract below.
- Hand off — route confirmed defects to
mk:fix, compile/build failures to mk:build-fix, and unresolved causes back to the user with explicit uncertainty.
- Run shared protocols — load
references/shared-protocols.md for completion status + telemetry
References
Load only when executing the corresponding step — not upfront.
| Reference |
When to load |
Content |
| preamble.md |
Step 1 — skill startup |
Session init, env detection, upgrade check |
| debugging-methodology.md |
Steps 2-4 — investigation |
Evidence collection and hypothesis testing |
| shared-protocols.md |
Step 7 — completion |
AskUserQuestion format, completion status, telemetry, contributor mode |
Specialized Techniques (load based on bug type)
| Bug type |
Load reference |
What it adds |
| Deep stack trace errors |
references/root-cause-tracing.md |
Backward trace: symptom → cause → ROOT CAUSE |
| Server/CI/DB incidents |
references/system-investigation.md |
5-step system investigation methodology |
| CI/CD failures, log correlation |
references/log-analysis.md |
Filter → timeline → pattern → cross-source |
| Performance issues |
references/performance-diagnostics.md |
Quantify → layer isolation → bottleneck |
| Post-fix validation |
references/reporting-standards.md |
Enhanced DEBUG REPORT with timeline + recommendations |
| Test pollution |
Run scripts/find-polluter.sh <file> <test-pattern> |
Bisection to find which test creates unwanted state |
| Defense-in-depth |
See mk:fix/references/prevention-gate.md |
4-layer validation (DRY — shared with mk:fix) |
Constraints
- Diagnostic only — never edit source, tests, configuration, plans, or memory stores
- Report-only writes —
Write is allowed solely for tasks/reports/** and is hook-enforced
- 3-strike rule — if 3 hypotheses fail, STOP and escalate
- Evidence boundary — label each claimed cause as confirmed or uncertain; do not imply remediation completed
Diagnostic Output Contract
Every report includes: symptom, reproduction status, expected versus actual behavior, ranked causes,
confirmed root cause or explicit uncertainty, evidence, and blast radius. Recommendations may name a
next owner but must not implement a fix.
Hooks
- Iron Law enforcement: No fixes without confirmed root cause;
mk:fix is the only remediation owner.
- Report-path hook: the
PreToolUse:Write hook fails closed unless the destination is under tasks/reports/**.
- If root cause cannot be confirmed after 3 hypotheses, escalate to human
- Interaction with mk:careful: If mk:careful is active, debugging commands that touch state will still prompt for confirmation. This is expected — do not bypass.
Gotchas
- Confirming hypothesis without disproving alternatives: Finding evidence FOR a theory doesn't mean it's correct → Actively test at least one alternative hypothesis before concluding
- Log timestamps in wrong timezone: Server logs in UTC, local comparison in local time → Normalize all timestamps to UTC before correlation
Delegation: mk:web-to-markdown
When investigation requires fetching an arbitrary external URL (e.g. a vendor error page,
a remote log endpoint, a referenced issue URL), this skill delegates to
mk:web-to-markdown via the --wtm-accept-risk flag.
- Without
--wtm-accept-risk: mk:web-to-markdown refuses cross-skill delegation.
External URL resolution falls back to Context7 / chub / WebSearch only.
- With
--wtm-accept-risk: delegation proceeds through all security layers
(SSRF guard, injection scanner, DATA boundary, secret scrub). The flag is a conscious
trust-boundary crossing — the caller acknowledges the target URL may contain prompt
injection and that the skill's defenses are best-effort.
- Delegation example:
.claude/skills/.venv/bin/python3 .claude/skills/web-to-markdown/scripts/fetch_as_markdown.py "<url>" --wtm-accept-risk --caller mk:investigate
1---2name: mk-investigate3description: Systematic debugging with root cause investigation. Produces a diagnostic report; mk:fix owns remediation and mk:build-fix owns compile/build failures. Use when asked to "debug this", "fix this bug", "why is this broken", "investigate this error", or "root cause analysis". Proactively suggest when the user reports errors, unexpected behavior, or is troubleshooting why something stopped working. NOT for applying fixes without investigation (see mk:fix); NOT for step-by-step evidence-based reasoning (see mk:sequential-thinking).4---56<!-- Split for progressive disclosure (checklist #11, #14): 497 → ~65 lines -->7<!-- References loaded just-in-time, not all upfront -->89# Systematic Investigation1011> **Path convention:** Commands below assume cwd is `$CLAUDE_PROJECT_DIR` (project root). Prefix paths with `"$CLAUDE_PROJECT_DIR/"` when invoking from subdirectories.1213**Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**1415## Skill wiring1617- **Reads memory:** canonical `.meowkit/memory/fixes.json` and `architecture-decisions.json`; fall back to matching generated Markdown views only when JSON is absent. See `.claude/rules/memory-read-rules.md`.18- **Writes:** a diagnostic report only, under `tasks/reports/**`; the hook enforces this path. `mk:fix` owns remediation and any memory capture after a fix.1920## Plan-First Gate2122Investigation precedes planning for bug fixes:23241. Confirm root cause FIRST (Iron Law)252. After root cause confirmed, hand off to `mk:fix`. If the remedy affects more than two files, `mk:fix` requests an approved bug-fix plan using supported plan-creator syntax.2627Skip: Investigation itself doesn't need a plan — it produces the input for planning.2829## When to Use3031- User reports errors, bugs, unexpected behavior32- "debug this", "fix this bug", "why is this broken"33- "investigate this error", "root cause analysis"34- Troubleshooting why something stopped working3536## Process37381. **Run preamble** — load `references/preamble.md` and execute the startup bash block392. **Collect symptoms** — read error messages, stack traces, reproduction steps403. **Investigate root cause** — load `references/debugging-methodology.md` and follow Phase 1-3. For recurring patterns or complex failures, load `references/rca-method-selection.md` for methodology selection. Load `references/rca-anti-patterns.md` to avoid common RCA mistakes.414. **Check alternatives** — test the strongest competing explanation before declaring a root cause.425. **Write diagnostic report** — save only to `tasks/reports/{timestamp}-investigation-{slug}.md`; include the required output contract below.436. **Hand off** — route confirmed defects to `mk:fix`, compile/build failures to `mk:build-fix`, and unresolved causes back to the user with explicit uncertainty.447. **Run shared protocols** — load `references/shared-protocols.md` for completion status + telemetry4546## References4748Load **only when executing** the corresponding step — not upfront.4950| Reference | When to load | Content |51| --------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------- |52| **[preamble.md](./references/preamble.md)** | Step 1 — skill startup | Session init, env detection, upgrade check |53| **[debugging-methodology.md](./references/debugging-methodology.md)** | Steps 2-4 — investigation | Evidence collection and hypothesis testing |54| **[shared-protocols.md](./references/shared-protocols.md)** | Step 7 — completion | AskUserQuestion format, completion status, telemetry, contributor mode |5556### Specialized Techniques (load based on bug type)5758| Bug type | Load reference | What it adds |59|----------|---------------|-------------|60| Deep stack trace errors | `references/root-cause-tracing.md` | Backward trace: symptom → cause → ROOT CAUSE |61| Server/CI/DB incidents | `references/system-investigation.md` | 5-step system investigation methodology |62| CI/CD failures, log correlation | `references/log-analysis.md` | Filter → timeline → pattern → cross-source |63| Performance issues | `references/performance-diagnostics.md` | Quantify → layer isolation → bottleneck |64| Post-fix validation | `references/reporting-standards.md` | Enhanced DEBUG REPORT with timeline + recommendations |65| Test pollution | Run `scripts/find-polluter.sh <file> <test-pattern>` | Bisection to find which test creates unwanted state |66| Defense-in-depth | See `mk:fix/references/prevention-gate.md` | 4-layer validation (DRY — shared with mk:fix) |6768## Constraints6970- **Diagnostic only** — never edit source, tests, configuration, plans, or memory stores71- **Report-only writes** — `Write` is allowed solely for `tasks/reports/**` and is hook-enforced72- **3-strike rule** — if 3 hypotheses fail, STOP and escalate73- **Evidence boundary** — label each claimed cause as confirmed or uncertain; do not imply remediation completed7475## Diagnostic Output Contract7677Every report includes: symptom, reproduction status, expected versus actual behavior, ranked causes,78confirmed root cause or explicit uncertainty, evidence, and blast radius. Recommendations may name a79next owner but must not implement a fix.8081## Hooks8283- **Iron Law enforcement**: No fixes without confirmed root cause; `mk:fix` is the only remediation owner.84- **Report-path hook**: the `PreToolUse:Write` hook fails closed unless the destination is under `tasks/reports/**`.85- If root cause cannot be confirmed after 3 hypotheses, escalate to human86- **Interaction with mk:careful**: If mk:careful is active, debugging commands that touch state will still prompt for confirmation. This is expected — do not bypass.8788## Gotchas8990- **Confirming hypothesis without disproving alternatives**: Finding evidence FOR a theory doesn't mean it's correct → Actively test at least one alternative hypothesis before concluding91- **Log timestamps in wrong timezone**: Server logs in UTC, local comparison in local time → Normalize all timestamps to UTC before correlation9293## Delegation: `mk:web-to-markdown`9495When investigation requires fetching an arbitrary external URL (e.g. a vendor error page,96a remote log endpoint, a referenced issue URL), this skill delegates to97`mk:web-to-markdown` via the `--wtm-accept-risk` flag.9899- **Without `--wtm-accept-risk`:** `mk:web-to-markdown` refuses cross-skill delegation.100 External URL resolution falls back to Context7 / chub / WebSearch only.101- **With `--wtm-accept-risk`:** delegation proceeds through all security layers102 (SSRF guard, injection scanner, DATA boundary, secret scrub). The flag is a conscious103 trust-boundary crossing — the caller acknowledges the target URL may contain prompt104 injection and that the skill's defenses are best-effort.105- Delegation example: `.claude/skills/.venv/bin/python3 .claude/skills/web-to-markdown/scripts/fetch_as_markdown.py "<url>" --wtm-accept-risk --caller mk:investigate`
ngocsangyem