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 and how to reproduce it.

   • 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.

2. 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.

3. 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).

4. 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.

5. 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.

6. Report the root cause with evidence and a fix recommendation.

   • Deliver: identified root cause, the evidence that supports it, the impact scope, and the fix recommendation.
   • 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.

---

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