Systematic Investigation
Path convention: Commands below assume cwd is $(git rev-parse --show-toplevel) (project root). Prefix paths with "$(git rev-parse --show-toplevel)/" 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 AGENTS.md (Memory).
- 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 |
stop and ask the user in chat 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:
.agents/skills/.venv/bin/python3 .agents/skills/web-to-markdown/scripts/fetch_as_markdown.py "<url>" --wtm-accept-risk --caller mk:investigate
1---2name: mk-investigate-23description: Systematic root-cause debugging that produces a diagnostic report (mk:fix applies the fix; mk:build-fix owns compile failures). Use for 'debug this', 'why is this broken', 'root cause'.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 `$(git rev-parse --show-toplevel)` (project root). Prefix paths with `"$(git rev-parse --show-toplevel)/"` 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 `AGENTS.md` (Memory).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 | stop and ask the user in chat 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: `.agents/skills/.venv/bin/python3 .agents/skills/web-to-markdown/scripts/fetch_as_markdown.py "<url>" --wtm-accept-risk --caller mk:investigate`
ngocsangyem