feat: implement reflection phase with /reflect skill and enriched reflector hat

Replace the /reflect stub with a full skill that analyzes completed HAIKU
execution cycles, produces reflection.md artifacts with evidence-based
metrics, and offers iterate (intent versioning) or close (organizational
memory) paths. Enrich the reflector hat with structured analysis steps,
targeted user questions, and strict evidence grounding requirements.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jwaldrip

haiku-plugin/hats/reflector.md

@@ -1,73 +1,175 @@
 ---
 name: "Reflector"
-description: Analyzes outcomes and captures learnings for continuous improvement
+description: Analyzes execution outcomes and captures evidence-based learnings for continuous improvement
 ---
 
 # Reflector
 
 ## Overview
 
-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.
+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.
 
 ## Parameters
 
-- **Unit**: {unit} - The Unit being reflected upon
-- **Iteration History**: {history} - Record of iterations and decisions
+- **Intent**: {intent} - The Intent being reflected upon
+- **Units**: {units} - All unit specs and their completion status
+- **Iteration History**: {history} - Record of iterations, hat transitions, and decisions
+- **Operational Outcomes**: {operations} - Results from operational tasks (if applicable)
 - **Blockers Encountered**: {blockers} - Issues faced during execution
 
 ## Prerequisites
 
 ### Required Context
 
 - Executor and Operator (if applicable) have completed work
-- Iteration history and scratchpad available
+- All unit files accessible with final statuses
+- Iteration state and scratchpad data available
 - Blocker records available
+- Operational plan and status available (if workflow includes operator)
 
 ### Required State
 
-- Execution results accessible
-- Previous iteration data loaded
+- Intent directory exists with all artifacts
+- Iteration state loaded from storage
+- Operation status loaded (if applicable)
 
 ## Steps
 
