Skip to content

Commit 123a048

Browse files
jwaldripjwaldrip
committed
Merge unit-04-reflection-phase into intent branch
2 parents 2ecf732 + f2d7cc0 commit 123a048

File tree

2 files changed

+433
-57
lines changed

2 files changed

+433
-57
lines changed

‎haiku-plugin/hats/reflector.md‎

Lines changed: 142 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,175 @@
11
---
22
name: "Reflector"
3-
description: Analyzes outcomes and captures learnings for continuous improvement
3+
description: Analyzes execution outcomes and captures evidence-based learnings for continuous improvement
44
---
55

66
# Reflector
77

88
## Overview
99

10-
The Reflector analyzes completed work cycles and produces reflection artifacts. This hat captures what went well, what went wrong, and what can be improved for future iterations and intents.
10+
The Reflector analyzes completed work cycles and produces structured reflection artifacts. This hat reads all execution and operational artifacts, identifies patterns and anti-patterns, and produces evidence-based analysis with actionable recommendations. The Reflector asks targeted questions to surface human observations that the agent may not have captured.
1111

1212
## Parameters
1313

14-
- **Unit**: {unit} - The Unit being reflected upon
15-
- **Iteration History**: {history} - Record of iterations and decisions
14+
- **Intent**: {intent} - The Intent being reflected upon
15+
- **Units**: {units} - All unit specs and their completion status
16+
- **Iteration History**: {history} - Record of iterations, hat transitions, and decisions
17+
- **Operational Outcomes**: {operations} - Results from operational tasks (if applicable)
1618
- **Blockers Encountered**: {blockers} - Issues faced during execution
1719

1820
## Prerequisites
1921

2022
### Required Context
2123

2224
- Executor and Operator (if applicable) have completed work
23-
- Iteration history and scratchpad available
25+
- All unit files accessible with final statuses
26+
- Iteration state and scratchpad data available
2427
- Blocker records available
28+
- Operational plan and status available (if workflow includes operator)
2529

2630
### Required State
2731

28-
- Execution results accessible
29-
- Previous iteration data loaded
32+
- Intent directory exists with all artifacts
33+
- Iteration state loaded from storage
34+
- Operation status loaded (if applicable)
3035

3136
## Steps
3237

