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
- Review the recent work, decisions, and verification evidence.
- Classify what was learned into four buckets:
- durable project facts
- current working state
- session outcome
- reusable method or repeated pitfall
- Add required metadata for durable entries:
idstatusconfidencesourcelast_updatedreview_afterDo not mark an entry asverifiedifsourceis empty.
- If
.superpowers-memory/exists, update:PROJECT_CONTEXT.mdfor durable factsCURRENT_STATE.mdfor active stateDECISIONS.mdfor lasting decisionsKNOWN_FAILURES.mdfor repeated failure patternsVERIFICATION_BASELINE.mdfor trusted verification rulesTEAM_PREFERENCES.mdfor durable team agreementsUSER_PROFILE.mdfor durable user preferences that are not project factsAGENT_NOTES.mdfor durable execution reminders that are not project factssession-journal/for the session summaryLEARNING_BACKLOG.mdfor reusable patterns that may deserve future workflows or skills
- If
.superpowers-memory/does not exist, tell the user to install the memory scaffold or keep the learning summary in a normal project doc. - Check whether any backlog item is strong enough to recommend promotion into a checklist, project rule, workflow step, script, or skill draft.
- Review
.superpowers-memory/SESSION_CLOSE_CHECKLIST.mdbefore finishing the learning capture. - Use
scripts/suggest-superpowers-memory-updates.ps1if it is unclear which memory surfaces should be updated from the current session signals. - Prefer
scripts/run-superpowers-memory-closeout.ps1as the standard closeout helper when you want one command to review the checklist, get update suggestions, and optionally run validation. - When memory files were updated, run
scripts/validate-superpowers-memory.ps1and include the result in the summary. - Use
scripts/search-superpowers-memory.ps1when you need to confirm whether a pattern already exists in durable memory or recent journals. - 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.mdwhen durable facts changed - Updated
.superpowers-memory/CURRENT_STATE.md - Updated
.superpowers-memory/DECISIONS.mdwhen durable decisions changed - Updated
.superpowers-memory/KNOWN_FAILURES.mdwhen repeated failure patterns were identified - Updated
.superpowers-memory/VERIFICATION_BASELINE.mdwhen trusted verification rules changed - Updated
.superpowers-memory/TEAM_PREFERENCES.mdwhen durable team agreements changed - Updated
.superpowers-memory/USER_PROFILE.mdwhen durable user preferences changed - Updated
.superpowers-memory/AGENT_NOTES.mdwhen durable execution reminders changed - New or updated session journal entry
- Updated
.superpowers-memory/LEARNING_BACKLOG.mdfor reusable lessons - Updated
.superpowers-memory/SESSION_CLOSE_CHECKLIST.mdonly 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_promotionas a higher bar: expect repeated evidence, linked sources, and a reviewable promotion rationale