-1. Review iteration history
-   - You MUST review all iterations for this Unit
-   - You MUST identify patterns in successes and failures
-   - **Validation**: Iteration patterns documented
-
-2. Analyze outcomes
-   - You MUST compare planned work against actual results
-   - You MUST identify deviations and their causes
-   - You SHOULD quantify effort where possible
-   - **Validation**: Outcome analysis complete
-
-3. Capture learnings
-   - You MUST document what approaches worked
-   - You MUST document what approaches failed and why
-   - You SHOULD extract reusable patterns or techniques
-   - **Validation**: Learnings documented
-
-4. Suggest improvements
-   - You SHOULD propose process improvements for future work
-   - You SHOULD identify recurring blockers that need systemic fixes
-   - You MAY suggest changes to completion criteria patterns
-   - **Validation**: Improvement suggestions documented
-
-5. Save reflection artifacts
-   - You MUST save reflection to state storage
-   - You SHOULD structure findings for easy reference
-   - **Validation**: Reflection artifacts saved and accessible
+1. Read all execution artifacts
+   - You MUST read `intent.md` for success criteria and scope
+   - You MUST read every `unit-*.md` file for status and completion criteria
+   - You MUST read iteration state from `iteration.json`
+   - You MUST read scratchpad data for each unit (if available)
+   - You SHOULD read `operations.md` and `operation-status.json` if they exist
+   - You SHOULD read `completion-criteria.md` if it exists
+   - **Validation**: All available artifacts loaded
+
+2. Compute execution metrics
+   - You MUST count: units completed vs total, total iterations, workflow used
+   - You MUST identify: retries per unit (from iteration count and hat transitions)
+   - You SHOULD quantify: blocker count, quality gate pass rates (if data available)
+   - You MUST NOT fabricate metrics -- only report what the data supports
+   - **Validation**: Metrics are grounded in artifact data
+
+3. Identify what worked
+   - You MUST cite specific evidence for each positive finding
+   - You MUST look for: units that completed smoothly, approaches that succeeded on first try, effective patterns in execution
+   - You SHOULD identify: process decisions that paid off, good decomposition choices
+   - **Validation**: Each finding has a citation to a specific artifact or metric
+
+4. Identify what didn't work
+   - You MUST cite specific evidence for each negative finding
+   - You MUST look for: units that required multiple retries, recurring blockers, criteria that were hard to satisfy
+   - You SHOULD identify: process friction, unclear specifications, missing context
+   - You MUST propose a concrete improvement for each problem identified
+   - **Validation**: Each finding has evidence and a proposed improvement
+
+5. Analyze operational outcomes
+   - You MUST review operational task performance (if applicable)
+   - You MUST identify: tasks that succeeded/failed, gaps in operational coverage
+   - You SHOULD assess: whether the operational plan was sufficient
+   - **Validation**: Operational analysis complete (or noted as N/A)
+
+6. Distill key learnings
+   - You MUST extract actionable insights that apply beyond this specific intent
+   - You MUST distinguish between: intent-specific observations and generalizable patterns
+   - You SHOULD frame learnings as reusable guidelines
+   - **Validation**: Learnings are actionable and generalizable
+
+7. Produce recommendations
+   - You MUST provide specific, actionable recommendations
+   - You MUST prioritize recommendations (most impactful first)
+   - You SHOULD categorize: process improvements, technical improvements, tooling improvements
+   - **Validation**: Recommendations are specific and prioritized
+
+8. Ask targeted questions
+   - You MUST present your analysis to the user before finalizing
+   - You MUST ask specific questions to surface observations the agent missed:
+     - "Were there any difficulties not captured in the artifacts?"
+     - "Did the decomposition into units feel right, or should it change?"
+     - "Are there learnings from your perspective that should be captured?"
+   - You MUST NOT ask vague or generic questions
+   - **Validation**: User has validated findings and added observations
+
+9. Write reflection.md
+   - You MUST write the reflection artifact to `.haiku/{intent-slug}/reflection.md`
+   - You MUST use the standard reflection format (see Format section below)
+   - You MUST incorporate user feedback into the final artifact
+   - **Validation**: reflection.md written with all sections populated
+
+## Reflection Format
+
+```markdown
+---
+intent: {intent-slug}
+version: 1
+created: {ISO date}
+status: complete
+---
+
+# Reflection: {Intent Title}
+
+## Execution Summary
+- Units completed: N/M
+- Total iterations: X
+- Workflow: {workflow name}
+- Blockers encountered: Z
+
+## What Worked
+- {Specific thing with evidence}
+
+## What Didn't Work
+- {Specific thing with proposed improvement}
+
+## Operational Outcomes
+- {How operational tasks performed}
+
+## Key Learnings
+- {Distilled actionable insight}
+
+## Recommendations
+- [ ] {Specific recommendation}
+
+## Next Iteration Seed
+{What v2 should focus on}
+```
 
 ## Success Criteria
 
-- [ ] Iteration patterns identified
-- [ ] Outcome analysis complete (planned vs actual)
-- [ ] Learnings captured (successes and failures)
-- [ ] Improvement suggestions documented
-- [ ] Reflection artifacts saved
+- [ ] All execution artifacts read and analyzed
+- [ ] Execution metrics computed from actual data (not fabricated)
+- [ ] What-worked analysis grounded in evidence
+- [ ] What-didn't-work analysis includes proposed improvements
+- [ ] Operational outcomes assessed (if applicable)
+- [ ] Key learnings are actionable and generalizable
+- [ ] Recommendations are specific and prioritized
+- [ ] User has validated and augmented findings
+- [ ] reflection.md written with all sections
+
+## Error Handling
+
+### Error: Incomplete Execution Data
+
+**Symptoms**: Some units never executed, missing state data
+
+**Resolution**:
+1. You MUST note which data is missing and why
+2. You MUST analyze what is available
+3. You SHOULD flag gaps as a finding (incomplete execution is itself a learning)
+4. You MUST NOT fabricate data to fill gaps
+
+### Error: No Operational Data
+
+**Symptoms**: Workflow did not include operator, no operations.md
+
+**Resolution**:
+1. You MUST note that operational analysis is N/A for this workflow
+2. You SHOULD still consider operational implications if relevant
+3. You MUST skip the Operational Outcomes section or mark it N/A
 
 ## Related Hats
 
 - **Executor**: Produced the work being reflected upon
-- **Operator**: Provided operational perspective
+- **Operator**: Provided operational perspective and outcomes
 - **Planner**: Will benefit from learnings in future planning
+- **Reviewer**: Verified work quality during execution