| 1 | --- |
| 2 | name: reflect |
| 3 | description: Learning capture system that extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes. Use after user corrections ("no", "wrong"), praise ("perfect", "exactly"), or when discovering edge cases. Complements .squad/agents/{agent}/history.md and .squad/decisions.md. |
| 4 | license: MIT |
| 5 | version: 1.0.0-squad |
| 6 | domain: team-memory, learning |
| 7 | confidence: high |
| 8 | --- |
| 9 | |
| 10 | # Reflect Skill |
| 11 | |
| 12 | **Critical learning capture system** for Squad. Prevents repeating mistakes and preserves successful patterns across sessions. |
| 13 | |
| 14 | Analyze conversations and propose improvements to squad knowledge based on what worked, what didn't, and edge cases discovered. **Every correction is a learning opportunity.** |
| 15 | |
| 16 | --- |
| 17 | |
| 18 | ## Integration with Squad Architecture |
| 19 | |
| 20 | **Reflect complements existing Squad knowledge systems:** |
| 21 | |
| 22 | 1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (append-only; each agent updates their own file; Scribe propagates cross-agent updates) |
| 23 | 2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect |
| 24 | 3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md |
| 25 | |
| 26 | **Workflow:** |
| 27 | - Use `reflect` during work to capture learnings |
| 28 | - At session end, review captured learnings |
| 29 | - Promote HIGH confidence patterns → lead agent for decision.md review |
| 30 | - Promote agent-specific patterns → `{agent}/history.md` updates |
| 31 | |
| 32 | --- |
| 33 | |
| 34 | ## Triggers |
| 35 | |
| 36 | ### 🔴 HIGH Priority (Invoke Immediately) |
| 37 | |
| 38 | | Trigger | Example | Why Critical | |
| 39 | |---------|---------|--------------| |
| 40 | | User correction | "no", "wrong", "not like that", "never do" | Captures mistakes to prevent repetition | |
| 41 | | Architectural insight | "you removed that without understanding why" | Documents design decisions (Chesterton's Fence) | |
| 42 | | Immediate fixes | "debug", "root cause", "fix all" | Learns from errors in real-time | |
| 43 | |
| 44 | ### 🟡 MEDIUM Priority (Invoke After Multiple) |
| 45 | |
| 46 | | Trigger | Example | Why Important | |
| 47 | |---------|---------|---------------| |
| 48 | | User praise | "perfect", "exactly", "great" | Reinforces successful patterns | |
| 49 | | Tool preferences | "use X instead of Y", "prefer" | Builds workflow preferences | |
| 50 | | Edge cases | "what if X happens?", "don't forget", "ensure" | Captures scenarios to handle | |
| 51 | |
| 52 | ### 🟢 LOW Priority (Invoke at Session End) |
| 53 | |
| 54 | | Trigger | Example | Why Useful | |
| 55 | |---------|---------|------------| |
| 56 | | Repeated patterns | Frequent use of specific commands/tools | Identifies workflow preferences | |
| 57 | | Session end | After complex work | Consolidates all session learnings | |
| 58 | |
| 59 | --- |
| 60 | |
| 61 | ## Process |
| 62 | |
| 63 | ### Phase 1: Identify Learning Target |
| 64 | |
| 65 | Determine what knowledge system should be updated: |
| 66 | |
| 67 | 1. **Agent-specific learning** → `.squad/agents/{agent}/history.md` |
| 68 | 2. **Team-wide decision** → `.squad/decisions/inbox/{agent}-{topic}.md` |
| 69 | 3. **Skill-specific improvement** → Document in session, recommend to skill owner |
| 70 | |
| 71 | ### Phase 2: Analyze Conversation |
| 72 | |
| 73 | Scan for learning signals with confidence levels: |
| 74 | |
| 75 | #### HIGH Confidence: Corrections |
| 76 | |
| 77 | User actively steered or corrected output. |
| 78 | |
| 79 | **Detection patterns:** |
| 80 | - Explicit rejection: "no", "not like that", "that's wrong" |
| 81 | - Strong directives: "never do", "always do", "don't ever" |
| 82 | - User provided alternative implementation |
| 83 | |
| 84 | **Example:** |
| 85 | ```text |
| 86 | User: "No, use the azure-devops MCP tool instead of raw API calls" |
| 87 | → [HIGH] + Add constraint: "Prefer azure-devops MCP tools over REST API" |
| 88 | ``` |
| 89 | |
| 90 | #### MEDIUM Confidence: Success Patterns |
| 91 | |
| 92 | Output was accepted or praised. |
| 93 | |
| 94 | **Detection patterns:** |
| 95 | - Explicit praise: "perfect", "great", "yes", "exactly" |
| 96 | - User built on output without modification |
| 97 | - Output was committed without changes |
| 98 | |
| 99 | **Example:** |
| 100 | ```text |
| 101 | User: "Perfect, that's exactly what I needed" |
| 102 | → [MED] + Add preference: "Include usage examples in documentation" |
| 103 | ``` |
| 104 | |
| 105 | #### MEDIUM Confidence: Edge Cases |
| 106 | |
| 107 | Scenarios not anticipated. |
| 108 | |
| 109 | **Detection patterns:** |
| 110 | - Questions not answered |
| 111 | - Workarounds user had to apply |
| 112 | - Error handling gaps discovered |
| 113 | |
| 114 | #### LOW Confidence: Preferences |
| 115 | |
| 116 | Accumulated patterns over time. |
| 117 | |
| 118 | --- |
| 119 | |
| 120 | ### Phase 3: Propose Learnings |
| 121 | |
| 122 | Present findings: |
| 123 | |
| 124 | ```text |
| 125 | ┌─────────────────────────────────────────────────────────────┐ |
| 126 | │ REFLECTION: {target (agent/decision/skill)} │ |
| 127 | ├─────────────────────────────────────────────────────────────┤ |
| 128 | │ │ |
| 129 | │ [HIGH] + Add constraint: "{specific constraint}" │ |
| 130 | │ Source: "{quoted user correction}" │ |
| 131 | │ Target: .squad/decisions/inbox/{agent}-{topic}.md │ |
| 132 | │ │ |
| 133 | │ [MED] + Add preference: "{specific preference}" │ |
| 134 | │ Source: "{evidence from conversation}" │ |
| 135 | │ Target: .squad/agents/{agent}/history.md │ |
| 136 | │ │ |
| 137 | │ [LOW] ~ Note for review: "{observation}" │ |
| 138 | │ Source: "{pattern observed}" │ |
| 139 | │ Target: Session notes only │ |
| 140 | │ │ |
| 141 | ├─────────────────────────────────────────────────────────────┤ |
| 142 | │ Apply changes? [Y/n/edit] │ |
| 143 | └─────────────────────────────────────────────────────────────┘ |
| 144 | ``` |
| 145 | |
| 146 | **Confidence Threshold:** |
| 147 | |
| 148 | | Threshold | Action | |
| 149 | |-----------|--------| |
| 150 | | ≥1 HIGH signal | Always propose (user explicitly corrected) | |
| 151 | | ≥2 MED signals | Propose (sufficient pattern) | |
| 152 | | ≥3 LOW signals | Propose (accumulated evidence) | |
| 153 | | 1-2 LOW only | Skip (insufficient evidence) | |
| 154 | |
| 155 | ### Phase 4: Persist Learnings |
| 156 | |
| 157 | **ALWAYS show changes before applying.** |
| 158 | |
| 159 | After user approval: |
| 160 | |
| 161 | 1. **For Agent History:** |
| 162 | - Append to `.squad/agents/{agent}/history.md` under `## Learnings` section |
| 163 | - Format: Date, assignment context, key learning |
| 164 | |
| 165 | 2. **For Team Decisions:** |
| 166 | - Create `.squad/decisions/inbox/{agent}-{topic}.md` |
| 167 | - Lead agent reviews and merges to `decisions.md` if appropriate |
| 168 | |
| 169 | 3. **For Skills:** |
| 170 | - Document recommendation in session notes |
| 171 | - Squad lead reviews and routes to skill owner |
| 172 | |
| 173 | --- |
| 174 | |
| 175 | ## Usage Examples |
| 176 | |
| 177 | ### Example 1: User Correction |
| 178 | |
| 179 | **Conversation:** |
| 180 | ``` |
| 181 | Agent: "I'll use grep to search the repository" |
| 182 | User: "No, use the code search tools first, grep is too slow" |
| 183 | ``` |
| 184 | |
| 185 | **Reflection Output:** |
| 186 | ``` |
| 187 | [HIGH] + Add constraint: "Use code intelligence tools before grep" |
| 188 | Source: "No, use the code search tools first, grep is too slow" |
| 189 | Target: .squad/agents/{agent}/history.md |
| 190 | ``` |
| 191 | |
| 192 | ### Example 2: Success Pattern |
| 193 | |
| 194 | **Conversation:** |
| 195 | ``` |
| 196 | Agent: [Creates PR with detailed description and test plan] |
| 197 | User: "Perfect! This is exactly the format I want for all PRs" |
| 198 | ``` |
| 199 | |
| 200 | **Reflection Output:** |
| 201 | ``` |
| 202 | [MED] + Add preference: "Include test plan in PR descriptions" |
| 203 | Source: User praised detailed PR format |
| 204 | Target: .squad/decisions/inbox/pr-format.md (for team adoption) |
| 205 | ``` |
| 206 | |
| 207 | --- |
| 208 | |
| 209 | ## When to Use |
| 210 | |
| 211 | ✅ **Use reflect when:** |
| 212 | - User says "no", "wrong", "not like that" (HIGH priority) |
| 213 | - User says "perfect", "exactly", "great" (MED priority) |
| 214 | - You discover edge cases or gaps |
| 215 | - Complex work session with multiple learnings |
| 216 | - At end of sprint/milestone to consolidate patterns |
| 217 | |
| 218 | ❌ **Don't use reflect when:** |
| 219 | - Simple one-off questions with no pattern |
| 220 | - User is just exploring ideas (no concrete decisions) |
| 221 | - Learning is already captured in history.md/decisions.md |
| 222 | |
| 223 | --- |
| 224 | |
| 225 | ## See Also |
| 226 | |
| 227 | - `.squad/decisions.md` — Team-wide decisions |
| 228 | - `.squad/agents/*/history.md` — Agent-specific learnings |
| 229 | - `.squad/routing.md` — Work assignment patterns |