hk-refine

Name: hk-refine
Author: deepklarity

84stars12forks

How to install hk-refine?

deepklarity/harness-kit/hk-refine

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

Installs into the current project.

Summary

Iteratively improve any output by running a structured observe-hypothesize-change-rerun loop. Uses an organized scratch directory to prevent context blowup — the conversation stays thin while iterations accumulate on disk. Use when an output (reflection, plan, prompt, pipeline re

Files · 1

View on GitHub

SKILL.md

1	# /hk-refine — Iterative Output Refinement
2
3	You have an open loop: something produced output, the output isn't good enough, and you need to systematically improve it. This skill closes that loop.
4
5	The core discipline: everything lives on disk, not in conversation context. The scratch directory is the organized record of what was tried, what worked, and why. Subagents read from disk, write to disk, and report back in 2-3 line summaries. The main conversation only holds the current hypothesis and verdict — never full outputs.
6
7	## Context
8
9	<loop_context> $ARGUMENTS </loop_context>
10
11	If the context above is empty or unclear, ask the user:
12	1. What produced the output? (command, prompt, pipeline step)
13	2. What's wrong with it? (vague is ok — "it's not good enough" is a valid start)
14	3. Where should the scratch directory live? (suggest `temp_reflections/` or `temp_loop/`)
15
16	## The Scratch Directory
17
18	This is the product. Not temp files — the organized log of the refinement process.
19
20	```
21	<scratch_dir>/
22	├── loop.md # Live loop state (see template below)
23	├── baseline/
24	│ ├── output.md # Original output that needs improvement
25	│ ├── critique.md # Structured critique of what's wrong
26	│ └── run_command.txt # Exact command/process that produced the output
27	├── iter-1/
28	│ ├── hypothesis.md # What to change and why
29	│ ├── changes.md # What was actually changed (with file paths and diffs)
30	│ ├── output.md # New output after changes
31	│ ├── comparison.md # Before vs after, structured
32	│ └── verdict.md # Better / worse / mixed — with evidence
33	├── iter-2/
34	│ └── ...
35	└── summary.md # Written when loop closes
36	```
37
38	### loop.md template
39
40	This file is the single source of truth for where the loop is. Read it at the start of every iteration. Update it after every verdict.
41
42	```markdown
43	# Close-the-Loop: [short description]
44
45	## Target
46	What we're improving: [one line]
47	Run command: [the exact command to re-run]
48	Quality signal: [how we know it's better — specific, measurable if possible]
49
50	## Current State
51	Iteration: [N]
52	Best so far: [baseline \| iter-N]
53	Status: [observing \| hypothesizing \| changing \| running \| comparing \| closed]
54
55	## Hypothesis Log
56	- iter-1: [hypothesis] → [verdict: better/worse/mixed]
57	- iter-2: [hypothesis] → [verdict]
58	- ...
59
60	## What We've Learned
61	- [Accumulated insights that carry forward — things that definitely help or definitely don't]
62
63	## Next
64	[What to try next, or "CLOSED: [reason]"]
65	```
66
67	## The Loop
68
69	### Phase 0: SET UP (first invocation only)
70
71	1. Create the scratch directory structure
72	2. Capture the baseline output — either from the user's clipboard/description, or by running the command
73	3. Write `run_command.txt` with the exact command that produces the output
74	4. Write `loop.md` with initial state
75	5. Proceed to Phase 1
76
77	### Phase 1: OBSERVE
78
79	Delegate critique to a subagent (sonnet). The subagent reads the current output and produces a structured critique. The main conversation does NOT read the full output — only the critique summary.
80
81	```
82	Task(model: sonnet, subagent_type: general-purpose)
83
84	Read <scratch_dir>/[baseline or iter-N]/output.md
85
86	Produce a structured critique:
87	1. STRENGTHS: What's working well (keep these)
88	2. WEAKNESSES: What's not working, ranked by impact
89	3. MISSING: What should be there but isn't
90	4. EXCESS: What's there but shouldn't be (noise, fluff, wrong focus)
91	5. ROOT ISSUE: The single biggest thing to fix (not a list — pick one)
92
93	Write your critique to <scratch_dir>/[baseline or iter-N]/critique.md
94	Return a 3-line summary: the root issue, the top weakness, and one strength to preserve.
95	```
96
97	### Phase 2: HYPOTHESIZE
98
99	Based on the critique summary (not the full output), form a hypothesis. This happens in the main conversation — it's a judgment call, not mechanical work.
100
101	Write to `<scratch_dir>/iter-N/hypothesis.md`:
102
103	```markdown
104	# Hypothesis for Iteration N
105
106	## What to change
107	[Specific change — which file, which prompt section, which config value]
108
109	## Why this should help
110	[Connect the change to the root issue from the critique]
111
112	## What to watch for
113	[Side effects — things that might get worse when this gets better]
114
115	## Estimated impact
116	[High / Medium / Low — on the specific quality signal defined in loop.md]
117	```
118
119	The hypothesis must be specific enough that someone else could

People who liked this also viewed

6 picks

Type

hk-refine

84stars12forks

View on GitHub

How to install hk-refine?

deepklarity/harness-kit/hk-refine

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /hk-refine — Iterative Output Refinement
2
3	You have an open loop: something produced output, the output isn't good enough, and you need to systematically improve it. This skill closes that loop.
4
5	The core discipline: everything lives on disk, not in conversation context. The scratch directory is the organized record of what was tried, what worked, and why. Subagents read from disk, write to disk, and report back in 2-3 line summaries. The main conversation only holds the current hypothesis and verdict — never full outputs.
6
7	## Context
8
9	<loop_context> $ARGUMENTS </loop_context>
10
11	If the context above is empty or unclear, ask the user:
12	1. What produced the output? (command, prompt, pipeline step)
13	2. What's wrong with it? (vague is ok — "it's not good enough" is a valid start)
14	3. Where should the scratch directory live? (suggest `temp_reflections/` or `temp_loop/`)
15
16	## The Scratch Directory
17
18	This is the product. Not temp files — the organized log of the refinement process.
19
20	```
21	<scratch_dir>/
22	├── loop.md # Live loop state (see template below)
23	├── baseline/
24	│ ├── output.md # Original output that needs improvement
25	│ ├── critique.md # Structured critique of what's wrong
26	│ └── run_command.txt # Exact command/process that produced the output
27	├── iter-1/
28	│ ├── hypothesis.md # What to change and why
29	│ ├── changes.md # What was actually changed (with file paths and diffs)
30	│ ├── output.md # New output after changes
31	│ ├── comparison.md # Before vs after, structured
32	│ └── verdict.md # Better / worse / mixed — with evidence
33	├── iter-2/
34	│ └── ...
35	└── summary.md # Written when loop closes
36	```
37
38	### loop.md template
39
40	This file is the single source of truth for where the loop is. Read it at the start of every iteration. Update it after every verdict.
41
42	```markdown
43	# Close-the-Loop: [short description]
44
45	## Target
46	What we're improving: [one line]
47	Run command: [the exact command to re-run]
48	Quality signal: [how we know it's better — specific, measurable if possible]
49
50	## Current State
51	Iteration: [N]
52	Best so far: [baseline \| iter-N]
53	Status: [observing \| hypothesizing \| changing \| running \| comparing \| closed]
54
55	## Hypothesis Log
56	- iter-1: [hypothesis] → [verdict: better/worse/mixed]
57	- iter-2: [hypothesis] → [verdict]
58	- ...
59
60	## What We've Learned
61	- [Accumulated insights that carry forward — things that definitely help or definitely don't]
62
63	## Next
64	[What to try next, or "CLOSED: [reason]"]
65	```
66
67	## The Loop
68
69	### Phase 0: SET UP (first invocation only)
70
71	1. Create the scratch directory structure
72	2. Capture the baseline output — either from the user's clipboard/description, or by running the command
73	3. Write `run_command.txt` with the exact command that produces the output
74	4. Write `loop.md` with initial state
75	5. Proceed to Phase 1
76
77	### Phase 1: OBSERVE
78
79	Delegate critique to a subagent (sonnet). The subagent reads the current output and produces a structured critique. The main conversation does NOT read the full output — only the critique summary.
80
81	```
82	Task(model: sonnet, subagent_type: general-purpose)
83
84	Read <scratch_dir>/[baseline or iter-N]/output.md
85
86	Produce a structured critique:
87	1. STRENGTHS: What's working well (keep these)
88	2. WEAKNESSES: What's not working, ranked by impact
89	3. MISSING: What should be there but isn't
90	4. EXCESS: What's there but shouldn't be (noise, fluff, wrong focus)
91	5. ROOT ISSUE: The single biggest thing to fix (not a list — pick one)
92
93	Write your critique to <scratch_dir>/[baseline or iter-N]/critique.md
94	Return a 3-line summary: the root issue, the top weakness, and one strength to preserve.
95	```
96
97	### Phase 2: HYPOTHESIZE
98
99	Based on the critique summary (not the full output), form a hypothesis. This happens in the main conversation — it's a judgment call, not mechanical work.
100
101	Write to `<scratch_dir>/iter-N/hypothesis.md`:
102
103	```markdown
104	# Hypothesis for Iteration N
105
106	## What to change
107	[Specific change — which file, which prompt section, which config value]
108
109	## Why this should help
110	[Connect the change to the root issue from the critique]
111
112	## What to watch for
113	[Side effects — things that might get worse when this gets better]
114
115	## Estimated impact
116	[High / Medium / Low — on the specific quality signal defined in loop.md]
117	```
118
119	The hypothesis must be specific enough that someone else could

People who liked this also viewed

6 picks

Type