AGENTS/skill/reflection/SKILL.md

name, description, compatibility

name	description	compatibility
reflection	Conversation analysis to improve skills based on user feedback. Use when: (1) user explicitly requests reflection ('reflect', 'improve', 'learn from this'), (2) reflection mode is ON and clear correction signals detected, (3) user asks to analyze skill performance. Triggers: reflect, improve, learn, analyze conversation, skill feedback. Toggle with /reflection on|off command.	opencode

Reflection

Analyze conversations to detect user corrections, preferences, and observations, then propose skill improvements.

Reflection Mode

Toggle: Use /reflection on|off|status command

When mode is ON:

• Actively monitor for correction signals during conversation
• Auto-suggest reflection when clear patterns detected
• Proactively offer skill improvements

When mode is OFF (default):

• Only trigger on explicit user request
• No automatic signal detection

Core Workflow

When triggered, follow this sequence:

1. Identify Target Skill

If skill explicitly mentioned:

User: "Reflect on the task-management skill"
→ Target: task-management

If not specified, ask:

"Which skill should I analyze? Recent skills used: [list from session]"

2. Scan Conversation

Use session tools to analyze the current conversation:

# Read current session messages
session_read --session_id [current] --include_todos true

Analyze for:

• When target skill was used
• User responses after skill usage
• Correction signals (see references/signal-patterns.md)
• Workflow patterns
• Repeated interactions

3. Classify Findings

Rate each finding using 3-tier system (see references/rating-guidelines.md):

HIGH (Explicit Constraints):

• Direct corrections: "No, don't do X"
• Explicit rules: "Always/Never..."
• Repeated violations

MEDIUM (Preferences & Patterns):

• Positive reinforcement: "That's perfect"
• Adopted patterns (used 3+ times)
• Workflow optimizations

LOW (Observations):

• Contextual insights
• Tentative patterns
• Environmental preferences

4. Read Target Skill

Before proposing changes, read the current skill implementation:

# Read the skill file
read skill/[target-skill]/SKILL.md

# Check for references if needed
glob pattern="**/*.md" path=skill/[target-skill]/references/

5. Generate Proposals

For each finding, create:

HIGH findings:

• Specific constraint text to add
• Location in skill where it should go
• Exact wording for the rule

MEDIUM findings:

• Preferred approach description
• Suggested default behavior
• Optional: code example or workflow update

LOW findings:

• Observation description
• Potential future action
• Context for when it might apply

6. User Confirmation

Present findings in structured format:

## Reflection Analysis: [Skill Name]

### HIGH Priority (Constraints)
1. **[Finding Title]**
   - Signal: [What user said/did]
   - Proposed: [Specific change to skill]

### MEDIUM Priority (Preferences)
1. **[Finding Title]**
   - Signal: [What user said/did]
   - Proposed: [Suggested update]

### LOW Priority (Observations)
[List observations]

---

Approve changes to [skill name]? (yes/no/selective)

7. Apply Changes or Document

If user approves (yes):

1. Edit skill/[target-skill]/SKILL.md with proposed changes
2. Confirm: "Updated [skill name] with [N] improvements"
3. Show diff of changes

If user selects some (selective):

1. Ask which findings to apply
2. Edit skill with approved changes only
3. Write rejected findings to OBSERVATIONS.md

If user declines (no):

1. Create/append to skill/[target-skill]/OBSERVATIONS.md
2. Document all findings with full context
3. Confirm: "Documented [N] observations in OBSERVATIONS.md for future reference"

OBSERVATIONS.md Format

When writing observations file:

# Observations for [Skill Name]

Generated: [Date]
From conversation: [Session ID if available]

## HIGH: [Finding Title]
**Context:** [Which scenario/workflow]
**Signal:** [User's exact words or repeated pattern]
**Constraint:** [The rule to follow]
**Proposed Change:** [Exact text to add to skill]
**Status:** Pending user approval

---

## MEDIUM: [Finding Title]
**Context:** [Which scenario/workflow]
**Signal:** [What indicated this preference]
**Preference:** [The preferred approach]
**Rationale:** [Why this works well]
**Proposed Change:** [Suggested skill update]
**Status:** Pending user approval

---

## LOW: [Observation Title]
**Context:** [Which scenario/workflow]
**Signal:** [What was noticed]
**Observation:** [The pattern or insight]
**Potential Action:** [Possible future improvement]
**Status:** Noted for future consideration

Signal Detection Patterns

Key patterns to watch for (detailed in references/signal-patterns.md):

Explicit corrections:

• "No, that's wrong..."
• "Actually, you should..."
• "Don't do X, do Y instead"

Repeated clarifications:

• User explains same thing multiple times
• Same mistake corrected across sessions

Positive patterns:

• "Perfect, keep doing it this way"
• User requests same approach repeatedly
• "That's exactly what I needed"

Workflow corrections:

• "You skipped step X"
• "Wrong order"
• "You should have done Y first"

Usage Examples

Example 1: Post-Skill Usage

User: "Reflect on how the task-management skill performed"

Agent:
1. Read current session
2. Find all task-management skill invocations
3. Analyze user responses afterward
4. Read skill/task-management/SKILL.md
5. Present findings with confirmation prompt

Example 2: User-Prompted Learning

User: "Learn from this conversation - I had to correct you several times"

Agent:
1. Ask which skill to analyze (if multiple used)
2. Scan full conversation for correction signals
3. Classify by severity (HIGH/MEDIUM/LOW)
4. Propose changes with confirmation

Example 3: Detected Signals

# During conversation, user corrects workflow twice
User: "No, run tests BEFORE committing, not after"
[later]
User: "Again, tests first, then commit"

# Later when user says "reflect" or at end of session
Agent detects: HIGH priority constraint for relevant skill

References

• signal-patterns.md - Comprehensive list of correction patterns to detect
• rating-guidelines.md - Decision tree for classifying findings (HIGH/MEDIUM/LOW)

Load these when analyzing conversations for detailed pattern matching and classification logic.

Important Constraints

1. Never edit skills without user approval - Always confirm first
2. Read the skill before proposing changes - Avoid suggesting what already exists
3. Preserve existing structure - Match the skill's current organization and style
4. Be specific - Vague observations aren't actionable
5. Full conversation scan - Don't just analyze last few messages
6. Context matters - Include why the finding matters, not just what was said