Systematic Debugging
ChrisWiles/claude-code-showcase
Applies a four-phase debugging routine that finds the root cause of a bug or failing test before any fix is written.
Interactive Root Cause Analysis enforcer. An agent skill from deepklarity/harness-kit.
Install Hk Rca
$ npx skills add deepklarity/harness-kit --skill hk-rca -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install deepklarity/harness-kit hk-rca --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/deepklarity/harness-kit.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/hk-rca .claude/skills/hk-rca && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "hk-rca" agent skill from https://github.com/deepklarity/harness-kit/tree/main/.claude/skills/hk-rca into .claude/skills/hk-rca/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "hk-rca", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/deepklarity/harness-kit/tree/main/.claude/skills/hk-rcaType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add deepklarity/harness-kit --skill hk-rca -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install deepklarity/harness-kit hk-rca --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/deepklarity/harness-kit.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.claude/skills/hk-rca .agents/skills/hk-rca && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "hk-rca" agent skill from https://github.com/deepklarity/harness-kit/tree/main/.claude/skills/hk-rca into .agents/skills/hk-rca/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "hk-rca", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add deepklarity/harness-kit --skill hk-rca -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install deepklarity/harness-kit hk-rca --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/deepklarity/harness-kit.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.claude/skills/hk-rca .cursor/skills/hk-rca && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "hk-rca" agent skill from https://github.com/deepklarity/harness-kit/tree/main/.claude/skills/hk-rca into .cursor/skills/hk-rca/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "hk-rca", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/deepklarity/harness-kit.git --path .claude/skills/hk-rca--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add deepklarity/harness-kit --skill hk-rca -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install deepklarity/harness-kit hk-rca --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/deepklarity/harness-kit.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.claude/skills/hk-rca .gemini/skills/hk-rca && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "hk-rca" agent skill from https://github.com/deepklarity/harness-kit/tree/main/.claude/skills/hk-rca into .gemini/skills/hk-rca/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "hk-rca", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install deepklarity/harness-kit hk-rcaInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add deepklarity/harness-kit --skill hk-rca -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/deepklarity/harness-kit.git skills-src && mkdir -p .github/skills && cp -r skills-src/.claude/skills/hk-rca .github/skills/hk-rca && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "hk-rca" agent skill from https://github.com/deepklarity/harness-kit/tree/main/.claude/skills/hk-rca into .github/skills/hk-rca/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "hk-rca", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add deepklarity/harness-kit --skill hk-rca -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install deepklarity/harness-kit hk-rca --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/deepklarity/harness-kit.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.claude/skills/hk-rca .opencode/skills/hk-rca && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "hk-rca" agent skill from https://github.com/deepklarity/harness-kit/tree/main/.claude/skills/hk-rca into .opencode/skills/hk-rca/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "hk-rca", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
hk-rca- GitHub stars
- 100
- Token cost
- ~1.5k tokens
- SKILL.md length
- 670 words
- Files
- 1
- Skills in repo
- 18
- Repo updated
- First seen
- Licence
- MIT
At a glance
Interactive Root Cause Analysis enforcer. An agent skill from deepklarity/harness-kit.
- Works in 7 steps: REPRODUCE → LOCATE → HYPOTHESIS → …
- Debugging a bug
- SKILL.md covers Context, The Protocol, After completing all 7 steps and When to bail out
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Hk Rca is an agent skill from deepklarity/harness-kit. 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 won't let you skip to a fix without stating a hypothesis first. Triggers on: 'something is broken', 'debug this', 'why is this failing', 'RCA', 'root cause', or /hk-rca.
Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Root cause analysis, Failing and flaky tests and Debugging. The repository describes itself as: A kit for building with AI agents and also the engineering patterns around it. The licence is MIT.
When your agent uses it
- Debugging a bug
- Investigating a failure
- Something unexpected happened
- : something is broken
Example prompts
- “something is broken”
- “debug this”
- “why is this failing”
- “/hk-rca”
Requirements
- Pre-approved tools (allowed-tools): Bash, Read, Edit, Write, Task, Grep, Glob
Workflow steps
7 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit 87305cd. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves these tools, so the agent can use them without asking each time:
BashReadEditWriteTaskGrepGlob
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Hk Rca loads about 1.5k tokens when it runs. Until then it costs about 114 tokens; SKILL.md has 670 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check: notes
The automated check noted patterns worth knowing about, such as sudo or a known installer.
- NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
allowed-tools: Bash, Read, Edit, Write, Task, Grep, Glob
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from deepklarity/harness-kit at commit 87305cd, republished under its MIT licence (© deepklarity). 670 words, ~1,457 tokens.
Download SKILL.mdSave it as
.claude/skills/hk-rca/SKILL.md (or your agent's skills folder).- name
- hk-rca
- description
- 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 won't let you skip to a fix without stating a hypothesis first. Triggers on: 'something is broken', 'debug this', 'why is this failing', 'RCA', 'root cause', or /hk-rca.
- allowed-tools
- Bash, Read, Edit, Write, Task, Grep, Glob
- argument-hint
- [optional: brief description of the bug or symptom]
/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:
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
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)
Consumer layer: Check the final consumer
- Is it receiving the data?
- Is it rendering/using it?
- Is there a conditional hiding it?
State the layer explicitly:
LOCATED: The bug is in the [data/API/consumer] layer.
Evidence: [what you checked and what you found]Step 3: HYPOTHESIS
Before writing any fix, state your hypothesis. This is the most important step — it makes your reasoning checkable and prevents shotgun debugging.
Format:
HYPOTHESIS: I think the problem is [X] because [Y].
Changing [Z] should fix it because [W].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.
Step 4: FAILING TEST
Write a test that:
- Reproduces the exact bug
- Fails right now
- Will pass after the fix
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.
Show the test and its failure:
TEST: [file path and test name]
RESULT: FAILS with [error message]Show full SKILL.md (244 more words)Show less
Step 5: FIX
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.
Run the failing test. It should pass. Run the full relevant suite. Nothing else should break.
FIX: [what was changed, 1-2 sentences]
TEST RESULT: PASSES
SUITE RESULT: [all pass / N failures — list them]Step 6: VERIFY LIVE
After static tests pass, verify the behavior in the real system. This step is not optional.
- If UI bug: load the page and confirm
- If API bug: hit the endpoint and confirm
- If pipeline bug: run a spec and confirm
- If logic bug: run the actual scenario that triggered it
LIVE VERIFICATION: [what was checked and the result]If you cannot verify live (e.g., no running server), say so explicitly and note it as a follow-up.
Step 7: DOCUMENT
Record the RCA. This goes in the commit message or PR description:
Fix: [what was fixed]
Root cause: [the actual root cause — not the symptom]
Prevention: [what test/check now prevents recurrence]If the bug reveals a systemic gap (e.g., "serializers are never tested for new fields"), call it out as a follow-up item.
After completing all 7 steps
Summarize:
## RCA Summary
Symptom: [1 line]
Root cause: [1 line]
Fix: [1 line]
Prevention: [what test now guards this]
Systemic gap: [if any — what process change prevents similar bugs]When to bail out
If after Step 3, your hypothesis doesn't hold (the fix doesn't work, or a new error appears that contradicts your reasoning):
- Do NOT cascade-fix (fixing error A reveals error B, fixing B reveals C — this means A was wrong)
- Go back to Step 2 and re-locate
- If stuck after 2 failed hypotheses, zoom out: re-read the data flow end-to-end, question your assumptions about what the code does vs. what you think it does
© deepklarity, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in .claude/skills/hk-rca of deepklarity/harness-kit.
Open the folder on GitHubat commit 87305cd
Compare with similar skills
Hk Rca next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Hk Rca this skilldeepklarity/harness-kit | 100 | — | ~1.5k | Automated safety check: Notes | MIT | |
| Systematic DebuggingChrisWiles/claude-code-showcase | 6.1k | 3 repos | ~1.2k | Automated safety check: Pass | None | |
| Debugging and Error Recoveryaddyosmani/agent-skills | 104k | 1 repos | ~2.6k | Automated safety check: Pass | MIT | |
| Systematic Debugginged3dai/ed3d-plugins | 250 | 3 repos | ~2.4k | Automated safety check: Pass | None | |
| Debugging And Error Recoveryabashev/vfs-s3 | 106 | 6 repos | ~2.6k | Automated safety check: Pass | Apache-2.0 | |
| Veomni DebugByteDance-Seed/VeOmni | 2.2k | — | ~2.8k | Automated safety check: Pass | Apache-2.0 |
Similar skills
Debugging and Error Recovery
addyosmani/agent-skills
Applies a stop-the-line rule and a step-by-step triage when tests fail, builds break or something stops working, aiming at the root cause instead of guesses.
Systematic Debugging
ed3dai/ed3d-plugins
A skill your agent uses when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis…
Debugging And Error Recovery
abashev/vfs-s3
Guides systematic root-cause debugging. An agent skill from abashev/vfs-s3.
Veomni Debug
ByteDance-Seed/VeOmni
A skill your agent uses for ANY bug, error, crash, wrong output, loss divergence, gradient explosion, test failure, CUDA error, distributed training hang, checkpoint load failure, or unexpected…
Root Cause Debugging
jsmastery-pro/skills
Runs a reproduce, localize, hypothesize, test, fix and verify loop to find a bug's root cause, applies the minimal fix and hands off a regression test.
More from deepklarity/harness-kit
All 18 skills in this repoHk Skill Creator
deepklarity/harness-kit
Create new skills, modify and improve existing skills, and measure skill performance.
Hk Arch Audit
deepklarity/harness-kit
Run comprehensive agent-native architecture review with scored principles.
Hk Mock First
deepklarity/harness-kit
Mock-first, layer-by-layer feature development. An agent skill from deepklarity/harness-kit.
Hk Autonomy Audit
deepklarity/harness-kit
Audit whether an AI agent can autonomously close the loop on problems in a given area — from discovering a symptom to verifying a fix — without human intervention.
Hk Breadcrumb Creator
deepklarity/harness-kit
Traces a workflow end-to-end through the harness-kit monorepo and creates a breadcrumb analysis doc in docs/breadcrumbanalysis/.
Hk Changelog
deepklarity/harness-kit
Generate changelog entries from git diffs, prepend to CHANGELOG.md, and optionally commit + PR.
Related
Categories
Questions about Hk Rca
What does Hk Rca do?
Interactive Root Cause Analysis enforcer. An agent skill from deepklarity/harness-kit. Hk Rca is an agent skill from deepklarity/harness-kit. Interactive Root Cause Analysis enforcer.
When should I use Hk Rca?
Hk Rca fits situations like: debugging a bug; investigating a failure; something unexpected happened; : something is broken.
How do I install Hk Rca in Claude Code?
Run `npx skills add deepklarity/harness-kit --skill hk-rca -a claude-code`. Or copy the skill folder (.claude/skills/hk-rca in deepklarity/harness-kit) into .claude/skills/hk-rca in your project. Claude Code loads it when a task matches its description.
How do I install Hk Rca in Codex?
Run `npx skills add deepklarity/harness-kit --skill hk-rca -a codex`. Or copy the skill folder (.claude/skills/hk-rca in deepklarity/harness-kit) into .agents/skills/hk-rca in your project. Codex loads it when a task matches its description.
Can I use Hk Rca in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add deepklarity/harness-kit --skill hk-rca -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/hk-rca, .gemini/skills/hk-rca, .github/skills/hk-rca and .opencode/skills/hk-rca in your project.
What does Hk Rca need to run?
SKILL.md names no scripts, command-line tools or credentials: Hk Rca is instructions for the agent only. Its frontmatter pre-approves these tools: Bash, Read, Edit, Write, Task, Grep, Glob.
Does Hk Rca access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Hk Rca safe to install?
Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.
What licence does Hk Rca use?
Hk Rca is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Hk Rca use?
About 1.5k tokens (SKILL.md is roughly 5.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Hk Rca?
Skills that share tags, products or a category with Hk Rca: Systematic Debugging (ChrisWiles/claude-code-showcase, 6.1k stars), Debugging and Error Recovery (addyosmani/agent-skills, 104k stars), Systematic Debugging (ed3dai/ed3d-plugins, 250 stars) and Debugging And Error Recovery (abashev/vfs-s3, 106 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Hk Rca?
deepklarity (a GitHub organization) maintains it in deepklarity/harness-kit, which has 100 GitHub stars. The repository holds 18 skills in this directory. The repository was last updated on July 15, 2026.
Source: deepklarity/harness-kit on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.