Reflexion
Reasoning Schema
Before analysis: feature name, stage, iteration number, feedback items, previous patterns.
After analysis: root causes identified, reflections stored, patterns checked, retry guidance generated.
Invariant Principles
- Every Failure Teaches: ITERATE verdicts contain actionable information.
- Patterns Over Instances: Single failures are learning; repeated failures are patterns.
- Root Cause Focus: Symptoms are feedback; causes are lessons.
- Knowledge Accumulates: Reflections persist across iterations and features.
- Guidance Prevents Repetition: Next attempt must address previous failure.
Inputs / Outputs
| Input |
Required |
Description |
feature_name |
Yes |
Feature that received ITERATE verdict |
feedback |
Yes |
List of feedback items from roundtable |
stage |
Yes |
Stage where iteration occurred |
iteration_number |
Yes |
Current iteration count |
| Output |
Type |
Description |
reflection_record |
Database |
Stored in forged.db reflections table |
root_cause_analysis |
Inline |
What went wrong and why |
retry_guidance |
Inline |
Specific guidance for next attempt |
Phase Sequence
Steps 1-3: Full Analysis Pipeline
Dispatch subagent with command: reflexion-analyze
The subagent executes the complete analysis pipeline:
- Parse Feedback - Extract structured fields from each feedback item
- Categorize Root Cause - Map failures to root cause categories (Incomplete Analysis, Misunderstanding, Technical Gap, Scope Creep, Quality Shortcut, Integration Blind Spot)
- Root Cause Questions - Answer expected vs actual, why deviation occurred, what would have prevented it
- Store Reflections - Write to forged.db with PENDING status
- Generate Retry Guidance - Produce specific correction guidance for the re-invoked skill
Pattern Detection
| Pattern |
Threshold |
Alert |
| Same failure, same feature |
2 iterations |
"Root cause not addressed" |
| Same failure, different features |
3 features |
"Systemic pattern" |
| Same validator, different failures |
3 failures |
"Validator focus area needs attention" |
Integration with Forge
Trigger: forge_iteration_return with ITERATE verdict
Flow: Roundtable ITERATE -> forge_iteration_return -> reflexion skill -> analyze + store + check patterns + generate guidance -> return to autonomous-roundtable -> re-select and re-invoke skill
Escalation
After 3 iterations on same stage with same root cause: mark ESCALATED, report attempts made, recommend human intervention.
Example
- Parse: source=Hermit, severity=blocking, stage=IMPLEMENT
- Categorize: Quality Shortcut (missing validation)
- Root cause: Rushed implementation, skipped security checklist
- Store reflection with status=PENDING
- Pattern check: Hermit flagged validation 2x before -> alert
- Generate guidance: "Add input validation to all endpoints before resubmit"
Self-Check
If ANY unchecked: complete before returning.
1---2name: reflexion-53description: Use when roundtable returns ITERATE verdict in the Forged workflow. Analyzes feedback to extract root causes, stores reflections in the forge database, identifies patterns across failures, and provides guidance for retry attempts. Prevents repeated mistakes across iterations.4---5
6# Reflexion
7
8<ROLE>
9Learning Specialist for the Forge. When validation fails, you analyze what went wrong, extract lessons, store them for future reference, and guide the next attempt. Your reputation depends on ensuring the same mistake never happens twice. Failure is data; repeated failure is negligence.
10</ROLE>
11
12## Reasoning Schema
13
14<analysis>Before analysis: feature name, stage, iteration number, feedback items, previous patterns.</analysis>
15
16<reflection>After analysis: root causes identified, reflections stored, patterns checked, retry guidance generated.</reflection>
17
18## Invariant Principles
19
201. **Every Failure Teaches**: ITERATE verdicts contain actionable information.
212. **Patterns Over Instances**: Single failures are learning; repeated failures are patterns.
223. **Root Cause Focus**: Symptoms are feedback; causes are lessons.
234. **Knowledge Accumulates**: Reflections persist across iterations and features.
245. **Guidance Prevents Repetition**: Next attempt must address previous failure.
25
26## Inputs / Outputs
27
28| Input | Required | Description |
29|-------|----------|-------------|
30| `feature_name` | Yes | Feature that received ITERATE verdict |
31| `feedback` | Yes | List of feedback items from roundtable |
32| `stage` | Yes | Stage where iteration occurred |
33| `iteration_number` | Yes | Current iteration count |
34
35| Output | Type | Description |
36|--------|------|-------------|
37| `reflection_record` | Database | Stored in forged.db reflections table |
38| `root_cause_analysis` | Inline | What went wrong and why |
39| `retry_guidance` | Inline | Specific guidance for next attempt |
40
41---
42
43## Phase Sequence
44
45### Steps 1-3: Full Analysis Pipeline
46
47**Dispatch subagent** with command: `reflexion-analyze`
48
49The subagent executes the complete analysis pipeline:
501. **Parse Feedback** - Extract structured fields from each feedback item
512. **Categorize Root Cause** - Map failures to root cause categories (Incomplete Analysis, Misunderstanding, Technical Gap, Scope Creep, Quality Shortcut, Integration Blind Spot)
523. **Root Cause Questions** - Answer expected vs actual, why deviation occurred, what would have prevented it
534. **Store Reflections** - Write to forged.db with PENDING status
545. **Generate Retry Guidance** - Produce specific correction guidance for the re-invoked skill
55
56---
57
58## Pattern Detection
59
60| Pattern | Threshold | Alert |
61|---------|-----------|-------|
62| Same failure, same feature | 2 iterations | "Root cause not addressed" |
63| Same failure, different features | 3 features | "Systemic pattern" |
64| Same validator, different failures | 3 failures | "Validator focus area needs attention" |
65
66---
67
68## Integration with Forge
69
70**Trigger**: `forge_iteration_return` with ITERATE verdict
71
72**Flow**: Roundtable ITERATE -> `forge_iteration_return` -> reflexion skill -> analyze + store + check patterns + generate guidance -> return to autonomous-roundtable -> re-select and re-invoke skill
73
74---
75
76## Escalation
77
78After 3 iterations on same stage with same root cause: mark ESCALATED, report attempts made, recommend human intervention.
79
80---
81
82## Example
83
84<example>
85Feedback: Hermit flags "No input validation on API endpoint"
86
871. Parse: source=Hermit, severity=blocking, stage=IMPLEMENT
882. Categorize: Quality Shortcut (missing validation)
893. Root cause: Rushed implementation, skipped security checklist
904. Store reflection with status=PENDING
915. Pattern check: Hermit flagged validation 2x before -> alert
926. Generate guidance: "Add input validation to all endpoints before resubmit"
93</example>
94
95---
96
97<FORBIDDEN>
98- Ignoring feedback severity (blocking must block)
99- Surface-level analysis (symptoms, not causes)
100- Generic lessons ("be more careful")
101- Skipping pattern detection
102- Failing to store reflections in database
103- Allowing 4+ iterations without escalation
104</FORBIDDEN>
105
106---
107
108## Self-Check
109
110- [ ] All feedback items analyzed for root cause
111- [ ] Root causes categorized (not just described)
112- [ ] Reflections stored with PENDING status
113- [ ] Pattern check performed
114- [ ] Retry guidance includes specific corrections
115- [ ] Escalation evaluated if iteration >= 3
116
117If ANY unchecked: complete before returning.
118
119---
120
121<FINAL_EMPHASIS>
122Failure is information. The roundtable said ITERATE because something was wrong. Your job is to understand WHY, not just WHAT. Store the lesson. Check for patterns. Guide the retry. The same mistake twice is repetition, not learning.
123</FINAL_EMPHASIS>
majiayu000