assistant-reflexion

name	assistant-reflexion
description	Reflect on evidence-backed lessons or recall prior ones. Use for explicit retrospectives, calibration, or a concrete durable lesson.
effort	low
triggers	[{"pattern":"reflect|what did we learn|lessons learned|how did that go|performance review|calibrate|self-assess|retrospective","priority":60,"min_words":3,"reminder":"This request matches assistant-reflexion. Consider invoking the Skill tool with skill='assistant-reflexion' for self-assessment and learning capture."}]

Reflexion — Self-Improving Agent

Contracts

File	Purpose
contracts/input.yaml	action (reflect/recall/stats/consolidate), task_description, project_type, task_type, review/build/user-correction evidence
contracts/output.yaml	action_taken, lessons[], evidence reviewed, persistence/no-save decision, recalled_lessons[]

• task_description is required for reflect; project_type and task_type are inferred when absent
• lessons entries include lesson, confidence (high/medium/low), applies_to, and evidence source
• recalled_lessons entries include lesson, confidence, date, and project
• Reflection outputs include persistence evidence when memory was written, or no-save rationale when storage was skipped, unavailable, disallowed, or refused

Cross-task learning system where insights from task N improve performance on task N+1.

Core principle: Capture durable lessons, not routine task ceremony.

Goal

Convert task outcomes, mistakes, calibration signals, and reusable lessons into future-facing memory without saving noise.

Success Criteria

• Reflection uses concrete task evidence, not vibes or generic advice.
• Lessons are actionable, scoped to project/task type, and assigned confidence.
• Pre-task recall returns relevant lessons with confidence and source context.
• Memory updates avoid secrets, PII, and facts already obvious from the repo.

Constraints

• Do not store broad platitudes or easily rediscoverable repository facts as lessons.
• Ask only when task identity or intended reflection action is materially unclear.
• Keep reflection output concise and focused on future behavior change.

Two Modes

Mode 1: Post-Task Reflection (after completing work)

Run reflection only when the user explicitly asks or concrete evidence suggests a durable lesson.

Mode 2: Pre-Task Lesson Recall (before starting work)

Recall prior lessons only when current work depends on earlier context.

Post-Task Reflection Protocol

After a user asks to reflect, or after review findings, build/test failures, user corrections, or memory trends expose a concrete reusable lesson:

Step 1: Capture Context

>> Reflecting on completed task...

Gather:

• What was the task?
• What project and project type?
• What size was it?
• What approach/strategy was used?
• How long did it take (approximate)?

Step 1.5: Read Learning Signals

If memory_trend MCP tool is available, call it with the current project name to surface mid-task signals (corrections, approvals, frustrations, pivots) captured during this session. Incorporate these into the self-assessment — they are objective evidence of what worked and what didn't.

For medium+ workflow completion, consume the ### Learning Controller fields from the task journal or equivalent workflow output. Treat Review Log findings, build/test failures, and user corrections as the highest-value lesson sources. Use routine progress and completed checklist items only as context, never as the lesson itself.

Step 2: Self-Assess

Ask yourself honestly:

What went well?

• Approaches that worked efficiently
• Correct assumptions
• Good tool/pattern choices
• Smooth phases (discovery was quick, plan was accurate, etc.)

What went wrong or was slow?

• Wrong initial assumptions
• Wasted effort (wrong approach, unnecessary code, late discoveries)
• Things that required user correction
• Plans that didn't survive contact with reality
• Review findings that exposed a repeated or preventable mistake
• Build/test failures that exposed a missing check, bad assumption, or fragile workflow

What was surprising or non-obvious?

• Gotchas specific to this project/technology
• Patterns that weren't what you expected
• User preferences that differ from defaults

Step 3: Extract Lessons

Convert observations into actionable rules:

Good format:

• "In [project type], always [do X] because [reason]"
• "When [situation], prefer [approach] over [alternative] because [reason]"
• "For [user name], [preference] is important because [reason]"

Bad format:

• "Things went well" (too vague)
• "I should have done better" (not actionable)
• "The code was complex" (not a lesson)
• "Completed slice 3" (task progress, not durable learning)

For lessons from review findings, build/test failures, or user corrections, include the source evidence in the lesson entry. If no evidence-backed durable lesson exists, return skipped_not_durable with a no-save rationale instead of forcing a memory write.

Step 4: Record

Store the reflection using memory system:

# Reflexion: [Task Description]

**Date:** [YYYY-MM-DD]
**Project:** [project name]
**Project Type:** [dotnet-api / blazor / maui / unity / etc.]
**Task Type:** [feature / bugfix / refactor / security / docs]
**Size:** [small / medium / large / mega]
**Duration:** [approximate]

## What Went Well
- [observation]

## What Went Wrong
- [observation]

## Lessons
- [actionable rule]

## Confidence Calibration
- Plan accuracy: [1-5] — [notes]
- Size estimate accuracy: [1-5] — [notes]
- First approach worked: [yes/no]

Use memory_reflect MCP tool to record the reflexion in the knowledge graph when the configured local memory backend is available and policy-approved.

