---
name: extract-insights
description: Use after a non-trivial session reveals a reusable workflow, failure pattern, decision rule, or tool combination worth preserving for future work.
---

# Extract Insights

Capture reusable lessons from a session so future work starts with evidence instead of rediscovery.

## When to Use

Run this near the end of a session when:

- A problem took multiple attempts to solve.
- A non-obvious workflow or tool combination worked.
- A failure pattern should be avoided next time.
- A decision framework emerged from tradeoffs.
- The insight applies across projects, not only to one incident.

Do not extract trivial steps, one-off outage details, or facts already documented in project instructions.

## Insight Selection

Pick one insight per note. A good insight has:

- **Trigger:** when a future agent should remember it.
- **Pattern:** what to do or avoid.
- **Evidence:** what happened that proves the pattern matters.
- **Boundary:** when not to apply it.

If you cannot name the trigger, do not save it.

## Output Format

```markdown
# [Actionable Insight Name]

## Trigger
[When this should be used]

## Problem
[What failure, friction, or decision this addresses]

## Pattern
[The reusable approach]

## Evidence
[Concrete session evidence, command result, artifact, or observed failure]

## Boundary
[When this does not apply]

## Next-Time Checklist
- [Specific check or action]
- [Specific check or action]
```

## Process

1. Review the session for one reusable pattern.
2. Draft the note using the format above.
3. Ask whether the user wants it saved and where.
4. Save only after approval unless the user already gave a target location.

## Quality Bar

- One insight per file.
- Write for a future session with no memory of today.
- Include enough evidence to prevent vague folklore.
- Avoid praise, apologies, or narrative recap.
- If the insight changes agent behavior, consider converting it into a proper skill later and testing it.