# Reflect

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

- Skill: `finografic/reflect` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx get-skill add finografic/reflect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/finografic/reflect/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: finografic (https://skillmd.com/u/finografic)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/finografic/reflect

---


# 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. Transcript location is harness-specific — Claude Code keeps them under `~/.claude/projects/<slug>/`, Cursor under `~/.cursor/projects/<slug>/agent-transcripts/`. If the system prompt names a transcript directory for the active workspace, that path wins. **Scope the glob to the active workspace's directory only.** Globbing across `~/.<harness>/projects/*/` crosses workspace boundaries and reads private chats from unrelated projects.

```bash
ls -t <transcript-dir>/*.jsonl <transcript-dir>/*/*.jsonl <transcript-dir>/*/subagents/*.jsonl 2>/dev/null | head -10
```

Three transcript layouts to expect: flat (`<id>.jsonl`), 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 general-purpose subagents. Give them tool access rather than read-only mode: reviewers need MCP access for context lookups (tickets, chat threads, observability traces referenced in the transcript), and read-only modes commonly strip MCPs. The prompt forbids file writes; the parent applies edits.

| Lens | Prompt template |
|---|---|
| Judgment | `references/judgment-reviewer.md` |
| Tooling | `references/tooling-reviewer.md` |
| Divergent | `references/divergent-reviewer.md` |

Pass each template verbatim, substituting the transcript path or digest where marked. Reviewers return findings in their response bodies.

If the harness lets you set a model or reasoning effort per subagent, give the divergent lens a different model from the judgment lens — the three lenses exist to disagree, and identical runners weaken that. Where it does not, the distinct prompts still carry most of the separation.

### 3. Synthesize

One general-purpose subagent, with tool access rather than read-only: the synthesizer's quality check includes spot-verifying citations, which can require MCP access. 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.

### 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 whatever skill-authoring skill this harness ships (Claude Code has `skill-creator`; several harnesses ship a `create-skill`) and run its draft / test / iterate loop. If none exists, draft the edit, then re-read the whole skill cold and cut anything the edit made redundant.
- `tune description: <skill path>` (the skill exists but didn't trigger when it should have): the description is the entire trigger mechanism. Rewrite it to lead with the use case and name the concrete words a user would actually say. Hand to the authoring skill's description-optimization loop where one exists.
- `new skill: <kebab-name>`: hand creation to the authoring skill. Do not invent the shape ad hoc — a new skill needs a `name`, a trigger-shaped `description`, and bulk content in `references/` rather than in the body.

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.

