hk-rca

/hk-rca — Root Cause Analysis Protocol

This skill enforces the discipline of methodical debugging. The protocol exists because the most common debugging failure is jumping from "I see the symptom" to "I'll try this fix" — skipping the hypothesis, the test, and the verification.

Each step gates the next. You don't write a fix until you have a hypothesis. You don't have a hypothesis until you've located the layer. You don't locate the layer until you've reproduced the bug.

Context

<bug_context> $ARGUMENTS </bug_context>

If the context above is empty, ask the user: "What's broken? Describe the symptom — what you expected vs. what happened."

The Protocol

Work through these steps in order. Present each step's output visibly before moving to the next. Do not skip steps.

Step 1: REPRODUCE

Before anything else, confirm the bug exists and define its boundaries.

Produce this checklist (fill it in, don't just print it empty):

REPRODUCE:
- Symptom: [what's wrong — exact error, unexpected behavior, missing data]
- Expected: [what should have happened]
- Actual: [what did happen]
- Input: [exact input that triggers it — command, URL, spec, task ID]
- Deterministic? [yes/no/unknown]
- Environment: [local, staging, which agent, which harness]

If you cannot reproduce it, stop and tell the user. Do not guess. Do not "fix" something you haven't seen fail.

Step 2: LOCATE

Narrow the failure to a specific layer. Follow this order — stop when you find the discrepancy:

1. Data layer: Run diagnostic scripts if available (task_inspect, spec_trace, etc.)

   • Does the data look correct in the database/store?
   • If NO → bug is in the backend (model, serializer, view, pipeline)
   • If YES → data is correct but not reaching the consumer

2. API layer: Check the API response or function output

   • Does the output include the expected fields/values?
   • If NO → serializer, view, or processing bug
   • If YES → bug is in the consumer (frontend, CLI, downstream code)