/pstack:reflect
Call when neededIn one lineAfter a task, three reviewers read the chat and suggest improvements. Nothing changes until you approve.
- When to use
- A task was too slow or went the long way round, and you want to avoid that next time.
/pstack:reflect That was too slow. Write down what you learned so it doesn't happen again.Just asking vs. using it
The same request, typed plainly or with /pstack:reflect. Here's what changes.
With /pstack:reflectWhat the document says
6 sections, about 950 words, 4 min to read. Click a section to read it.
OpeningIt mines this conversation for durable learnings and turns them into skill edits. It skips trivial chats and cases an existing skill already covered.
- 1Locate the active transcriptFinds this chat's transcript in your tool's session folder for this workspace and confirms it by the opening prompt.
- 2Spawn three reviewers in parallelStarts three helpers at once (judgment, tooling, divergent), each on the model the pstack settings file or default names.
- 3SynthesizeOne more helper spot-checks citations and merges the findings into Accepted, Rejected and Backlog lists.
- 4Structural enforcement checkMoves any accepted item that a lint, script, flag or runtime check would enforce better into Backlog.
- 5ApplyFiles Backlog items now, waits for approval on Accepted edits, edits a skill copy, and never opens a PR or pushes.
- 6Summarize for the userEnds with a short list: edits applied, new skills, Backlog filed, and findings dropped with reasons.
Wording worth borrowing
A few sentences from the original: what each one makes the AI do, why it works, and how you can borrow it.
Exclude a category in one line
One-offs are not learnings.
- Makes the AI
- It keeps only lessons that will come up again. A one-time accident doesn't go into a skill.
- Why it works
- One short exclusion blocks the most common mistake: treating chance as a pattern.
- Borrow it
- When the AI sums up a project, add: "Only list problems we'll hit again. One-time flukes don't count."
Make approval a hard gate
wait for explicit approval before applying any Accepted edit
- Makes the AI
- It shows you every proposal first and changes only the ones you approve.
- Why it works
- "Explicit" and "any" leave no gap, so the AI can't decide a small edit is fine to make first.
- Borrow it
- Before the AI edits a file, say: "List the changes first. Don't touch anything until I reply 'go'."
Let a check enforce it
Move any Accepted item that a lint rule, script, metadata flag, or runtime check would enforce more reliably to Backlog.
- Makes the AI
- Problems a script or check could catch go to the backlog to be automated, not into another reminder.
- Why it works
- It makes the AI ask "will people reliably remember this?" and steers the rule to a sturdier form.
- Borrow it
- When listing team rules, say: "If a spreadsheet formula could check it, don't write a reminder. Tell me the formula."
Hand over a fill-in template
Short list, no preamble:
- Makes the AI
- The final summary comes in four fixed groups, so you see at once what changed and what was dropped.
- Why it works
- Giving the format of each line, with placeholders, lets the AI fill it in instead of writing a long report.
- Borrow it
- When you ask for status, give a shape: "Reply as 'Done: … Not done: … (why)'."
Full text
The SKILL.md the AI reads, as written.
descriptionSpawn three parallel review subagents over the active transcript, surface learnings, and route each to a concrete edit on an existing skill. Use when the user says reflect.
Reflect
Mine the current conversation for durable learnings, then route them into skill edits.
Invoke when the user says "reflect" or "/pstack:reflect". Skip when the conversation is trivial, off-topic, or already covered by an existing skill the parent followed correctly. One-offs are not learnings.
1. Locate the active transcript
Before fanning out, find this conversation's transcript in the active workspace's session directory. Do not glob across every project's directory. That crosses workspace boundaries and reads private chats from unrelated projects.
Where the transcript lives depends on your harness:
- Cursor: the
agent-transcripts/directory the system prompt names.
ls -t <agent-transcripts>/*.jsonl <agent-transcripts>/*/*.jsonl <agent-transcripts>/*/subagents/*.jsonl 2>/dev/null | head -10
That covers the legacy flat (<id>.jsonl), current nested (<id>/<id>.jsonl), and subagent (<parent>/subagents/<child>.jsonl) layouts. For each candidate, read the first JSONL line. Take the file whose message.content[0].text contains the conversation's opening user prompt.
- Claude Code:
~/.claude/projects/<slug>/<session-id>.jsonl, where<slug>is the workspace path with every character that isn't a letter or digit turned into "-". - Pi:
~/.pi/agent/sessions/--<slug>--/*.jsonl, where<slug>is the workspace path with the leading slash dropped and each "/" turned into "-". - Codex:
~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl. Keep only files whose first line haspayload.cwdequal to the workspace path. - Other harnesses: check the harness's session directory for this workspace.
Outside Cursor, take the newest candidates first and confirm one by finding the conversation's opening user prompt in its first user message. If none matches, pass a tight digest of the session instead.
2. Spawn three reviewers in parallel
One message, three Task calls, subagent_type: generalPurpose, agent mode (readonly: false). Reviewers need MCP access to look up the tickets, chat threads, and observability traces the transcript references, and readonly strips MCPs.
Other harnesses. The spawns in this skill use Cursor's Task tool. In another harness, use its subagent tool: Agent in Claude Code (subagent_type: general-purpose), task in OpenCode (subagent_type: general), spawn_agent in Codex. Keep the prompt and the model. Drop parameters your tool doesn't have. If your harness has no subagent tool, as in Pi without an extension, run each role yourself, one after another.
Each reviewer and the synthesizer name a role line in the pstack settings file (~/.cursor/rules/pstack-models.mdc in Cursor, ~/.claude/rules/pstack-models.md in Claude Code, ~/.agents/pstack-models.md in other harnesses) and a default. Set model to that line's value, or to the default if the file or the line is missing. Leave model unset when the value is auto or inherit-parent. If your subagent tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message or your harness's model list. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the poteto-mode skill.
| Lens | Role line | Default model |
Prompt template |
|---|---|---|---|
| Judgment | reflect judgment, divergent, synthesizer |
claude-opus-5-5-xhigh |
references/judgment-reviewer.md |
| Tooling | reflect tooling |
grok-4.7-xhigh-fast |
references/tooling-reviewer.md |
| Divergent | reflect judgment, divergent, synthesizer |
claude-opus-5-5-xhigh |
references/divergent-reviewer.md |
Pass each template verbatim, substituting the transcript path or digest where marked. Reviewers return findings in the Task response body.
3. Synthesize
One Task call, subagent_type: generalPurpose, model from the reflect judgment, divergent, synthesizer line (default claude-opus-5-5-xhigh), agent mode (readonly: false). It spot-verifies citations through MCP, and readonly strips MCPs. Pass references/synthesizer.md verbatim, with each reviewer's full output inlined where marked. It returns an Accepted / Rejected / Backlog list.
4. Structural enforcement check
Move any Accepted item that a lint rule, script, metadata flag, or runtime check would enforce more reliably to Backlog. See the encode-lessons-in-structure principle skill.
5. Apply
Present the synthesizer's full Accepted / Rejected / Backlog output and wait for explicit approval before applying any Accepted edit. The user picks the subset and may redirect routings. Skill changes affect every future agent in the org. Do not auto-apply.
File each Backlog item to your team's devex or backlog tracker without waiting. Only the Accepted list waits for approval.
Never edit a skill under plugins/cache/. Before approval, show its destination: .cursor/skills/<skill>/ or ~/.cursor/skills/<skill>/ in Cursor, or your harness's project or user skill folder, such as .claude/skills/<skill>/ or ~/.agents/skills/<skill>/. After approval, copy the skill folder there and edit the copy. Never open a PR or push.
Follow each approved row's Routing exactly:
- Trivial existing-skill edit (a one-line bullet, a tightened sentence, a stale fact corrected): the parent does it directly.
- Substantive existing-skill edit (a new section, a new pattern table, more than ~10 lines): hand to your harness's skill-authoring skill and run its draft / test / iterate loop. That is
create-skillin Cursor (built in) or Anthropic'sskill-creator. If you have neither, follow the Agent Skills format at agentskills.io. "create-skill" below means whichever of these you use. tune description: <skill path>(the skill exists but didn't trigger when it should have): hand tocreate-skilland run its description-optimization loop.new skill via create-skill: <kebab-name>: hand creation tocreate-skill. Do not invent the shape ad hoc.
If your environment ships a SKILL.md validator, run it on every touched skill before declaring done.
6. Summarize for the user
Short list, no preamble:
- Edits applied:
<skill path>. What changed, one line each. - New skills created:
<skill path>. One line each (rare). - Backlog filed to the devex tracker:
<issue title>(<tags>). One line each. - Dropped: one line per rejected finding + reason from the synthesizer.
Original by Lauren Tan (poteto), MIT license. Checked against the pstack mirror at 97de40d. View on GitHub