hk-follow-breadcrumb

Name: hk-follow-breadcrumb
Author: deepklarity

84stars12forks

How to install hk-follow-breadcrumb?

deepklarity/harness-kit/hk-follow-breadcrumb

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

Installs into the current project.

Summary

Consults existing breadcrumb analysis docs before exploring the codebase. Use this skill whenever the user asks about how a flow works, where something happens in the code, how to debug or test a specific area, what files are involved in a feature, or needs to understand the path

Files · 1

View on GitHub

SKILL.md

1	# /hk-follow-breadcrumb — Breadcrumb-First Exploration
2
3	This skill is about reading before searching. The `docs/breadcrumb_analysis/` directory contains end-to-end workflow traces that have already been carefully researched and documented. Loading a relevant breadcrumb takes seconds and costs a fraction of what spawning exploration subagents costs. The breadcrumb docs are maintained alongside code changes, so they're the most reliable "map" of how flows work.
4
5	## Context
6
7	<exploration_context> $ARGUMENTS </exploration_context>
8
9	If the context above is empty, look at what the user is asking about in the conversation and infer the exploration target.
10
11	## Step 1: Load the index
12
13	Read `docs/breadcrumb_analysis/_INDEX.md`. This is the single source of truth for what's been documented.
14
15	The index has two sections that matter:
16
17	1. Flows table — lists every breadcrumb folder and what it traces. Scan this to find which breadcrumb(s) cover the user's question.
18	2. Quick navigation — maps common symptoms (e.g., "task stuck in IN_PROGRESS", "screenshots not showing") directly to the right DEBUG.md. If the user describes a symptom, check here first.
19
20	## Step 2: Match the question to breadcrumbs
21
22	Compare what the user is asking against the index entries. There are three outcomes:
23
24	### A. Direct hit — a breadcrumb covers exactly this flow
25
26	Load the relevant docs in order of increasing detail:
27
28	1. FLOW.md — Read this first. It's the high-level map (30-second read). Shows the path data takes, which files/functions are involved at each hop, and where branches occur. This alone often answers "where does X happen?" questions.
29
30	2. DETAILS.md — Read this if the user needs function-level specifics: what data goes in/out, what conditionals change behavior, what side effects exist. This answers "how does X work?" questions.
31
32	3. DEBUG.md — Read this if the user is debugging something broken, or wants to know how to test a flow. Contains log locations, grep patterns, quick commands, env vars, and common breakpoints. This answers "how do I debug/test X?" questions.
33
34	Don't load all three by default. Start with FLOW.md. Only go deeper if the user's question requires it. Present what you found and ask if they need more detail.
35
36	### B. Partial coverage — a breadcrumb covers part of the flow
37
38	Load the relevant breadcrumb for the covered portion. Then clearly tell the user:
39
40	```
41	The breadcrumb for <X> covers <these parts> of what you're asking about.
42	For <the uncovered parts>, I'll need to explore the code directly.
43	```
44
45	Then explore only the gaps — don't re-trace what the breadcrumb already documents.
46
47	### C. No coverage — nothing in the index matches
48
49	Tell the user:
50
51	```
52	No existing breadcrumb covers this flow. I'll explore the code directly.
53	Consider running /hk-breadcrumb-creator afterward to document this flow for next time.
54	```
55
56	Then proceed with normal exploration (grep, glob, file reads, subagents as needed).
57
58	## Step 3: Present findings
59
60	After loading the relevant breadcrumb docs, synthesize an answer to the user's actual question. Don't just dump the breadcrumb content — extract the specific information they need.
61
62	Good response pattern:
63	```
64	Based on the breadcrumb for <flow-name>:
65
66	<direct answer to their question, citing specific files/functions from the breadcrumb>
67
68	The key files involved are:
69	- `path/to/file.py` :: `function()` — <what it does in this context>
70	- `path/to/other.py` :: `other_func()` — <what it does>
71
72	<if debugging> Quick commands from the debug guide:
73	<relevant commands from DEBUG.md>
74	```
75
76	If the breadcrumb is stale (references files/functions that no longer exist), note which parts seem outdated and verify those specific points against the current code. Flag this to the user so the breadcrumb can be updated.
77
78	## Step 4: Suggest breadcrumb creation for gaps
79
80	If the user's exploration uncovered a flow that isn't documented (outcome C), or revealed that an existing

