syz-coder/superpowers-openspec-team-skills/superpowers-learning-workflow

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

1. 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.

1. 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

1. If .superpowers-memory/ does not exist, tell the user to install the memory scaffold or keep the learning summary in a normal project doc.
2. Check whether any backlog item is strong enough to recommend promotion into a checklist, project rule, workflow step, script, or skill draft.
3. Review .superpowers-memory/SESSION_CLOSE_CHECKLIST.md before finishing the learning capture.
4. Use scripts/suggest-superpowers-memory-updates.ps1 if it is unclear which memory surfaces should be updated from the current session signals.
5. 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.
6. When memory files were updated, run scripts/validate-superpowers-memory.ps1 and include the result in the summary.
7. Use scripts/search-superpowers-memory.ps1 when you need to confirm whether a pattern already exists in durable memory or recent journals.
8. 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