improvement-loop

Name: improvement-loop
Author: aaddrick

120stars16forks

How to install improvement-loop?

aaddrick/claude-pipeline/improvement-loop

$npx -y skills add aaddrick/claude-pipeline --skill improvement-loop

Installs into the current project.

Summary

Use after resolving a bug, failed task, or unexpected agent behavior to improve the pipeline skills, agents, hooks, or scripts that contributed to the problem. Also proactively suggest improvements when recurring patterns or inefficiencies are observed.

Files · 1

View on GitHub

SKILL.md

1	# The Improvement Loop
2
3	## Overview
4
5	Improve the `.claude/` pipeline after resolving the issue at hand — never during. When a skill, agent, hook, or script produces bad output, work through to the correct solution first, then update the pipeline with what you learned.
6
7	Core principle: Fix first, understand fully, improve last. Premature edits encode partial understanding.
8
9	## When to Use
10
11	```dot
12	digraph when_to_use {
13	"Issue resolved successfully?" [shape=diamond];
14	"Root cause in pipeline file?" [shape=diamond];
15	"Worth encoding permanently?" [shape=diamond];
16	"Run improvement cycle" [shape=box style=filled fillcolor=lightgreen];
17	"Keep working on the issue" [shape=box];
18	"Skip - not a pipeline problem" [shape=box];
19	"Skip - one-off or too specific" [shape=box];
20
21	"Issue resolved successfully?" -> "Root cause in pipeline file?" [label="yes"];
22	"Issue resolved successfully?" -> "Keep working on the issue" [label="no - finish first"];
23	"Root cause in pipeline file?" -> "Worth encoding permanently?" [label="yes"];
24	"Root cause in pipeline file?" -> "Skip - not a pipeline problem" [label="no"];
25	"Worth encoding permanently?" -> "Run improvement cycle" [label="yes"];
26	"Worth encoding permanently?" -> "Skip - one-off or too specific" [label="no"];
27	}
28	```
29
30	Trigger conditions (suggest to user):
31	- An agent produced incorrect output that required manual correction
32	- A skill was missing guidance that caused a wrong approach
33	- The same mistake has occurred more than once across sessions
34	- A hook failed to catch something it should have
35	- An orchestration script hit an unhandled edge case
36	- A subagent asked questions that the agent definition should have answered
37	- Review feedback repeatedly flags the same class of issue
38
39	Do NOT trigger:
40	- While still debugging or iterating on the original issue
41	- For one-off problems unlikely to recur
42	- For issues outside the pipeline (user error, external service failures)
43	- When the fix is a code change, not a pipeline change
44
45	## The Gate: Is the Issue Resolved?
46
47	This check is mandatory before any improvement work.
48
49	```dot
50	digraph gate_check {
51	"Original task/issue complete?" [shape=diamond];
52	"Tests passing?" [shape=diamond];
53	"User confirmed resolution?" [shape=diamond];
54	"GATE PASSED - proceed to improvement" [shape=box style=filled fillcolor=lightgreen];
55	"STOP - return to the issue" [shape=box style=filled fillcolor=salmon];
56
57	"Original task/issue complete?" -> "Tests passing?" [label="yes"];
58	"Original task/issue complete?" -> "STOP - return to the issue" [label="no"];
59	"Tests passing?" -> "User confirmed resolution?" [label="yes"];
60	"Tests passing?" -> "STOP - return to the issue" [label="no"];
61	"User confirmed resolution?" -> "GATE PASSED - proceed to improvement" [label="yes"];
62	"User confirmed resolution?" -> "STOP - return to the issue" [label="no/unclear"];
63	}
64	```
65
66	Verify ALL of these before proceeding:
67	1. The original task or issue is functionally complete
68	2. All tests pass (or the fix is committed and verified)
69	3. The user considers the issue resolved (ask if unclear)
70
71	If ANY check fails, stop. Return to the issue. Do not start improvement work.
72
73	## Proactive Detection
74
75	When you observe improvement opportunities during normal work, do not act immediately. Instead:
76
77	1. Note the opportunity — mentally flag what went wrong and which pipeline file is involved
78	2. Finish the current task — complete whatever you're working on
79	3. Ask the user — suggest the improvement explicitly:
80
81	```
82	I noticed [specific problem] while working on [task]. The root cause appears to be
83	[skill/agent/hook/script name] which [lacks guidance on X / has an anti-pattern gap /
84	doesn't handle Y].
85
86	Would you like me to run an improvement cycle to update it? This would involve:
87	- [Specific change: e.g., "adding an anti-pattern entry for Model::all()"]
88	- [Estimated scope: e.g., "a one-line addition to the agent's anti-patterns section"]
89	```
90
91	Always ask before starting. The user may want to defer, batch improvements, or handle it differently.
92
93	## The Five-Step Cycle
94
95	### Step 1: Capture the Problem
96
97	Document what happened before details fade:
98	- What went wrong: The specific incorrect output or behavior
99	- Which pipeline file: The skill, agent, hook, or script involved
100	- Root cause: Why the pipeline file led to the wrong outcome
101	- Correct solution: What the right approach turned out to be
102	- How you discovered it: The debugging path (helps write better guidance)
103
104	### Step 2: Classify the Improvement
105
106	\| Type \| Target \| Example \|
107	\|------\|--------\|---------\|
108	\| Anti-pattern \| Agent