People who liked this also viewed

6 picks

Type

hk-follow-breadcrumb

84stars12forks

View on GitHub

How to install hk-follow-breadcrumb?

deepklarity/harness-kit/hk-follow-breadcrumb

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /hk-follow-breadcrumb — Breadcrumb-First Exploration
2
3	This skill is about reading before searching. The `docs/breadcrumb_analysis/` directory contains end-to-end workflow traces that have already been carefully researched and documented. Loading a relevant breadcrumb takes seconds and costs a fraction of what spawning exploration subagents costs. The breadcrumb docs are maintained alongside code changes, so they're the most reliable "map" of how flows work.
4
5	## Context
6
7	<exploration_context> $ARGUMENTS </exploration_context>
8
9	If the context above is empty, look at what the user is asking about in the conversation and infer the exploration target.
10
11	## Step 1: Load the index
12
13	Read `docs/breadcrumb_analysis/_INDEX.md`. This is the single source of truth for what's been documented.
14
15	The index has two sections that matter:
16
17	1. Flows table — lists every breadcrumb folder and what it traces. Scan this to find which breadcrumb(s) cover the user's question.
18	2. Quick navigation — maps common symptoms (e.g., "task stuck in IN_PROGRESS", "screenshots not showing") directly to the right DEBUG.md. If the user describes a symptom, check here first.
19
20	## Step 2: Match the question to breadcrumbs
21
22	Compare what the user is asking against the index entries. There are three outcomes:
23
24	### A. Direct hit — a breadcrumb covers exactly this flow
25
26	Load the relevant docs in order of increasing detail:
27
28	1. FLOW.md — Read this first. It's the high-level map (30-second read). Shows the path data takes, which files/functions are involved at each hop, and where branches occur. This alone often answers "where does X happen?" questions.
29
30	2. DETAILS.md — Read this if the user needs function-level specifics: what data goes in/out, what conditionals change behavior, what side effects exist. This answers "how does X work?" questions.
31
32	3. DEBUG.md — Read this if the user is debugging something broken, or wants to know how to test a flow. Contains log locations, grep patterns, quick commands, env vars, and common breakpoints. This answers "how do I debug/test X?" questions.
33
34	Don't load all three by default. Start with FLOW.md. Only go deeper if the user's question requires it. Present what you found and ask if they need more detail.
35
36	### B. Partial coverage — a breadcrumb covers part of the flow
37
38	Load the relevant breadcrumb for the covered portion. Then clearly tell the user:
39
40	```
41	The breadcrumb for <X> covers <these parts> of what you're asking about.
42	For <the uncovered parts>, I'll need to explore the code directly.
43	```
44
45	Then explore only the gaps — don't re-trace what the breadcrumb already documents.
46
47	### C. No coverage — nothing in the index matches
48
49	Tell the user:
50
51	```
52	No existing breadcrumb covers this flow. I'll explore the code directly.
53	Consider running /hk-breadcrumb-creator afterward to document this flow for next time.
54	```
55
56	Then proceed with normal exploration (grep, glob, file reads, subagents as needed).
57
58	## Step 3: Present findings
59
60	After loading the relevant breadcrumb docs, synthesize an answer to the user's actual question. Don't just dump the breadcrumb content — extract the specific information they need.
61
62	Good response pattern:
63	```
64	Based on the breadcrumb for <flow-name>:
65
66	<direct answer to their question, citing specific files/functions from the breadcrumb>
67
68	The key files involved are:
69	- `path/to/file.py` :: `function()` — <what it does in this context>
70	- `path/to/other.py` :: `other_func()` — <what it does>
71
72	<if debugging> Quick commands from the debug guide:
73	<relevant commands from DEBUG.md>
74	```
75
76	If the breadcrumb is stale (references files/functions that no longer exist), note which parts seem outdated and verify those specific points against the current code. Flag this to the user so the breadcrumb can be updated.
77
78	## Step 4: Suggest breadcrumb creation for gaps
79
80	If the user's exploration uncovered a flow that isn't documented (outcome C), or revealed that an existing

People who liked this also viewed

6 picks

Type