If the backend is unavailable or policy-disallowed, do not write ad hoc markdown as cross-session memory. Return the reflection with persistence_decision: backend_unavailable or policy_disallowed and a no_save_rationale. If the only candidates are routine task progress, obvious repo facts, or stale temporary state, return persistence_decision: skipped_not_durable.

Step 5: Update Strategy Profile

If lessons apply broadly to a project type, update the strategy profile:

# Strategy: [Project Type]

## Discovery
- [lesson about what to check/ask]

## Planning
- [lesson about what to include in plans]

## Building
- [lesson about implementation approach]

## Review
- [lesson about what to watch for]

Use memory_pattern MCP tool to record/reinforce the strategy pattern in the knowledge graph.

Update (don't overwrite) — add new lessons, reinforce existing ones.

Pre-Task Lesson Recall Protocol

Use before planning only when prior project decisions, corrections, preferences, or lessons can materially change the current approach.

Step 1: Query Relevant Lessons

Search memory for lessons matching:

• Current project name
• Current project type
• Current task type (feature, bugfix, etc.)
• Technologies involved

Also call memory_trend with the project type to surface calibration trends and recent signal patterns. If trends show systematic bias (e.g., underestimation), factor that into planning.

Step 2: Filter by Relevance

• High confidence (reinforced 2+ times or from user correction): Always apply
• Medium confidence (single observation): Mention as consideration
• Low confidence (old, never reinforced): Skip unless directly relevant

Step 3: Incorporate

>> Checking past lessons for [project type] [task type]...
   Found [N] relevant lessons:
   - [lesson 1] (confidence: high)
   - [lesson 2] (confidence: medium)
>> Incorporating into plan constraints.

Add high-confidence lessons to the plan's constraints section.

Confidence Calibration

Track prediction accuracy across tasks:

What's Tracked

Prediction Type	How Measured
Size estimate	Predicted vs. actual effort (did "small" stay small?)
Plan accuracy	How many plan deviations occurred?
Risk predictions	Did flagged risks materialize? Did unflagged risks appear?
First-approach success	Did the first strategy work or require pivoting?

How It's Used

If cumulative data shows systematic bias:

• "You tend to underestimate refactors by 1 size category" → auto-adjust estimates
• "Plans for this project type have 60% deviation rate" → add more discovery time
• "First approach fails 40% of the time for large tasks" → explore 2 approaches before committing

Storage

Calibration data accumulates in strategy profile files and memory graph.

Lesson Lifecycle

Lesson created (confidence: 0.5)
    │
    ├─ Reinforced by same observation → confidence += 0.2
    ├─ Confirmed by user → confidence = 1.0
    ├─ Contradicted by evidence → flag for review
    │
    ├─ Not reinforced in 90 days → confidence -= 0.1/month
    │
    └─ confidence < 0.2 → archived

Integration Points

Skill	How Reflexion Integrates
assistant-workflow	Conditional recall when prior context matters; conditional reflection when durable evidence exists
assistant-memory	Stores reflexion entries and strategy profiles
assistant-onboard	First reflexion seeds from onboarding observations
assistant-review	Review findings feed into lessons about common mistakes

Output

Return:

• Action taken - reflected, recalled lessons, updated strategy, reported stats, or consolidated.
• Memory trend status - checked, backend_unavailable, policy_disallowed, not_configured, or not_applicable.
• Lessons - actionable lessons with confidence, where they apply, and source evidence.
• Evidence reviewed - task context, review findings, build/test failures, user corrections, and memory signals considered.
• Persistence decision - durable_saved, durable_updated, skipped_not_durable, backend_unavailable, policy_disallowed, or refused_sensitive.
• Artifacts - memory/reflexion/strategy entries written, or "none" with no-save rationale.
• Next use - how the lessons should influence future discovery, planning, build, or review work.
• Status - reflected, recalled, consolidated, or blocked by missing context.

Stop Rules

• Stop before recording memory when a lesson is not actionable or evidence-backed.
• Stop and refuse to store secrets, credentials, or sensitive personal data.
• If memory tools are unavailable or policy-disallowed, report the reflection result but mark persistence as backend_unavailable or policy_disallowed with no-save rationale.
• Stop before treating ad hoc markdown as durable persistence when a configured backend is available.

Visibility

Following the "invisible workflow" principle:

• During relevant recall: single line ("Found N lessons") unless user asks for details
• During Reflection: concise summary unless user asks to see full assessment
• Strategy profiles: only surface when directly relevant
• Calibration data: only mention when it changes a recommendation

Rules

• Skip routine reflection — run it only for an explicit request or a concrete durable lesson
• Be honest — reflexion that says "everything went perfectly" every time isn't useful
• Actionable over observational — "X was slow" is observation; "next time do Y instead of X" is actionable
• Don't over-capture — 2-3 good lessons per task beats 10 vague ones
• Corrections are highest priority — when the user corrects you, that's a guaranteed high-confidence lesson
• Mistakes beat progress — prefer lessons from review findings, build/test failures, and user corrections over routine task completion notes