hk-rca

Name: hk-rca
Author: deepklarity

84stars12forks

How to install hk-rca?

deepklarity/harness-kit/hk-rca

$npx -y skills add deepklarity/harness-kit --skill hk-rca

Installs into the current project.

Summary

Interactive Root Cause Analysis enforcer. Guides you through the 7-step RCA protocol: Reproduce, Locate, Hypothesis, Failing Test, Fix, Verify Live, Document. Use when debugging a bug, investigating a failure, or when something unexpected happened. This skill gates each step — it

Files · 1

View on GitHub

SKILL.md

1	# /hk-rca — Root Cause Analysis Protocol
2
3	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.
4
5	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.
6
7	## Context
8
9	<bug_context> $ARGUMENTS </bug_context>
10
11	If the context above is empty, ask the user: "What's broken? Describe the symptom — what you expected vs. what happened."
12
13	## The Protocol
14
15	Work through these steps in order. Present each step's output visibly before moving to the next. Do not skip steps.
16
17	### Step 1: REPRODUCE
18
19	Before anything else, confirm the bug exists and define its boundaries.
20
21	Produce this checklist (fill it in, don't just print it empty):
22
23	```
24	REPRODUCE:
25	- Symptom: [what's wrong — exact error, unexpected behavior, missing data]
26	- Expected: [what should have happened]
27	- Actual: [what did happen]
28	- Input: [exact input that triggers it — command, URL, spec, task ID]
29	- Deterministic? [yes/no/unknown]
30	- Environment: [local, staging, which agent, which harness]
31	```
32
33	If you cannot reproduce it, stop and tell the user. Do not guess. Do not "fix" something you haven't seen fail.
34
35	### Step 2: LOCATE
36
37	Narrow the failure to a specific layer. Follow this order — stop when you find the discrepancy:
38
39	1. Data layer: Run diagnostic scripts if available (task_inspect, spec_trace, etc.)
40	- Does the data look correct in the database/store?
41	- If NO → bug is in the backend (model, serializer, view, pipeline)
42	- If YES → data is correct but not reaching the consumer
43
44	2. API layer: Check the API response or function output
45	- Does the output include the expected fields/values?
46	- If NO → serializer, view, or processing bug
47	- If YES → bug is in the consumer (frontend, CLI, downstream code)
48
49	3. Consumer layer: Check the final consumer
50	- Is it receiving the data?
51	- Is it rendering/using it?
52	- Is there a conditional hiding it?
53
54	State the layer explicitly:
55	```
56	LOCATED: The bug is in the [data/API/consumer] layer.
57	Evidence: [what you checked and what you found]
58	```
59
60	### Step 3: HYPOTHESIS
61
62	Before writing any fix, state your hypothesis. This is the most important step — it makes your reasoning checkable and prevents shotgun debugging.
63
64	Format:
65	```
66	HYPOTHESIS: I think the problem is [X] because [Y].
67	Changing [Z] should fix it because [W].
68	```
69
70	This must be specific enough that someone else could evaluate whether the hypothesis is plausible without seeing the code. "Something is wrong with the parser" is not a hypothesis. "The token parser expects Anthropic-style keys but receives OpenAI-style keys because the new harness uses a different format" is a hypothesis.
71
72	### Step 4: FAILING TEST
73
74	Write a test that:
75	- Reproduces the exact bug
76	- Fails right now
77	- Will pass after the fix
78
79	This test is the proof that the fix works. The test must fail BEFORE the fix is applied. If you can't write a failing test, your hypothesis may be wrong — go back to Step 3.
80
81	Show the test and its failure:
82	```
83	TEST: [file path and test name]
84	RESULT: FAILS with [error message]
85	```
86
87	### Step 5: FIX
88
89	Now — and only now — write the fix. Change the minimum code needed to make the failing test pass. Do not refactor, do not clean up, do not improve adjacent code.
90
91	Run the failing test. It should pass. Run the full relevant suite. Nothing else should break.
92
93	```
94	FIX: [what was changed, 1-2 sentences]
95	TEST RESULT: PASSES
96	SUITE RESULT: [all pass / N failures — list them]
97	```
98
99	### Step 6: VERIFY LIVE
100
101	After static tests pass, verify the behavior in the real system. This step is not optional.
102
103	- If UI bug: load the page and confirm
104	- If API bug: hit the endpoint and confirm
105	- If pipeline bug: run a spec and confirm
106	- If logic bug: run the actual scenario that triggered it
107
108	```
109	LIVE VERIFICATION: [what was checked and the result]
110	```
111
112	If you cannot verify live (e.g., no running server), say so explicitly and note it as a follow-up.
113
114	### Step 7: DOCUMENT
115
116	Record the RCA. This goes in the commit message or PR description:
117
118	```
119	Fix: [what was fixed]
120	Root cause: [the actual root cause — not the symptom]
121	Prevention: [what test/check

People who liked this also viewed

6 picks

Type

hk-rca

84stars12forks

View on GitHub

How to install hk-rca?

deepklarity/harness-kit/hk-rca

$npx -y skills add deepklarity/harness-kit --skill hk-rca

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /hk-rca — Root Cause Analysis Protocol
2
3	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.
4
5	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.
6
7	## Context
8
9	<bug_context> $ARGUMENTS </bug_context>
10
11	If the context above is empty, ask the user: "What's broken? Describe the symptom — what you expected vs. what happened."
12
13	## The Protocol
14
15	Work through these steps in order. Present each step's output visibly before moving to the next. Do not skip steps.
16
17	### Step 1: REPRODUCE
18
19	Before anything else, confirm the bug exists and define its boundaries.
20
21	Produce this checklist (fill it in, don't just print it empty):
22
23	```
24	REPRODUCE:
25	- Symptom: [what's wrong — exact error, unexpected behavior, missing data]
26	- Expected: [what should have happened]
27	- Actual: [what did happen]
28	- Input: [exact input that triggers it — command, URL, spec, task ID]
29	- Deterministic? [yes/no/unknown]
30	- Environment: [local, staging, which agent, which harness]
31	```
32
33	If you cannot reproduce it, stop and tell the user. Do not guess. Do not "fix" something you haven't seen fail.
34
35	### Step 2: LOCATE
36
37	Narrow the failure to a specific layer. Follow this order — stop when you find the discrepancy:
38
39	1. Data layer: Run diagnostic scripts if available (task_inspect, spec_trace, etc.)
40	- Does the data look correct in the database/store?
41	- If NO → bug is in the backend (model, serializer, view, pipeline)
42	- If YES → data is correct but not reaching the consumer
43
44	2. API layer: Check the API response or function output
45	- Does the output include the expected fields/values?
46	- If NO → serializer, view, or processing bug
47	- If YES → bug is in the consumer (frontend, CLI, downstream code)
48
49	3. Consumer layer: Check the final consumer
50	- Is it receiving the data?
51	- Is it rendering/using it?
52	- Is there a conditional hiding it?
53
54	State the layer explicitly:
55	```
56	LOCATED: The bug is in the [data/API/consumer] layer.
57	Evidence: [what you checked and what you found]
58	```
59
60	### Step 3: HYPOTHESIS
61
62	Before writing any fix, state your hypothesis. This is the most important step — it makes your reasoning checkable and prevents shotgun debugging.
63
64	Format:
65	```
66	HYPOTHESIS: I think the problem is [X] because [Y].
67	Changing [Z] should fix it because [W].
68	```
69
70	This must be specific enough that someone else could evaluate whether the hypothesis is plausible without seeing the code. "Something is wrong with the parser" is not a hypothesis. "The token parser expects Anthropic-style keys but receives OpenAI-style keys because the new harness uses a different format" is a hypothesis.
71
72	### Step 4: FAILING TEST
73
74	Write a test that:
75	- Reproduces the exact bug
76	- Fails right now
77	- Will pass after the fix
78
79	This test is the proof that the fix works. The test must fail BEFORE the fix is applied. If you can't write a failing test, your hypothesis may be wrong — go back to Step 3.
80
81	Show the test and its failure:
82	```
83	TEST: [file path and test name]
84	RESULT: FAILS with [error message]
85	```
86
87	### Step 5: FIX
88
89	Now — and only now — write the fix. Change the minimum code needed to make the failing test pass. Do not refactor, do not clean up, do not improve adjacent code.
90
91	Run the failing test. It should pass. Run the full relevant suite. Nothing else should break.
92
93	```
94	FIX: [what was changed, 1-2 sentences]
95	TEST RESULT: PASSES
96	SUITE RESULT: [all pass / N failures — list them]
97	```
98
99	### Step 6: VERIFY LIVE
100
101	After static tests pass, verify the behavior in the real system. This step is not optional.
102
103	- If UI bug: load the page and confirm
104	- If API bug: hit the endpoint and confirm
105	- If pipeline bug: run a spec and confirm
106	- If logic bug: run the actual scenario that triggered it
107
108	```
109	LIVE VERIFICATION: [what was checked and the result]
110	```
111
112	If you cannot verify live (e.g., no running server), say so explicitly and note it as a follow-up.
113
114	### Step 7: DOCUMENT
115
116	Record the RCA. This goes in the commit message or PR description:
117
118	```
119	Fix: [what was fixed]
120	Root cause: [the actual root cause — not the symptom]
121	Prevention: [what test/check

People who liked this also viewed

6 picks

Type