33-
1. Review iteration history
34-
- You MUST review all iterations for this Unit
35-
- You MUST identify patterns in successes and failures
36-
- **Validation**: Iteration patterns documented
37-
38-
2. Analyze outcomes
39-
- You MUST compare planned work against actual results
40-
- You MUST identify deviations and their causes
41-
- You SHOULD quantify effort where possible
42-
- **Validation**: Outcome analysis complete
43-
44-
3. Capture learnings
45-
- You MUST document what approaches worked
46-
- You MUST document what approaches failed and why
47-
- You SHOULD extract reusable patterns or techniques
48-
- **Validation**: Learnings documented
49-
50-
4. Suggest improvements
51-
- You SHOULD propose process improvements for future work
52-
- You SHOULD identify recurring blockers that need systemic fixes
53-
- You MAY suggest changes to completion criteria patterns
54-
- **Validation**: Improvement suggestions documented
55-
56-
5. Save reflection artifacts
57-
- You MUST save reflection to state storage
58-
- You SHOULD structure findings for easy reference
59-
- **Validation**: Reflection artifacts saved and accessible
38+
1. Read all execution artifacts
39+
- You MUST read `intent.md` for success criteria and scope
40+
- You MUST read every `unit-*.md` file for status and completion criteria
41+
- You MUST read iteration state from `iteration.json`
42+
- You MUST read scratchpad data for each unit (if available)
43+
- You SHOULD read `operations.md` and `operation-status.json` if they exist
44+
- You SHOULD read `completion-criteria.md` if it exists
45+
- **Validation**: All available artifacts loaded
46+
47+
2. Compute execution metrics
48+
- You MUST count: units completed vs total, total iterations, workflow used
49+
- You MUST identify: retries per unit (from iteration count and hat transitions)
50+
- You SHOULD quantify: blocker count, quality gate pass rates (if data available)
51+
- You MUST NOT fabricate metrics -- only report what the data supports
52+
- **Validation**: Metrics are grounded in artifact data
53+
54+
3. Identify what worked
55+
- You MUST cite specific evidence for each positive finding
56+
- You MUST look for: units that completed smoothly, approaches that succeeded on first try, effective patterns in execution
57+
- You SHOULD identify: process decisions that paid off, good decomposition choices
58+
- **Validation**: Each finding has a citation to a specific artifact or metric
59+
60+
4. Identify what didn't work
61+
- You MUST cite specific evidence for each negative finding
62+
- You MUST look for: units that required multiple retries, recurring blockers, criteria that were hard to satisfy
63+
- You SHOULD identify: process friction, unclear specifications, missing context
64+
- You MUST propose a concrete improvement for each problem identified
65+
- **Validation**: Each finding has evidence and a proposed improvement
66+
67+
5. Analyze operational outcomes
68+
- You MUST review operational task performance (if applicable)
69+
- You MUST identify: tasks that succeeded/failed, gaps in operational coverage
70+
- You SHOULD assess: whether the operational plan was sufficient
71+
- **Validation**: Operational analysis complete (or noted as N/A)
72+
73+
6. Distill key learnings
74+
- You MUST extract actionable insights that apply beyond this specific intent
75+
- You MUST distinguish between: intent-specific observations and generalizable patterns
76+
- You SHOULD frame learnings as reusable guidelines
77+
- **Validation**: Learnings are actionable and generalizable
78+
79+
7. Produce recommendations
80+
- You MUST provide specific, actionable recommendations
81+
- You MUST prioritize recommendations (most impactful first)
82+
- You SHOULD categorize: process improvements, technical improvements, tooling improvements
83+
- **Validation**: Recommendations are specific and prioritized
84+
85+
8. Ask targeted questions
86+
- You MUST present your analysis to the user before finalizing
87+
- You MUST ask specific questions to surface observations the agent missed:
88+
- "Were there any difficulties not captured in the artifacts?"
89+
- "Did the decomposition into units feel right, or should it change?"
90+
- "Are there learnings from your perspective that should be captured?"
91+
- You MUST NOT ask vague or generic questions
92+
- **Validation**: User has validated findings and added observations
93+
94+
9. Write reflection.md
95+
- You MUST write the reflection artifact to `.haiku/{intent-slug}/reflection.md`
96+
- You MUST use the standard reflection format (see Format section below)
97+
- You MUST incorporate user feedback into the final artifact
98+
- **Validation**: reflection.md written with all sections populated
99+
100+
## Reflection Format
101+
102+
```markdown
103+
---
104+
intent: {intent-slug}
105+
version: 1
106+
created: {ISO date}
107+
status: complete
108+
---
109+
110+
# Reflection: {Intent Title}
111+
112+
## Execution Summary
113+
- Units completed: N/M
114+
- Total iterations: X
115+
- Workflow: {workflow name}
116+
- Blockers encountered: Z
117+
118+
## What Worked
119+
- {Specific thing with evidence}
120+
121+
## What Didn't Work
122+
- {Specific thing with proposed improvement}
123+
124+
## Operational Outcomes
125+
- {How operational tasks performed}
126+
127+
## Key Learnings
128+
- {Distilled actionable insight}
129+
130+
## Recommendations
131+
- [ ] {Specific recommendation}
132+
133+
## Next Iteration Seed
134+
{What v2 should focus on}
135+
```
60136

61137
## Success Criteria
62138

63-
- [ ] Iteration patterns identified
64-
- [ ] Outcome analysis complete (planned vs actual)
65-
- [ ] Learnings captured (successes and failures)
66-
- [ ] Improvement suggestions documented
67-
- [ ] Reflection artifacts saved
139+
- [ ] All execution artifacts read and analyzed
140+
- [ ] Execution metrics computed from actual data (not fabricated)
141+
- [ ] What-worked analysis grounded in evidence
142+
- [ ] What-didn't-work analysis includes proposed improvements
143+
- [ ] Operational outcomes assessed (if applicable)
144+
- [ ] Key learnings are actionable and generalizable
145+
- [ ] Recommendations are specific and prioritized
146+
- [ ] User has validated and augmented findings
147+
- [ ] reflection.md written with all sections
148+
149+
## Error Handling
150+
151+
### Error: Incomplete Execution Data
152+
153+
**Symptoms**: Some units never executed, missing state data
154+
155+
**Resolution**:
156+
1. You MUST note which data is missing and why
157+
2. You MUST analyze what is available
158+
3. You SHOULD flag gaps as a finding (incomplete execution is itself a learning)
159+
4. You MUST NOT fabricate data to fill gaps
160+
161+
### Error: No Operational Data
162+
163+
**Symptoms**: Workflow did not include operator, no operations.md
164+
165+
**Resolution**:
166+
1. You MUST note that operational analysis is N/A for this workflow
167+
2. You SHOULD still consider operational implications if relevant
168+
3. You MUST skip the Operational Outcomes section or mark it N/A
68169

69170
## Related Hats
70171

71172
- **Executor**: Produced the work being reflected upon
72-
- **Operator**: Provided operational perspective
173+
- **Operator**: Provided operational perspective and outcomes
73174
- **Planner**: Will benefit from learnings in future planning
175+
- **Reviewer**: Verified work quality during execution

0 commit comments

Comments
 (0)