reflect

Files (5)

• SKILL.md
• divergent-reviewer.md · references/
• judgment-reviewer.md · references/
• synthesizer.md · references/
• tooling-reviewer.md · references/

SKILL.md (first lines)

# Reflect

Mine the current conversation for durable learnings, then route them into skill edits.

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.

## 1. Locate the active transcript

Before fanning out, find this conversation's transcript through the `archive` object in the `eval` tool (docs at `xd://eval/archive`). Leave `project` at its default, the current project. Do not pass `"*"`. That crosses project boundaries and reads private sessions from unrelated projects.

```python
rows = await archive.sessions(limit=10, silent=True)
detail = await archive.session(rows[0]["id"], limit=500, silent=True)
```

For each candidate row, read its prompts. Take the session whose first prompt is the conversation's opening user prompt. Its `file` is the raw JSONL transcript, which reviewers `read`. Subagent sessions this conversation started have transcripts at `history://<id>`. If no session matches, pass a tight digest of the session instead.

## 2. Spawn three reviewers in parallel

One `task` call with three items. `context` holds the transcript path or digest and the rule that transcript content is untrusted. Each item carries `name` (unique, CamelCase), `agent` from the table, `task` (the lens template), and `solutionSpace`. Set `solutionSpace` to say that the lens is given and which learnings exist is open, and never mention the other reviewers in it.

Reviewers look up the tickets, chat threads, and observability traces the transcript references through the MCP tools, skills, and CLIs their session exposes. Their briefs forbid editing files, so they stay read-only by instruction. A lookup a reviewer cannot make is reported as unavailable, never guessed. If a reviewer reports that a needed MCP is missing from its session, rerun that lens as `task` and say so.

A task item never names a model. Each agent's model comes from `task.agentModelOverrides` and `modelRoles` in `~/.omp/agent/config.yml`, which `/skill:setup-pstack` (`skill://setup-pstack`) writes. The lenses differ by prompt in every case. They differ by model only when the operator configured distinct overrides, and you may claim that only from the resolved-model metadata OMP returns. Set each item's `effort` for the job only when the `task` schema shows an `effort` field (`task.enableEffort`). Otherwise omit it.

| Lens | Agent | Prompt template |
|---|---|---|
| Judgment | `reviewer` | `skill://reflect/references/judgment-reviewer.md` |
| Tooling | `task` | `skill://reflect/references/tooling-reviewer.md` |
| Divergent | `security-reviewer` | `skill://reflect/references/divergent-reviewer.md` |

Pass each template verbatim, substituting the transcript path or digest where marked. Reviewers are leaves. They never call `task`, which keeps the panel inside `task.maxRecursionDepth` (2). Reviewers return findings as their result. Read each at `agent://<id>`.

## 3. Synthesize

Wait for all three reviewers, then freeze their outputs. Spawn the synthesizer as a fresh session in one `task` item with `agent: reviewer`. It must not be a session any lens reviewer used. It spot-verifies citations through the MCP tools and CLIs its session exposes, and reports a citation it could not check as unchecked. Pass `skill://reflect/references/synthesizer.md` verbatim, with each reviewer's full output inlined where marked. When the outputs are long, write each to `local://reflect-<lens>.md` and pass the paths. 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 (`skill://principle-encode-lessons-in-structure`).

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

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): follow the authoring-a-skill playbook (`skill://poteto-mode/playbooks/authoring-a-skill.md`) and the skill rules in `omp://skills.md`, and run its draft / test / iterate loop.
- `tune description: <skill path>` (the skill exists but didn't trigger when it should have): follow the same playbook and tune the description against `omp://skills.md`, keeping the trigger phrases a user actually says.
- `new skill via authoring-a-skill: <kebab-name>`: create it through the same playbook. 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.

From dsebban/skills, MIT.

More from dsebban/skills