People who liked this also viewed

6 picks

Type

improvement-loop

120stars16forks

View on GitHub

How to install improvement-loop?

aaddrick/claude-pipeline/improvement-loop

$npx -y skills add aaddrick/claude-pipeline --skill improvement-loop

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# The Improvement Loop
2
3	## Overview
4
5	Improve the `.claude/` pipeline after resolving the issue at hand — never during. When a skill, agent, hook, or script produces bad output, work through to the correct solution first, then update the pipeline with what you learned.
6
7	Core principle: Fix first, understand fully, improve last. Premature edits encode partial understanding.
8
9	## When to Use
10
11	```dot
12	digraph when_to_use {
13	"Issue resolved successfully?" [shape=diamond];
14	"Root cause in pipeline file?" [shape=diamond];
15	"Worth encoding permanently?" [shape=diamond];
16	"Run improvement cycle" [shape=box style=filled fillcolor=lightgreen];
17	"Keep working on the issue" [shape=box];
18	"Skip - not a pipeline problem" [shape=box];
19	"Skip - one-off or too specific" [shape=box];
20
21	"Issue resolved successfully?" -> "Root cause in pipeline file?" [label="yes"];
22	"Issue resolved successfully?" -> "Keep working on the issue" [label="no - finish first"];
23	"Root cause in pipeline file?" -> "Worth encoding permanently?" [label="yes"];
24	"Root cause in pipeline file?" -> "Skip - not a pipeline problem" [label="no"];
25	"Worth encoding permanently?" -> "Run improvement cycle" [label="yes"];
26	"Worth encoding permanently?" -> "Skip - one-off or too specific" [label="no"];
27	}
28	```
29
30	Trigger conditions (suggest to user):
31	- An agent produced incorrect output that required manual correction
32	- A skill was missing guidance that caused a wrong approach
33	- The same mistake has occurred more than once across sessions
34	- A hook failed to catch something it should have
35	- An orchestration script hit an unhandled edge case
36	- A subagent asked questions that the agent definition should have answered
37	- Review feedback repeatedly flags the same class of issue
38
39	Do NOT trigger:
40	- While still debugging or iterating on the original issue
41	- For one-off problems unlikely to recur
42	- For issues outside the pipeline (user error, external service failures)
43	- When the fix is a code change, not a pipeline change
44
45	## The Gate: Is the Issue Resolved?
46
47	This check is mandatory before any improvement work.
48
49	```dot
50	digraph gate_check {
51	"Original task/issue complete?" [shape=diamond];
52	"Tests passing?" [shape=diamond];
53	"User confirmed resolution?" [shape=diamond];
54	"GATE PASSED - proceed to improvement" [shape=box style=filled fillcolor=lightgreen];
55	"STOP - return to the issue" [shape=box style=filled fillcolor=salmon];
56
57	"Original task/issue complete?" -> "Tests passing?" [label="yes"];
58	"Original task/issue complete?" -> "STOP - return to the issue" [label="no"];
59	"Tests passing?" -> "User confirmed resolution?" [label="yes"];
60	"Tests passing?" -> "STOP - return to the issue" [label="no"];
61	"User confirmed resolution?" -> "GATE PASSED - proceed to improvement" [label="yes"];
62	"User confirmed resolution?" -> "STOP - return to the issue" [label="no/unclear"];
63	}
64	```
65
66	Verify ALL of these before proceeding:
67	1. The original task or issue is functionally complete
68	2. All tests pass (or the fix is committed and verified)
69	3. The user considers the issue resolved (ask if unclear)
70
71	If ANY check fails, stop. Return to the issue. Do not start improvement work.
72
73	## Proactive Detection
74
75	When you observe improvement opportunities during normal work, do not act immediately. Instead:
76
77	1. Note the opportunity — mentally flag what went wrong and which pipeline file is involved
78	2. Finish the current task — complete whatever you're working on
79	3. Ask the user — suggest the improvement explicitly:
80
81	```
82	I noticed [specific problem] while working on [task]. The root cause appears to be
83	[skill/agent/hook/script name] which [lacks guidance on X / has an anti-pattern gap /
84	doesn't handle Y].
85
86	Would you like me to run an improvement cycle to update it? This would involve:
87	- [Specific change: e.g., "adding an anti-pattern entry for Model::all()"]
88	- [Estimated scope: e.g., "a one-line addition to the agent's anti-patterns section"]
89	```
90
91	Always ask before starting. The user may want to defer, batch improvements, or handle it differently.
92
93	## The Five-Step Cycle
94
95	### Step 1: Capture the Problem
96
97	Document what happened before details fade:
98	- What went wrong: The specific incorrect output or behavior
99	- Which pipeline file: The skill, agent, hook, or script involved
100	- Root cause: Why the pipeline file led to the wrong outcome
101	- Correct solution: What the right approach turned out to be
102	- How you discovered it: The debugging path (helps write better guidance)
103
104	### Step 2: Classify the Improvement
105
106	\| Type \| Target \| Example \|
107	\|------\|--------\|---------\|
108	\| Anti-pattern \| Agent

People who liked this also viewed

6 picks

Type