---
name: superpowers-learning-workflow
description: Use when the user explicitly wants to capture lessons from completed work, persist durable project knowledge, or turn repeated patterns into reusable learning notes for future sessions.
---

# Superpowers Learning Workflow

## Overview

Use this workflow after meaningful work to capture what should survive the current session. It is a lightweight, repo-owned learning loop inspired by reflective agent systems, but scoped for safe use inside normal project workflows.

This is an explicit opt-in workflow. Do not use it by default. Only use it when the user explicitly asks for this workflow, names this skill, or a repository policy explicitly requires it.

## Workflow

1. Review the recent work, decisions, and verification evidence.
2. Classify what was learned into four buckets:
   - durable project facts
   - current working state
   - session outcome
   - reusable method or repeated pitfall
3. Add required metadata for durable entries:
   - `id`
   - `status`
   - `confidence`
   - `source`
   - `last_updated`
   - `review_after`
   Do not mark an entry as `verified` if `source` is empty.
4. If `.superpowers-memory/` exists, update:
   - `PROJECT_CONTEXT.md` for durable facts
   - `CURRENT_STATE.md` for active state
   - `DECISIONS.md` for lasting decisions
   - `KNOWN_FAILURES.md` for repeated failure patterns
   - `VERIFICATION_BASELINE.md` for trusted verification rules
   - `TEAM_PREFERENCES.md` for durable team agreements
   - `USER_PROFILE.md` for durable user preferences that are not project facts
   - `AGENT_NOTES.md` for durable execution reminders that are not project facts
   - `session-journal/` for the session summary
   - `LEARNING_BACKLOG.md` for reusable patterns that may deserve future workflows or skills
5. If `.superpowers-memory/` does not exist, tell the user to install the memory scaffold or keep the learning summary in a normal project doc.
6. Check whether any backlog item is strong enough to recommend promotion into a checklist, project rule, workflow step, script, or skill draft.
7. Review `.superpowers-memory/SESSION_CLOSE_CHECKLIST.md` before finishing the learning capture.
8. Use `scripts/suggest-superpowers-memory-updates.ps1` if it is unclear which memory surfaces should be updated from the current session signals.
9. Prefer `scripts/run-superpowers-memory-closeout.ps1` as the standard closeout helper when you want one command to review the checklist, get update suggestions, and optionally run validation.
10. When memory files were updated, run `scripts/validate-superpowers-memory.ps1` and include the result in the summary.
11. Use `scripts/search-superpowers-memory.ps1` when you need to confirm whether a pattern already exists in durable memory or recent journals.
12. Summarize what was learned and what, if anything, should become a future rule, checklist, script, or skill.

## When to Use

- The user explicitly asks to capture lessons from the current session
- The user explicitly names `$superpowers-learning-workflow`
- The user wants to persist durable knowledge for future sessions
- The user wants to turn repeated patterns into reusable learning notes
- A repository policy explicitly requires reflective capture after meaningful work

## Outputs

- Updated `.superpowers-memory/PROJECT_CONTEXT.md` when durable facts changed
- Updated `.superpowers-memory/CURRENT_STATE.md`
- Updated `.superpowers-memory/DECISIONS.md` when durable decisions changed
- Updated `.superpowers-memory/KNOWN_FAILURES.md` when repeated failure patterns were identified
- Updated `.superpowers-memory/VERIFICATION_BASELINE.md` when trusted verification rules changed
- Updated `.superpowers-memory/TEAM_PREFERENCES.md` when durable team agreements changed
- Updated `.superpowers-memory/USER_PROFILE.md` when durable user preferences changed
- Updated `.superpowers-memory/AGENT_NOTES.md` when durable execution reminders changed
- New or updated session journal entry
- Updated `.superpowers-memory/LEARNING_BACKLOG.md` for reusable lessons
- Updated `.superpowers-memory/SESSION_CLOSE_CHECKLIST.md` only as a reference checklist, not as a session log
- Memory validation evidence when memory was updated
- Optional memory update suggestion evidence when the suggestion script was used
- Optional closeout helper output when the closeout script was used
- A short summary of what should be remembered next time

## Guardrails

- Do not write temporary TODO noise into `PROJECT_CONTEXT.md`
- Do not turn a one-off fix into a reusable rule without a clear repeated pattern
- Do not auto-edit the skill library itself unless the user explicitly asks for that separate step
- Keep learning notes concise and actionable
- Do not promote a backlog item without enough repeated evidence or cross-session value
- Treat `ready_for_promotion` as a higher bar: expect repeated evidence, linked sources, and a reviewable promotion rationale