Session Reflection

Value: Feedback — every user intervention is a signal that the system prompt is incomplete. Turning corrections into durable instructions creates compound improvement across sessions.

Purpose

Teaches agents to analyze session history for recurring corrections, generate project-specific system prompts that prevent known failure modes, and maintain working state that survives context compaction and crashes. Transforms reactive corrections into proactive prevention.

Practices

Reflection Triggers

Reflect after: milestones (PR merged, feature complete), 3+ repeated corrections from the user, session restart or crash recovery, every 5 completed tasks, and on explicit user request. Do not wait for a “good time” — reflect when triggered.

The 3-correction trigger is a HARD REQUIREMENT, not a suggestion. If the user has corrected you 3 times on any topic, IMMEDIATELY invoke session-reflection. Count explicit corrections (user telling you to do something differently) and implicit corrections (user interrupting to do something themselves). Do not defer because “now is not a good time.”

Analyze Session History

Examine conversation history, git log, memory files, WORKING_STATE.md, and session logs. Categorize each user intervention into one of five types:

• Correction: Agent did the wrong thing (system prompt gap)
• Repetition: Agent was told the same thing again (emphasis gap)
• Role Redirect: Agent stepped outside its role (boundary gap)
• Frustration Escalation: User became more forceful (decay problem)
• Workaround: User did it themselves (skill gap)

See references/analysis-framework.md for detailed categorization and prioritization.

Generate or Refine System Prompt

Create a project-specific system prompt file that supplements installed skills. Structure: Role and Constraints, Startup Procedure, Process Requirements, Common Mistakes, Reminders.

Refinement rules: add new items for new gaps, promote advisory to structural when gaps recur, rewrite ambiguous items for clarity. Never remove items until the gap is confirmed solved across 3+ sessions. See references/system-prompt-patterns.md.

Generate Launcher Script

For harnesses that support system prompts (Claude Code: claude --system-prompt <file> "$@"), generate a launcher script (e.g., bin/ccf). For harnesses without system prompt support, fold critical directives into CLAUDE.md/AGENTS.md. See references/launcher-templates.md.

Self-Reminder Protocol

Every 5-10 messages during long sessions, re-read: system prompt, role constraints, current task context, WORKING_STATE.md. Mandatory after context compaction (you lose implicit context). This is the primary defense against role drift in long sessions.

Working State Persistence

Maintain WORKING_STATE.md as insurance against context compaction and crashes. Update after every significant state change. Always read before acting after any interruption. Location: .factory/WORKING_STATE.md (pipeline) or project root (standalone). See references/working-state-schema.md for format.

Do:

• Update on task start, phase change, decision made, blocker encountered
• Overwrite with current state (not append)
• Read FIRST after any interruption

Do not:

• Guess state from memory after a compaction or restart
• Use as a journal — keep it concise and current
• Skip updates because “nothing important changed”

Context Budget Awareness

When beginning a task with more than 10 discrete items, proactively write incremental status to a scratch file (e.g., .factory/session-status.md) after every 3-5 completed items. This enables continuation sessions to resume efficiently without re-reading all completed work.

Continuation Summary Requirements

When generating or reading a continuation summary, verify it includes: current role and its constraints, active team members and their tasks, the specific gate/stage the pipeline is at. If the summary omits role constraints, re-derive them from the skill files before proceeding.

Hook Output Is a Directive

When a hook fires and injects a message into the conversation — especially Stop hooks at session end — treat it as a command to execute immediately. Do not relay hook messages to the user and wait for instructions. Do not ask permission. The hook already told you what to do. Act on it.

This applies to all hook types: if a PostToolUse hook says “run tests and paste output,” run the tests. If a Stop hook says “commit or stash changes,” commit or stash. The hook message is your instruction, not a status report to forward to the user.

Post-Session Learning Loop

At session end: identify patterns from this session, update memory files, refine system prompt if triggers were hit, archive working state.

The loop closes when the same category of intervention stops recurring. If an intervention category persists across 3+ sessions after system prompt refinement, escalate: the gap may require a new skill or a structural change to the workflow.

Enforcement Note

This skill provides advisory guidance. The self-reminder protocol and working state maintenance require agent self-discipline. On Claude Code, a pre-tool-use hook could mechanically enforce state file reads, but no such hook is provided by default. The reflection triggers are event-driven and cannot be mechanically enforced. If you observe the agent drifting from its role or repeating corrected mistakes, point out the pattern and suggest a reflection.

Verification

After completing work guided by this skill, verify:

• Reflection performed at every trigger point (milestone, repeated correction, restart)
• User interventions categorized using the five-type taxonomy
• System prompt generated or refined with structural (not just advisory) language
• Self-reminder protocol followed (state re-read every 5-10 messages)
• WORKING_STATE.md current and accurate
• State re-read after every context compaction (not guessed)
• Launcher script generated for harnesses that support system prompts

If any criterion is not met, revisit the relevant practice before proceeding.

Dependencies

This skill works standalone. For enhanced workflows, it integrates with:

• memory-protocol: Persistent storage for session learnings and working state
• agent-coordination: Coordination patterns referenced in system prompt generation
• pipeline: Pipeline controller benefits from self-reminder and crash recovery
• ensemble-team: Team retrospectives feed into session reflection analysis

Missing a dependency? Install with:

npx skills add jwilger/agent-skills --skill memory-protocol