Task Retrospective

A skill for reflecting on completed tasks and converting experience into lasting rules.

The goal is simple: after finishing work, extract what was learned — both what went well and what failed — and encode that knowledge as concrete, actionable rules in the same format used by agent.instructions.md. This prevents repeating the same mistakes and reinforces effective patterns.

---

When to use this skill

• Immediately after completing a task, feature, plan, or agent workflow
• When the user asks for a reflection, retrospective, or lessons learned
• When an agent wants to close a loop and capture institutional knowledge
• Proactively, at the end of any multi-step execution that involved meaningful decisions

---

Process

Step 1: Collect context

Gather the raw material for reflection. Use whatever is available:

• Current conversation history (decisions, corrections, feedback given by the user)
• Task/plan files if provided (e.g., docs/agents/plans/*.md, tasks/todo.md)
• Git diff or commit history if relevant
• Any error messages, failed attempts, or corrections made mid-task

If a file path was passed as argument, read it. If nothing was provided, analyze the conversation directly.

Step 2: Identify decision events

Go through the execution timeline and identify discrete moments where a decision was made. For each one, note:

• What was decided — the action taken or approach chosen
• Outcome — did it work? Was it corrected? Did it cause rework?
• Category — Problem Understanding, Planning, Implementation, Communication, Tool Use, Verification, etc.

Focus on consequential decisions. Skip trivial steps.

Step 3: Classify decisions

Separate into two groups:

Correct decisions — actions that led to good outcomes, saved time, or were confirmed by the user as the right approach. Ask: "Why did this work? What principle is this an example of?"

Wrong decisions — actions that caused errors, required rework, were rejected by the user, violated stated requirements, or wasted effort. Ask: "Why did this fail? What pattern should be avoided in the future?"

Step 4: Generalize into rules

Avoid writing rules that are too specific to the current task. The best rules are transferable — they apply across many future tasks.

Good rule: "Always read the current file content before editing any section." Too specific: "Always read agent.instructions.md before line 47 of that specific file."

For each identified pattern (both good and bad), write a single-line rule. Be direct and imperative. No justifications in the rule itself — just the actionable instruction.

Step 5: Produce the retrospective report

Output a structured Markdown report using the template below. Never skip sections, even if a section has few items.

---

Output template

# Task Retrospective: <task name or brief description>

**Date:** <yyyy-mm-dd>
**Process evaluated:** <brief description of what was executed>

---

## Summary

<2-4 sentences describing what was done, what the main challenge was, and whether the overall outcome was good.>

---

## Decision Analysis

### Correct Decisions

| #   | Decision        | Category   | Why it worked              |
| --- | --------------- | ---------- | -------------------------- |
| 1   | <what was done> | <category> | <principle it illustrates> |

### Wrong Decisions

| #   | Decision        | Category   | Root cause      |
| --- | --------------- | ---------- | --------------- |
| 1   | <what was done> | <category> | <why it failed> |

---

## Extracted Rules

### Rules to Follow

- <Actionable rule 1>
- <Actionable rule 2>
- ...

### Rules to Avoid

- <Anti-pattern 1>
- <Anti-pattern 2>
- ...

---

## Proposed Update to agent.instructions.md

The following rules are ready to be appended to the relevant sections of `instructions/agent.instructions.md`:

**Add to ## Mandatory: Rules to Follow:**

- <new rule>

**Add to ## Mandatory: Rules to Avoid:**

- <new anti-pattern>

---

Step 6: Offer to persist the rules

After presenting the report, ask the user:

"Would you like me to append the new rules to instructions/agent.instructions.md? I'll add only the rules that don't already exist there."

If the user confirms:

1. Read the current content of instructions/agent.instructions.md
2. Identify which rules are truly new (avoid duplicates)
3. Append new rules under the appropriate sections (## Mandatory: Rules to Follow / ## Mandatory: Rules to Avoid) using precise, surgical edits — no rewrites

---

Quality guidelines for rules

A good rule is:

• Imperative — starts with a verb: "Always...", "Never...", "Read X before...", "Validate..."
• Specific enough to act on — not vague like "Be careful"
• General enough to reuse — not tied to one specific file or context
• Honest — derived from an actual failure or success, not hypothetical

Aim for 3–7 rules per section. More than that usually means some rules are redundant or too narrow.

---

Decision categories (reference)

Use these when classifying decisions in Step 2:

Category	Examples
Planning	Breaking down tasks, defining scope, sequencing steps
Problem Understanding	Reading requirements, asking clarifying questions
Implementation	Code choices, tool usage, file edits
Verification	Testing, validating outputs, checking requirements
Communication	How information was presented to the user
Tool Use	Choosing which tool to call, parameter correctness
Scope Control	Staying within requested boundaries, avoiding over-engineering
File Management	Creating, editing, deleting files