git:20260828.7c3522d to git:20260907.b1269d9

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

- 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. Resolve `../recall/scripts/find-transcripts.mjs` relative to this `SKILL.md`. Run it with `node`, `--host claude`, `--workspace` set to the active workspace, and `--limit 10`. The helper reads JSONL `cwd` metadata and returns only this workspace's transcripts in modification-time order. Never replace it with a whole-store content scan, which can read private chats from unrelated projects.

-

- 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

-

- One message, three read-only subagents that cannot edit or write, an explicit model on each. Reviewers need MCP access for context lookups (tickets, chat threads, observability traces referenced in the transcript); Read-only keeps MCPs and blocks writes, so the parent stays the only writer.

-

- | Lens | `model` | Prompt template |

- |---|---|---|

- | Judgment | your configured reflect-judgment model (defaults to your judgment model) | `references/judgment-reviewer.md` |

- | Tooling | your configured reflect-tooling model (defaults to your precise-execution model) | `references/tooling-reviewer.md` |

- | Divergent | your configured reflect-judgment model (defaults to your judgment model) | `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 read-only subagent using your configured reflect-judgment model (defaults to your judgment model). The synthesizer's quality check includes spot-verifying citations, which can require MCP access; A read-only subagent keeps MCPs and blocks writes. Use `references/synthesizer.md` verbatim, with each reviewer's full output inlined where marked. 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. 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): hand to the **Authoring a skill** playbook (`poteto-mode/playbooks/authoring-a-skill.md`) and run its draft / test / iterate loop.

- - `tune description: <skill path>` (the skill exists but didn't trigger when it should have): run the description-optimization loop in the **Authoring a skill** playbook (`poteto-mode/playbooks/authoring-a-skill.md`).

- - `new skill: <kebab-name>`: hand creation to the **Authoring a skill** playbook (`poteto-mode/playbooks/authoring-a-skill.md`). 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.