0xrsydn/pstack-pi / skills/reflect
reflect
VerifiedSpawn 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.6 KB |
| references/divergent-reviewer.md | markdown | 3.9 KB |
| references/judgment-reviewer.md | markdown | 3.2 KB |
| references/synthesizer.md | markdown | 4.1 KB |
| references/tooling-reviewer.md | markdown | 4.7 KB |
SKILL.md
View on GitHub---
name: reflect
description: Spawn 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.
disable-model-invocation: true
---
# Reflect
Mine the current conversation for durable learnings, then route them into skill edits.
## When to invoke
- The user said "reflect" or "/reflect".
- A complex task (5+ tool calls) just landed cleanly and the recipe is worth keeping.
- The agent hit dead ends, found the working path, and the path generalizes.
- The user corrected the agent's approach mid-task.
- A non-trivial workflow emerged that isn't captured anywhere.
Skip when the conversation is trivial, off-topic, or already covered by an existing skill the parent followed correctly. One-offs are not learnings.
## Process
### 1. Locate the active transcript
The parent finds its own transcript file before fanning out. The system prompt names the active workspace's `agent-transcripts/` directory; use that path. Do not glob across `~/~/.pi/agent/sessions/*/`. That crosses workspace boundaries and reads private chats from unrelated projects.
```bash
ls -t <agent-transcripts>/*.jsonl <agent-transcripts>/*/*.jsonl <agent-transcripts>/*/subagents/*.jsonl 2>/dev/null | head -10
```
Three transcript layouts: legacy flat (`<id>.jsonl`), current nested (`<id>/<id>.jsonl`), and subagent (`<parent>/subagents/<child>.jsonl`).
For each candidate, read the first JSONL line and check that `message.content[0].text` contains the conversation's opening user prompt. Take the matching path. If no path resolves, write a tight digest of the session and pass that instead.
### 2. Spawn three reviewers in parallel
Use one parallel `pstack_task` call with three tasks. Set `agent: "general-purpose"` and `readonly: false`. Reviewers need Model Context Protocol (MCP) access for context lookups. The prompt forbids file writes; the parent applies edits.
| Lens | `model` | Prompt template |
|---|---|---|
| Judgment | `role: "reflect-judgment-divergent-synthesizer"` | `references/judgment-reviewer.md` |
| Tooling | `role: "reflect-tooling"` | `references/tooling-reviewer.md` |
| Divergent | `role: "reflect-judgment-divergent-synthesizer"` | `references/divergent-reviewer.md` |
Pass each template verbatim, substituting the transcript path or digest where marked. Reviewers return findings in the subagent output.
### 3. Synthesize
Use one `pstack_task` call with `agent: "general-purpose"`, `role: "reflect-judgment-divergent-synthesizer"`, and `readonly: false`. The synthesizer can use MCP access to spot-check citations. Use `references/synthesizer.md` verbatim and insert each full review where marked.
### 4. Structural enforcement check
Sanity-check the synthesizer's Accepted list. For any item that would be enforced more reliably by a lint rule, script, metadata flag, or runtime check, move it from Accepted to Backlog. The synthesizer already applies this criterion; this is a final pass before edits land. See the **encode-lessons-in-structure** principle skill.
### 5. Apply
Before applying any Accepted edit, present the synthesizer's full Accepted/Rejected/Backlog output to the user and wait for explicit approval. The user picks which subset to apply and may redirect routings. Skill changes affect every future agent in the org; do not auto-apply.
Backlog items file to whatever devex / backlog tracker your team uses automatically. Those are tracker submissions, not skill edits. Only the Accepted list waits for approval.
For each approved Accepted item, follow the Routing field exactly:
- Trivial existing-skill edit (a one-line bullet, a tightened sentence, a stale fact corrected): parent does directly.
- Substantive existing-skill edit (a new section, a new pattern table, more than ~10 lines): author per the skill-authoring-style loop below skill and run its draft / test / iterate loop.
- `tune description: <skill path>` (the skill exists but didn't trigger when it should have): author per the skill-authoring-style loop below and run its description-optimization loop.
- `new skill via skill-authoring: <kebab-name>`: draft and iterate the skill directly. Do not invent the shape ad hoc.
If your environment ships a SKILL.md validator, run it on every touched skill before declaring done. Skip this step if it doesn't.
### 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |