--- 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 Invoke when the user says "reflect" or "/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. **`reflect` or `retro`.** Reflect routes learnings into skill edits. A lesson that belongs in the repo or its environment instead (a lint rule or other automated check, a `CODING_STANDARDS.md` rule, an `AGENTS.md` navigation pointer, tool economy, access to logs or services) is a job for `/skill:retro` (`../../mattpocock/retro/SKILL.md`), which proposes those guardrails for the user to approve. Route such a finding there, or list it as Backlog, instead of forcing it into a skill edit. ## Process ### 1. Locate the active transcript The active transcript is `$PI_SESSION_FILE`, set in the bash tool. Use it directly when present. To choose an earlier transcript for this working directory, read only this working directory's sessions, per the session directory rule in `../poteto-mode/playbooks/session-pickup.md`. Never glob Pi's global session directory. Before grepping, reading or delegating an earlier session file, read only its first line, the session header, and check that its `cwd` is exactly this working directory: a session directory's encoded name can collide with another project's, and a directory can be shared. Skip any session whose header names another directory, or has none, without reading further. A child brief lists only the files that passed and tells the child to repeat this check before it greps or reads one. If no session file resolves, write a tight digest of the current session and pass that instead. ### 2. Spawn three reviewers in parallel Before these launches, follow the architecture preflight in `../poteto-mode/references/delegation.md`. Judgment, divergent and the synthesizer need `task:architecture`. Three independent bare `subagent` calls in one turn, per `../poteto-mode/references/fan-out.md`, each with a prompt that forbids file writes as its `systemPrompt` (`fork: false`) and no `tools` list. Reviewers may use MCPs available to their Pi child process for context lookups (tickets, chat threads, observability traces referenced in the transcript). The parent applies edits. | Lens | `model` | Prompt template | |---|---|---| | Judgment | `task:architecture` | `references/judgment-reviewer.md` | | Tooling | exact model from another family | `references/tooling-reviewer.md` | | Divergent | `task:architecture` | `references/divergent-reviewer.md` | Judgment and divergent are judgment seats: `model` is `task:architecture` and `thinking` is `high` or above only when that category has no configured thinking (otherwise omit it), the same category as other judgment and prose synthesis (`../poteto-mode/references/delegation.md`). The tooling lens is a diversity seat per `../poteto-mode/references/fan-out.md` section 3. Read the family of the first model listed for architecture under Task-category shortlists, and give tooling an exact authenticated `provider/model-id` from a different family. With no other authenticated family, run tooling on a same-family model and say the lens is context-isolated, not cross-family. If the architecture launch falls back to a later candidate, check the delivered model's family, and if it matches the tooling lens, relabel that lens as context-isolated. Reviewers never get a raw transcript. Before any launch, write a redacted copy of each transcript to a new file in a fresh temporary directory outside the repo (`mktemp -d`, file mode 600). In the copy, replace every secret, token, password, private key, credential and credential-bearing URL, and the whole output of any tool call that read a `.env*` or credential file, with `[REDACTED: , ]`. Check the copy before passing it on, and delete the directory once synthesis is done. A digest follows the same rule. Pass each template verbatim as `systemPrompt`, and put the redacted copy's path for ``, or the redacted digest, in `task`. Reviewers return findings in their delivered `subagent` results. Each template forbids quoting a secret, token, credential or credential-bearing URL: a finding refers to one by its location and quotes only bounded excerpts. That matters most for the tooling lens, which sends the transcript to another model family. ```json subagent { "name": "reflect-judgment", "task": " is . . Do not write files. You are a leaf: launch nothing.", "systemPrompt": "", "model": "task:architecture", "fork": false } ``` The divergent reviewer differs only in `name` and prompt file. The tooling reviewer uses the diversity-seat model: ```json subagent { "name": "reflect-tooling", "task": " is . . Do not write files. You are a leaf: launch nothing.", "systemPrompt": "", "model": "/", "thinking": "high", "fork": false } ``` ### 3. Synthesize After all three reviewers have delivered, one bare `subagent` call on `task:architecture` with no `tools` list. The synthesizer may use MCPs available to its Pi child process to spot-check citations. Use `references/synthesizer.md` verbatim as `systemPrompt`, with each reviewer's full output in `task` under its marker, after you remove any secret, token, credential or credential-bearing URL that slipped into it (refer to it by location instead). The `task` tells the synthesizer to drop any that remain. ```json subagent { "name": "reflect-synthesizer", "task": ": . : . : . Drop any secret, token, credential or credential-bearing URL a reviewer output still quotes, and refer to it by its location instead. Do not write files. You are a leaf: launch nothing.", "systemPrompt": "", "model": "task:architecture", "fork": false } ``` The synthesizer returns a structured Accepted / Rejected / Backlog list. ### 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. See the **principle-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 go to whatever devex / backlog tracker your team uses. Filing one is an external action under `../poteto-mode/references/authorization.md`, so present the Backlog list with the Accepted list and file only the items the user approves. Never edit a packaged or cache install of a skill in place. Before approval, show each skill's destination: the project's `.pi/skills//`, or the user's Pi skills directory such as `~/.pi/agent/skills//` when the user chose a personal install. After approval, copy the skill folder there and edit the copy. Never open a PR or push for a skill install. 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): draft, test and iterate it per the authoring playbook (`../poteto-mode/playbooks/authoring-a-skill.md`) and Pi's skills documentation (`docs/skills.md` in the installed Pi package). - `tune description: ` (the skill exists but didn't trigger when it should have): rewrite the description per Pi's skills documentation, which says the description determines when the model considers loading the skill. - `new skill via Pi skill authoring: `: create it per the authoring playbook (`../poteto-mode/playbooks/authoring-a-skill.md`) and Pi's skills documentation. 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: ``. What changed, one line each. - New skills created: ``. One line each (rare). - Backlog filed to the devex tracker with the user's approval: `` (``). One line each. List unapproved Backlog items as not filed. - Dropped: one line per rejected finding + reason from the synthesizer.