# Karvey Investigate

> Systematic root-cause debugging for the Karvey method. Iron Law — no fixes without investigation first. Dates the symptom, asks what changed before what is wrong, traces data flow across repo boundaries, forms and tests hypotheses, separates root cause from latent fragility, stops after repeated failures. Triggers include "karvey investigate", "investigar bug", "root cause", "depurar", "por qué falla", "debugging".

- Skill: `mauricioquezadahaintech/karvey-investigate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mauricioquezadahaintech/karvey-investigate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mauricioquezadahaintech/karvey-investigate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: MauricioQuezadaHaintech (https://skillmd.com/u/mauricioquezadahaintech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mauricioquezadahaintech/karvey-investigate

---


# Karvey Investigate — Root-Cause Analysis

## Purpose

A **cross-cutting** skill of the Karvey Method: a debugging and root-cause-analysis support layer (the Debugger role, inspired by gstack `/investigate`). **It is NOT a phase of the linear pipeline**: it does not modify `spec.json:phase` nor advance the phase flow. It is invoked any time a symptom, bug or unexpected behavior shows up, and when it finishes the pipeline continues exactly where it was.

**Iron Law:** NEVER apply fixes without first investigating the root cause. The investigation produces evidence and a recommendation; the fix is applied by `karvey-impl`, respecting the corresponding gates.

It is **stack-agnostic**: it uses the target's real runtime (see `karvey/rules/targets.md`), whether it's Python/Azure Functions, Vue, SQL Server, Node-RED, Asterisk, etc.

## Steps

1. **Capture the exact symptom, how to reproduce it, and WHEN it started.**
   - Write down the observed behavior vs. the expected one, the literal error message, stack trace, exit code, and the minimal steps to reproduce.
   - If there is no reliable repro, get one before continuing. Without a repro there is no serious investigation.
   - **Date the symptom.** Get the timestamp of the report and, if possible, of the first occurrence. Ask the reporter if it is not in the ticket. This gives you the **incident window** (first occurrence → report), and steps 2 and 3 are useless without it. An investigation that never establishes a date is not an investigation; it is a code review.

2. **Check what is already known before reading any code.**
   - Read the incident tracker (`docs/bugs_dev_testing.md`, `incidents-index.md` — see `karvey/rules/incident-tracking.md`): this symptom may already be diagnosed, or reopened.
   - Read the engineering standards (`karvey/rules/engineering-standards.md`) for the layer involved: a known gray zone or a documented migration often IS the explanation.
   - Skim the team's `CHANGELOG.md` for the incident window.
   - The team's accumulated knowledge is a first-class source of evidence. Skipping it means re-deriving from scratch a root cause somebody already paid for.

3. **Ask "what CHANGED?" before "what is WRONG?".**
   - For any symptom that is new or recently reported, the causal question is historical, not static. Before reading source code, inspect the incident window: `CHANGELOG.md` entries, `git log` (including `git log -S` for the symbol involved), merges to the deploy branches, releases, **and changes outside the application code** — configuration, security headers/CSP, secrets and their rotation, infra, feature flags, external provider or quota changes.
   - Only after this, move on to reading code. Most recent symptoms are explained by a recent change, and that change is frequently not in the repo you are staring at.

4. **Trace the data flow / relevant code path.**
   - Use Grep/Glob to locate the entry point and follow the data flow down to the symptom.
   - Read (Read) the files involved end to end along the path: input → transformations → output.
   - Identify the boundaries (SP calls, webhooks, external APIs, queues/events) where the data can get corrupted or lost.
   - **The path does not stop at the repo boundary.** Follow it into whatever component actually holds the next hop — the other repo, the SP, the gateway, the provider's configuration. If a repo you need is not available to you, say so explicitly and name what you would inspect; do not silently downgrade the conclusion to what happened to be reachable.

5. **Formulate explicit hypotheses.**
   - Write each hypothesis as a falsifiable claim: "X fails because Y".
   - Prioritize by likelihood and by verification cost (verify the cheapest and most likely first).

6. **Test each hypothesis with evidence.**
   - Confirm or rule out with concrete evidence: logs, temporary prints/traces, read queries, state inspection, and **reproduction in the target's real runtime** (see `karvey/rules/targets.md`).
   - Each hypothesis is closed with a verdict: confirmed / ruled out, and the evidence that backs it.
   - Do not mix several diagnostic changes at once: change one variable at a time so the signal is not contaminated.
   - **Never state what a symbol does without opening it.** Helpers, wrappers and loggers defined inside the project are the usual trap: their behavior is a project decision, not a language default. If a claim in the report depends on what `logger.error`, a retry helper or a guard actually does, read its definition and cite file and line. An unread assumption is not evidence.

7. **Causal-coherence check — this is a gate, not a formality.**
   - Before declaring a root cause, confirm it explains the symptom **in time**: a cause that predates the incident window cannot by itself explain a symptom that started inside it.
   - If the finding turns out to be pre-existing ("this has been here since the first commit"), then it is **latent fragility, not the cause**. That is a valid, reportable finding — but the investigation is not finished: something recent turned a latent weakness into a live failure. Go back to step 3 and find the trigger.
   - State the verdict explicitly in the report: *cause* (explains the window) vs. *contributing fragility* (made the failure worse or silent). Confusing the two sends the team to fix something real that will not stop the incident.

8. **Stop after ~3 failed attempts.**
   - If after ~3 hypothesis-test cycles the root cause is still not reached, **stop and ask for help** instead of continuing blindly or firing off speculative fixes.
   - Report what was ruled out, what is still uncertain, and what information or access is missing to move forward.

9. **Report the root cause with evidence and a fix recommendation.**
   - Deliver: the incident window, the identified root cause, the evidence that supports it, the impact scope, and the fix recommendation.
   - Separate **root cause** from **contributing fragility**, and **verified fact** from **open hypothesis** — each labeled, never blended into one narrative.
   - **Before recommending a mechanism, check whether the codebase already has it.** Retry/backoff, reconnection, degraded-state indicators, circuit breakers: a sibling module has usually solved it already. Cite that implementation as the pattern to follow instead of designing a new one; consistency beats novelty and the existing one is already battle-tested.
   - **Do not apply the fix here.** The fix is executed by `karvey-impl`, respecting the method's gates.

## Constraints

- It does not advance or change the pipeline phase (`spec.json:phase` stays intact).
- It does not apply corrective changes; it only diagnoses and recommends.
- Temporary diagnostic changes (prints, traces) must be reverted or flagged so that `karvey-impl` cleans them up.
- **No undated investigation.** Without an incident window there is no causal claim — at most a list of weaknesses.
- **No pre-existing finding may be reported as the cause of a new symptom** without a trigger that explains the window.
- **No claim about a symbol's behavior without having read its definition**, cited by file and line.

---
*Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see `karvey/LICENSE` and `karvey/TRADEMARK.md`.*