From fe5a68a4aced89edf7ad526a47f3f7cb9ed2b4d1 Mon Sep 17 00:00:00 2001 From: Tamir Dresher Date: Wed, 25 Mar 2026 23:20:00 +0200 Subject: [PATCH 1/4] =?UTF-8?q?feat(skills):=20add=20reflect=20skill=20?= =?UTF-8?q?=E2=80=94=20in-session=20learning=20capture=20and=20mistake=20p?= =?UTF-8?q?revention?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Battle-tested in production multi-agent deployment. Extracts HIGH/MED/LOW confidence patterns from conversations, surfaces corrections as learnings, and routes them to .squad/decisions/inbox/ or agent history.md. Zero breaking changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .changeset/reflect-skill.md | 6 + .../templates/skills/reflect/SKILL.md | 230 ++++++++++++++++++ .../templates/skills/reflect/SKILL.md | 230 ++++++++++++++++++ 3 files changed, 466 insertions(+) create mode 100644 .changeset/reflect-skill.md create mode 100644 packages/squad-cli/templates/skills/reflect/SKILL.md create mode 100644 packages/squad-sdk/templates/skills/reflect/SKILL.md diff --git a/.changeset/reflect-skill.md b/.changeset/reflect-skill.md new file mode 100644 index 000000000..0a566f89c --- /dev/null +++ b/.changeset/reflect-skill.md @@ -0,0 +1,6 @@ +--- +"squad-cli": minor +"squad-sdk": minor +--- + +feat: add reflect skill for in-session learning capture and mistake prevention diff --git a/packages/squad-cli/templates/skills/reflect/SKILL.md b/packages/squad-cli/templates/skills/reflect/SKILL.md new file mode 100644 index 000000000..7e2a3bddd --- /dev/null +++ b/packages/squad-cli/templates/skills/reflect/SKILL.md @@ -0,0 +1,230 @@ +--- +name: reflect +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. +license: MIT +metadata: + version: 1.0.0-squad + domain: team-memory, learning + confidence: high +--- + +# Reflect Skill + +**Critical learning capture system** for Squad. Prevents repeating mistakes and preserves successful patterns across sessions. + +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.** + +--- + +## Integration with Squad Architecture + +**Reflect complements existing Squad knowledge systems:** + +1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (READ-ONLY by agents, managed by human) +2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect +3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md + +**Workflow:** +- Use `reflect` during work to capture learnings +- At session end, review captured learnings +- Promote HIGH confidence patterns → lead agent for decision.md review +- Promote agent-specific patterns → `{agent}/history.md` updates + +--- + +## Triggers + +### 🔴 HIGH Priority (Invoke Immediately) + +| Trigger | Example | Why Critical | +|---------|---------|--------------| +| User correction | "no", "wrong", "not like that", "never do" | Captures mistakes to prevent repetition | +| Architectural insight | "you removed that without understanding why" | Documents design decisions (Chesterton's Fence) | +| Immediate fixes | "debug", "root cause", "fix all" | Learns from errors in real-time | + +### 🟡 MEDIUM Priority (Invoke After Multiple) + +| Trigger | Example | Why Important | +|---------|---------|---------------| +| User praise | "perfect", "exactly", "great" | Reinforces successful patterns | +| Tool preferences | "use X instead of Y", "prefer" | Builds workflow preferences | +| Edge cases | "what if X happens?", "don't forget", "ensure" | Captures scenarios to handle | + +### 🟢 LOW Priority (Invoke at Session End) + +| Trigger | Example | Why Useful | +|---------|---------|------------| +| Repeated patterns | Frequent use of specific commands/tools | Identifies workflow preferences | +| Session end | After complex work | Consolidates all session learnings | + +--- + +## Process + +### Phase 1: Identify Learning Target + +Determine what knowledge system should be updated: + +1. **Agent-specific learning** → `.squad/agents/{agent}/history.md` +2. **Team-wide decision** → `.squad/decisions/inbox/{agent}-{topic}.md` +3. **Skill-specific improvement** → Document in session, recommend to skill owner + +### Phase 2: Analyze Conversation + +Scan for learning signals with confidence levels: + +#### HIGH Confidence: Corrections + +User actively steered or corrected output. + +**Detection patterns:** +- Explicit rejection: "no", "not like that", "that's wrong" +- Strong directives: "never do", "always do", "don't ever" +- User provided alternative implementation + +**Example:** +```text +User: "No, use the azure-devops MCP tool instead of raw API calls" +→ [HIGH] + Add constraint: "Prefer azure-devops MCP tools over REST API" +``` + +#### MEDIUM Confidence: Success Patterns + +Output was accepted or praised. + +**Detection patterns:** +- Explicit praise: "perfect", "great", "yes", "exactly" +- User built on output without modification +- Output was committed without changes + +**Example:** +```text +User: "Perfect, that's exactly what I needed" +→ [MED] + Add preference: "Include usage examples in documentation" +``` + +#### MEDIUM Confidence: Edge Cases + +Scenarios not anticipated. + +**Detection patterns:** +- Questions not answered +- Workarounds user had to apply +- Error handling gaps discovered + +#### LOW Confidence: Preferences + +Accumulated patterns over time. + +--- + +### Phase 3: Propose Learnings + +Present findings: + +```text +┌─────────────────────────────────────────────────────────────┐ +│ REFLECTION: {target (agent/decision/skill)} │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ [HIGH] + Add constraint: "{specific constraint}" │ +│ Source: "{quoted user correction}" │ +│ Target: .squad/decisions/inbox/{topic}.md │ +│ │ +│ [MED] + Add preference: "{specific preference}" │ +│ Source: "{evidence from conversation}" │ +│ Target: .squad/agents/{agent}/history.md │ +│ │ +│ [LOW] ~ Note for review: "{observation}" │ +│ Source: "{pattern observed}" │ +│ Target: Session notes only │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ Apply changes? [Y/n/edit] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Confidence Threshold:** + +| Threshold | Action | +|-----------|--------| +| ≥1 HIGH signal | Always propose (user explicitly corrected) | +| ≥2 MED signals | Propose (sufficient pattern) | +| ≥3 LOW signals | Propose (accumulated evidence) | +| 1-2 LOW only | Skip (insufficient evidence) | + +### Phase 4: Persist Learnings + +**ALWAYS show changes before applying.** + +After user approval: + +1. **For Agent History:** + - Append to `.squad/agents/{agent}/history.md` under `## Learnings` section + - Format: Date, assignment context, key learning + +2. **For Team Decisions:** + - Create `.squad/decisions/inbox/{agent}-{topic}.md` + - Lead agent reviews and merges to `decisions.md` if appropriate + +3. **For Skills:** + - Document recommendation in session notes + - Squad lead reviews and routes to skill owner + +--- + +## Usage Examples + +### Example 1: User Correction + +**Conversation:** +``` +Agent: "I'll use grep to search the repository" +User: "No, use the code search tools first, grep is too slow" +``` + +**Reflection Output:** +``` +[HIGH] + Add constraint: "Use code intelligence tools before grep" + Source: "No, use the code search tools first, grep is too slow" + Target: .squad/agents/{agent}/history.md +``` + +### Example 2: Success Pattern + +**Conversation:** +``` +Agent: [Creates PR with detailed description and test plan] +User: "Perfect! This is exactly the format I want for all PRs" +``` + +**Reflection Output:** +``` +[MED] + Add preference: "Include test plan in PR descriptions" + Source: User praised detailed PR format + Target: .squad/decisions/inbox/pr-format.md (for team adoption) +``` + +--- + +## When to Use + +✅ **Use reflect when:** +- User says "no", "wrong", "not like that" (HIGH priority) +- User says "perfect", "exactly", "great" (MED priority) +- You discover edge cases or gaps +- Complex work session with multiple learnings +- At end of sprint/milestone to consolidate patterns + +❌ **Don't use reflect when:** +- Simple one-off questions with no pattern +- User is just exploring ideas (no concrete decisions) +- Learning is already captured in history.md/decisions.md + +--- + +## See Also + +- `.squad/decisions.md` — Team-wide decisions +- `.squad/agents/*/history.md` — Agent-specific learnings +- `.squad/routing.md` — Work assignment patterns diff --git a/packages/squad-sdk/templates/skills/reflect/SKILL.md b/packages/squad-sdk/templates/skills/reflect/SKILL.md new file mode 100644 index 000000000..7e2a3bddd --- /dev/null +++ b/packages/squad-sdk/templates/skills/reflect/SKILL.md @@ -0,0 +1,230 @@ +--- +name: reflect +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. +license: MIT +metadata: + version: 1.0.0-squad + domain: team-memory, learning + confidence: high +--- + +# Reflect Skill + +**Critical learning capture system** for Squad. Prevents repeating mistakes and preserves successful patterns across sessions. + +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.** + +--- + +## Integration with Squad Architecture + +**Reflect complements existing Squad knowledge systems:** + +1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (READ-ONLY by agents, managed by human) +2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect +3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md + +**Workflow:** +- Use `reflect` during work to capture learnings +- At session end, review captured learnings +- Promote HIGH confidence patterns → lead agent for decision.md review +- Promote agent-specific patterns → `{agent}/history.md` updates + +--- + +## Triggers + +### 🔴 HIGH Priority (Invoke Immediately) + +| Trigger | Example | Why Critical | +|---------|---------|--------------| +| User correction | "no", "wrong", "not like that", "never do" | Captures mistakes to prevent repetition | +| Architectural insight | "you removed that without understanding why" | Documents design decisions (Chesterton's Fence) | +| Immediate fixes | "debug", "root cause", "fix all" | Learns from errors in real-time | + +### 🟡 MEDIUM Priority (Invoke After Multiple) + +| Trigger | Example | Why Important | +|---------|---------|---------------| +| User praise | "perfect", "exactly", "great" | Reinforces successful patterns | +| Tool preferences | "use X instead of Y", "prefer" | Builds workflow preferences | +| Edge cases | "what if X happens?", "don't forget", "ensure" | Captures scenarios to handle | + +### 🟢 LOW Priority (Invoke at Session End) + +| Trigger | Example | Why Useful | +|---------|---------|------------| +| Repeated patterns | Frequent use of specific commands/tools | Identifies workflow preferences | +| Session end | After complex work | Consolidates all session learnings | + +--- + +## Process + +### Phase 1: Identify Learning Target + +Determine what knowledge system should be updated: + +1. **Agent-specific learning** → `.squad/agents/{agent}/history.md` +2. **Team-wide decision** → `.squad/decisions/inbox/{agent}-{topic}.md` +3. **Skill-specific improvement** → Document in session, recommend to skill owner + +### Phase 2: Analyze Conversation + +Scan for learning signals with confidence levels: + +#### HIGH Confidence: Corrections + +User actively steered or corrected output. + +**Detection patterns:** +- Explicit rejection: "no", "not like that", "that's wrong" +- Strong directives: "never do", "always do", "don't ever" +- User provided alternative implementation + +**Example:** +```text +User: "No, use the azure-devops MCP tool instead of raw API calls" +→ [HIGH] + Add constraint: "Prefer azure-devops MCP tools over REST API" +``` + +#### MEDIUM Confidence: Success Patterns + +Output was accepted or praised. + +**Detection patterns:** +- Explicit praise: "perfect", "great", "yes", "exactly" +- User built on output without modification +- Output was committed without changes + +**Example:** +```text +User: "Perfect, that's exactly what I needed" +→ [MED] + Add preference: "Include usage examples in documentation" +``` + +#### MEDIUM Confidence: Edge Cases + +Scenarios not anticipated. + +**Detection patterns:** +- Questions not answered +- Workarounds user had to apply +- Error handling gaps discovered + +#### LOW Confidence: Preferences + +Accumulated patterns over time. + +--- + +### Phase 3: Propose Learnings + +Present findings: + +```text +┌─────────────────────────────────────────────────────────────┐ +│ REFLECTION: {target (agent/decision/skill)} │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ [HIGH] + Add constraint: "{specific constraint}" │ +│ Source: "{quoted user correction}" │ +│ Target: .squad/decisions/inbox/{topic}.md │ +│ │ +│ [MED] + Add preference: "{specific preference}" │ +│ Source: "{evidence from conversation}" │ +│ Target: .squad/agents/{agent}/history.md │ +│ │ +│ [LOW] ~ Note for review: "{observation}" │ +│ Source: "{pattern observed}" │ +│ Target: Session notes only │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ Apply changes? [Y/n/edit] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Confidence Threshold:** + +| Threshold | Action | +|-----------|--------| +| ≥1 HIGH signal | Always propose (user explicitly corrected) | +| ≥2 MED signals | Propose (sufficient pattern) | +| ≥3 LOW signals | Propose (accumulated evidence) | +| 1-2 LOW only | Skip (insufficient evidence) | + +### Phase 4: Persist Learnings + +**ALWAYS show changes before applying.** + +After user approval: + +1. **For Agent History:** + - Append to `.squad/agents/{agent}/history.md` under `## Learnings` section + - Format: Date, assignment context, key learning + +2. **For Team Decisions:** + - Create `.squad/decisions/inbox/{agent}-{topic}.md` + - Lead agent reviews and merges to `decisions.md` if appropriate + +3. **For Skills:** + - Document recommendation in session notes + - Squad lead reviews and routes to skill owner + +--- + +## Usage Examples + +### Example 1: User Correction + +**Conversation:** +``` +Agent: "I'll use grep to search the repository" +User: "No, use the code search tools first, grep is too slow" +``` + +**Reflection Output:** +``` +[HIGH] + Add constraint: "Use code intelligence tools before grep" + Source: "No, use the code search tools first, grep is too slow" + Target: .squad/agents/{agent}/history.md +``` + +### Example 2: Success Pattern + +**Conversation:** +``` +Agent: [Creates PR with detailed description and test plan] +User: "Perfect! This is exactly the format I want for all PRs" +``` + +**Reflection Output:** +``` +[MED] + Add preference: "Include test plan in PR descriptions" + Source: User praised detailed PR format + Target: .squad/decisions/inbox/pr-format.md (for team adoption) +``` + +--- + +## When to Use + +✅ **Use reflect when:** +- User says "no", "wrong", "not like that" (HIGH priority) +- User says "perfect", "exactly", "great" (MED priority) +- You discover edge cases or gaps +- Complex work session with multiple learnings +- At end of sprint/milestone to consolidate patterns + +❌ **Don't use reflect when:** +- Simple one-off questions with no pattern +- User is just exploring ideas (no concrete decisions) +- Learning is already captured in history.md/decisions.md + +--- + +## See Also + +- `.squad/decisions.md` — Team-wide decisions +- `.squad/agents/*/history.md` — Agent-specific learnings +- `.squad/routing.md` — Work assignment patterns From d7b1b0d489e4ea160fbb9f69ac990f323e1859d8 Mon Sep 17 00:00:00 2001 From: tamirdresher Date: Thu, 26 Mar 2026 10:30:28 +0200 Subject: [PATCH 2/4] fix: correct changeset package names to @bradygaster scoped names per FIDO review --- .changeset/reflect-skill.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.changeset/reflect-skill.md b/.changeset/reflect-skill.md index 0a566f89c..1263013b1 100644 --- a/.changeset/reflect-skill.md +++ b/.changeset/reflect-skill.md @@ -1,6 +1,5 @@ --- -"squad-cli": minor -"squad-sdk": minor +"@bradygaster/squad-cli": minor +"@bradygaster/squad-sdk": minor --- - -feat: add reflect skill for in-session learning capture and mistake prevention +feat: add reflect skill for in-session learning capture and mistake prevention \ No newline at end of file From e163e2bdc9a34dd5553997edd15762465e5d319c Mon Sep 17 00:00:00 2001 From: tamirdresher Date: Thu, 26 Mar 2026 10:42:44 +0200 Subject: [PATCH 3/4] feat: add proposal document for reflect skill per review policy --- docs/proposals/reflect.md | 78 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/proposals/reflect.md diff --git a/docs/proposals/reflect.md b/docs/proposals/reflect.md new file mode 100644 index 000000000..1847b133e --- /dev/null +++ b/docs/proposals/reflect.md @@ -0,0 +1,78 @@ +# Proposal: Reflect Skill + +**Issue:** bradygaster/squad#621 +**Author:** tamirdresher +**Date:** 2026-03-26 +**Status:** Proposal + +--- + +## Problem Statement + +Agents repeat mistakes that were already identified in the same session. When an approach fails +or a user provides corrective feedback, agents lack a standardized mechanism to: +1. Capture the learning before continuing +2. Check captured learnings before attempting similar actions +3. Prevent recurrence without human intervention + +This is different from the history-hygiene skill (which covers cross-session history writing). +Reflect targets in-session learning capture during active work. + +--- + +## Proposed Approach + +A structured reflection protocol triggered by failure or feedback events: + +**Trigger classification:** +- HIGH: Agent makes same error twice, user explicitly says "that's wrong again" +- MED: Tool error after a previous warning, misunderstood requirement after clarification +- LOW: Minor adjustment requested, first-time error with clear cause + +**Reflect protocol (HIGH/MED triggers):** +1. Write a ## Reflection entry to current session context +2. State: what failed, why, what changes for next attempt +3. Check reflection notes before any action of the same category +4. If same failure occurs after reflection: escalate (do not retry silently) + +**Confidence threshold table:** Maps trigger severity to required escalation path + +--- + +## Fit with Existing Architecture + +- **Complements** history-hygiene skill (history.md captures final outcomes; reflect captures + in-flight corrections before the outcome is known) +- **Complements** error-recovery skill (recover handles the failure response; reflect captures + the learning to prevent recurrence) +- **Integrates** with .squad/decisions.md for persistent pattern learnings +- **No code changes** — template-only + +--- + +## What Changes + +- New skill: packages/squad-cli/templates/skills/reflect/SKILL.md +- New skill: packages/squad-sdk/templates/skills/reflect/SKILL.md +- New changeset: .changeset/reflect-skill.md + +## What Stays the Same + +- history-hygiene skill behavior unchanged +- error-recovery skill behavior unchanged +- No CLI or SDK runtime code changed + +--- + +## Risks and Mitigations + +| Risk | Likelihood | Impact | Mitigation | +|------|-----------|--------|------------| +| Reflect overhead slows agents | Low | Low | Only triggered by HIGH/MED events, not routine actions | +| Overlaps with history-hygiene | Low | Low | Different scope (in-session corrections vs final outcomes) | + +--- + +## References + +- Issue: bradygaster/squad#621 From 17fa9a8ec7afbe5fefa32822948e5def6dc27976 Mon Sep 17 00:00:00 2001 From: Tamir Dresher Date: Sat, 28 Mar 2026 17:56:39 +0300 Subject: [PATCH 4/4] fix: address copilot PR reviewer feedback on reflect skill Flatten frontmatter (remove nested metadata: block for parser compat), fix history.md governance description (append-only, not read-only), fix decision inbox path to include {agent}- prefix for consistency. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- packages/squad-cli/templates/skills/reflect/SKILL.md | 11 +++++------ packages/squad-sdk/templates/skills/reflect/SKILL.md | 11 +++++------ 2 files changed, 10 insertions(+), 12 deletions(-) diff --git a/packages/squad-cli/templates/skills/reflect/SKILL.md b/packages/squad-cli/templates/skills/reflect/SKILL.md index 7e2a3bddd..6a85b5190 100644 --- a/packages/squad-cli/templates/skills/reflect/SKILL.md +++ b/packages/squad-cli/templates/skills/reflect/SKILL.md @@ -2,10 +2,9 @@ name: reflect 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. license: MIT -metadata: - version: 1.0.0-squad - domain: team-memory, learning - confidence: high +version: 1.0.0-squad +domain: team-memory, learning +confidence: high --- # Reflect Skill @@ -20,7 +19,7 @@ Analyze conversations and propose improvements to squad knowledge based on what **Reflect complements existing Squad knowledge systems:** -1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (READ-ONLY by agents, managed by human) +1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (append-only; each agent updates their own file; Scribe propagates cross-agent updates) 2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect 3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md @@ -129,7 +128,7 @@ Present findings: │ │ │ [HIGH] + Add constraint: "{specific constraint}" │ │ Source: "{quoted user correction}" │ -│ Target: .squad/decisions/inbox/{topic}.md │ +│ Target: .squad/decisions/inbox/{agent}-{topic}.md │ │ │ │ [MED] + Add preference: "{specific preference}" │ │ Source: "{evidence from conversation}" │ diff --git a/packages/squad-sdk/templates/skills/reflect/SKILL.md b/packages/squad-sdk/templates/skills/reflect/SKILL.md index 7e2a3bddd..6a85b5190 100644 --- a/packages/squad-sdk/templates/skills/reflect/SKILL.md +++ b/packages/squad-sdk/templates/skills/reflect/SKILL.md @@ -2,10 +2,9 @@ name: reflect 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. license: MIT -metadata: - version: 1.0.0-squad - domain: team-memory, learning - confidence: high +version: 1.0.0-squad +domain: team-memory, learning +confidence: high --- # Reflect Skill @@ -20,7 +19,7 @@ Analyze conversations and propose improvements to squad knowledge based on what **Reflect complements existing Squad knowledge systems:** -1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (READ-ONLY by agents, managed by human) +1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (append-only; each agent updates their own file; Scribe propagates cross-agent updates) 2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect 3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md @@ -129,7 +128,7 @@ Present findings: │ │ │ [HIGH] + Add constraint: "{specific constraint}" │ │ Source: "{quoted user correction}" │ -│ Target: .squad/decisions/inbox/{topic}.md │ +│ Target: .squad/decisions/inbox/{agent}-{topic}.md │ │ │ │ [MED] + Add preference: "{specific preference}" │ │ Source: "{evidence from conversation}" │