Skip to content
  1. Skills at a glance
  2. Report, review, get smoother over time
  3. /pstack:reflect

/pstack:reflect

Call when needed

In 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.
Say it like this
/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.

Just askingWith /pstack:reflect
Edits skill files as soon as it spots a problem.Shows Accepted, Rejected and Backlog lists and waits for your approval before editing.
Records one-off events as lessons.Keeps only durable learnings and skips trivial chats.
Searches chat logs across every project.Looks for this chat's transcript only in the current workspace's session folder.

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

  1. 1Locate the active transcriptFinds this chat's transcript in your tool's session folder for this workspace and confirms it by the opening prompt.
  2. 2Spawn three reviewers in parallelStarts three helpers at once (judgment, tooling, divergent), each on the model the pstack settings file or default names.
  3. 3SynthesizeOne more helper spot-checks citations and merges the findings into Accepted, Rejected and Backlog lists.
  4. 4Structural enforcement checkMoves any accepted item that a lint, script, flag or runtime check would enforce better into Backlog.
  5. 5ApplyFiles Backlog items now, waits for approval on Accepted edits, edits a skill copy, and never opens a PR or pushes.
  6. 6Summarize for the userEnds with a short list: edits applied, new skills, Backlog filed, and findings dropped with reasons.

See the wording worth borrowingRead the full text

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.

  1. 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."
  2. 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'."
  3. 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."
  4. 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 has payload.cwd equal 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-skill in Cursor (built in) or Anthropic's skill-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 to create-skill and run its description-optimization loop.
  • new skill via create-skill: <kebab-name>: hand creation to create-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

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.