# Mk:investigate

> |

- **Type:** Skill
- **Install:** `agentstack add skill-ngocsangyem-meowkit-investigate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ngocsangyem](https://agentstack.voostack.com/s/ngocsangyem)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ngocsangyem](https://github.com/ngocsangyem)
- **Source:** https://github.com/ngocsangyem/MeowKit/tree/main/.claude/skills/investigate
- **Website:** https://docs.meowkit.dev/

## Install

```sh
agentstack add skill-ngocsangyem-meowkit-investigate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Systematic Debugging

> **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:** `.claude/memory/fixes.md`, `.claude/memory/architecture-decisions.md`
- **Writes memory:** `.claude/memory/fixes.md` via direct `Edit` (diagnosis records only — `##note:` is a user-typed keyboard shortcut that does NOT fire from agent output; the fix itself is persisted by `mk:fix`). See `.claude/skills/memory/references/capture-architecture.md`.

## Plan-First Gate

Investigation precedes planning for bug fixes:

1. Confirm root cause FIRST (Iron Law)
2. After root cause confirmed → invoke `mk:plan-creator --type bugfix` if fix affects > 2 files

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

1. **Run preamble** — load `references/preamble.md` and execute the startup bash block
2. **Collect symptoms** — read error messages, stack traces, reproduction steps
3. **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.
4. **Lock scope** — optionally invoke `mk:freeze ` first to restrict edits to the affected module. The `check-freeze.sh` hook is installed but without an explicit `mk:freeze` invocation it is a no-op (all edits allowed).
5. **Implement fix** — follow Phase 4 from debugging methodology
6. **Verify** — reproduce original scenario, run test suite, output DEBUG REPORT
7. **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](./references/preamble.md)**                           | Step 1 — skill startup          | Session init, env detection, upgrade check                                  |
| **[debugging-methodology.md](./references/debugging-methodology.md)** | Steps 2-6 — investigation + fix | 5-phase debugging: investigate → analyze → hypothesize → implement → verify |
| **[shared-protocols.md](./references/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  ` | 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

- **Read-only until hypothesis confirmed** — no edits until root cause identified
- **3-strike rule** — if 3 hypotheses fail, STOP and escalate
- **Minimal diff** — fix root cause with fewest files/lines possible
- **Regression test required** — must fail without fix, pass with fix
- **>5 files touched** — AskUserQuestion about blast radius before proceeding

## Hooks

- **Iron Law enforcement**: No fixes without confirmed root cause — this is a process constraint, not a technical hook
- The skill gates Phase 3 (Fix) behind Phase 1 (Investigate) completion
- If root cause cannot be confirmed after 3 hypotheses, escalate to human
- **Scope-locking hook**: Installs a `PreToolUse` hook on Edit/Write that delegates to `mk:freeze` to scope edits to the investigation target. Deactivation follows freeze's semantics — end the session or start a new one to clear it.
- **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 "" --wtm-accept-risk --caller mk:investigate`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ngocsangyem](https://github.com/ngocsangyem)
- **Source:** [ngocsangyem/MeowKit](https://github.com/ngocsangyem/MeowKit)
- **License:** MIT
- **Homepage:** https://docs.meowkit.dev/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ngocsangyem-meowkit-investigate
- Seller: https://agentstack.voostack.com/s/ngocsangyem
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.