Reflector (/mantis-reflect)
System Goal
Execution Trajectory Analyst. Analyzes the sequence of thoughts, tool calls, and
observations (the "trajectory" or "conversation") of the other Mantis agents.
Extracts valuable insights to prevent future agents from making the same
mistakes.
Command Definition
- Command:
/mantis-reflect
- Description: Parses execution trajectories from the current loop and
appends structured insights to
workspace/learnings.jsonl.
Input/Output Contract
- Reads:
workspace/.mantis_state.json (to track the current loop pass, and to read
active_snapshot.snapshot_id for provenance stamping — see Instructions
step 3). Read this file STATE-RELATIVE under --state_root; never derive
snapshot state by running live VCS.
- Subagent execution logs (
transcript.jsonl files). The schema
execution_log_entry defined in schema.json is the normalized
representation. The orchestrator/adapter must normalize raw logs from
unsupported frameworks before passing them, or the reflector must parse
unsupported formats on a best-effort basis.
- Locating Logs (harness-neutral): The orchestrator SHOULD pass the list
of absolute file paths to the execution log files (e.g.
transcript.jsonl)
for the subagents executed during this round; when provided, use these paths
directly. Do NOT hardcode any single framework's log layout. If no path list
was passed, resolve transcript paths from the ACTIVE harness's own
transcript convention — this is harness-specific and there are several. For
example, Antigravity stores them under
<appDataDir>/brain/<conversation_id>/.system_generated/logs/transcript.jsonl;
other harnesses (e.g. Gemini CLI, the Google ADK, Claude Code) use different
layouts. Antigravity is ONE example among several, not the default. If,
after both routes, no readable transcript exists for a stage that ran this
round, do NOT abort and do NOT silently emit zero learnings — record a
missing-transcript insight per Instructions step 1.
- Writes:
- Appends structured trajectory insights to
workspace/learnings.jsonl.
- Preconditions:
- Execution logs for the current round SHOULD exist and contain entries. If a
stage's log is missing, unreadable, empty, or yields zero parseable entries,
this is NOT a fatal error and NOT a reason to stop: continue with the other
stages and record the gap as a
trajectory_insight (see Instructions step
1) so an absent log is never a silent zero-learnings result.
- Idempotency Guarantee:
- Parses logs and filters already-recorded learnings to prevent duplicate
entries in
workspace/learnings.jsonl. It should check existing lines in
workspace/learnings.jsonl to ensure it doesn't duplicate the same insight
if retried.
- When de-duplicating, compare on the semantic content (
target_entity +
insight + source_stage) and treat snapshot as attached metadata, NOT
part of the identity, so a retry within the same pass does not
double-append. Missing-transcript insights (step 1) are de-duplicated the
same way.
Instructions
0. Locator Resolution (Block A — FINDINGS-ONLY role)
LOCATOR RESOLUTION (before reading ANY target code or artifact):
0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
state for provenance/annotation; NEVER stop merely because a code root is unset.
1. Determine CODE_ROOT, in this priority order:
a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
(used when a caller hands you a prepared tree, e.g. a patched shadow).
b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
c. Else read state_root/workspace/.mantis_state.json (state_root from
--state_root if passed, else ./workspace/... relative to the current dir)
-> active_snapshot.root / .snapshot_id / .snapshot_pinned.
d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
deliberately mutated and is sentinel-EXEMPT.)
3. PATH FIELDS:
- SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
NOT of the form <existing-path>:<integer> is a non-source LOCATOR
(symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
line-range and line-existence logic.
- STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
kb_references, repro_file_path, reattack_file_path, helper scripts, report
files, and all state/findings JSON.
4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
(mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
cd into CODE_ROOT.
5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
(the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
lacks .git/.hg/.repo.
6. Every shell command uses ABSOLUTE paths and sets its own working directory on
that call. Do NOT assume the working directory persists between calls.
Reflector is a FINDINGS-ONLY stage (same class as report and calibrate). Per
Block A step 0 it SKIPS steps 2-6 — it resolves NO CODE_ROOT, checks NO
.mantis_snapshot_id sentinel, and applies NO snapshot-relative path logic —
but it STILL reads active_snapshot from state for provenance and NEVER stops
because a code root is unset or unpinned. Reflector needs only --state_root to
locate workspace/.mantis_state.json, workspace/learnings.jsonl, and the
transcript log files; all of these are STATE-RELATIVE (Block A step 3) and MUST
NEVER be prefixed with CODE_ROOT. Reflector MUST NOT run any live VCS command
(git/hg/repo); its only snapshot signal is active_snapshot.snapshot_id
read from state.
Analyze the execution trajectories of all successfully executed subagents in the
round (every stage that ran: history, summarize, architecture, threat-model,
plan, researcher, dedupe, review, critic, reproduce, chain, patch, calibrate) to
distill what went right and what went wrong.
Execute the reflection stage as follows:
Extract Trajectories (Token Optimization):
Do not attempt to read the entire, raw transcript.jsonl files natively
with read_file, as they can be massive and blow out your context window.
Use the absolute log file paths passed to you by the orchestrator to access
the log files.
Instead of reading the full files, use your bash/command execution tools to
parse and filter the logs. For example, write a short Python script or use
jq/grep to extract key events (which should conform to the
execution_log_entry schema; if raw logs from different frameworks are
provided, parse them on a best-effort basis): tool error messages, final
agent summaries, instances where an agent "gave up", or messages indicating
a trust boundary assumption was incorrect.
Missing / empty logs (never silent): For each stage that ran this round
whose transcript is missing, unreadable, empty, or yields zero parseable
entries, append exactly one trajectory_insight with action: "add",
source_stage: "mantis-reflect",
target_entity: "<stage-name> transcript", and an insight naming the
stage and the reason (e.g. "no transcript file at ", "empty log", "0
parseable entries"). Do this BEFORE synthesizing insights, so even a fully
empty round produces auditable output instead of nothing.
Synthesize Insights: Review the extracted events. Look for:
- False Assumptions: Did a researcher spend turns trying to exploit a
parameter, only to realize it was sanitized upstream in another file?
- Tool Failures: Did the reproducer fail consistently because of a
missing library in the sandbox?
- Successful Strategies: Did a patcher successfully fix a bug using a
specific idiomatic pattern that should be reused?
Append to the Inbox (workspace/learnings.jsonl): For each distinct
insight, append a structured JSON object to workspace/learnings.jsonl.
Reflection Schema Format (workspace/learnings.jsonl)
{"type": "trajectory_insight", "action": "add | update | remove", "target_entity": "[e.g., auth_module.py or sandbox_env]", "insight": "The researcher assumed input was unsanitized, but it is actually cleansed by the middleware. Do not attempt XSS on this parameter.", "source_stage": "mantis-researcher", "snapshot": "<active_snapshot.snapshot_id from state; omit field entirely if unavailable>"}
Snapshot provenance stamp (never live VCS): Before writing, read
active_snapshot.snapshot_id from workspace/.mantis_state.json
(STATE-RELATIVE, under --state_root). Set the OPTIONAL snapshot field on
EVERY emitted trajectory_insight (including the missing-transcript insights
from step 1) to that value, so each learning is attributable to the pass's
pinned snapshot. Do NOT run git/hg/repo or any live VCS command to
derive it. Backward-compat: if active_snapshot is absent, snapshot is
empty/null, or state is unreadable, OMIT the snapshot field entirely and
proceed (degraded) — never stop and never fabricate an id. snapshot is an
OPTIONAL field: the trajectory_insight sub-schema in schema.json does not
set additionalProperties: false, so existing consumers accept it unchanged.
Ensure the file is appended to, not overwritten. When complete, notify the
user.
1---
2name: mantis-reflect
3description: >-
4 Extracts learnings from execution trajectories at the end of a Mantis loop.
5 Use to parse agent conversations, extract successes, failures, and false assumptions, and append them to workspace/learnings.jsonl.
6 Don't use for analyzing source code or writing patches.
7metadata:
8 source: https://skillmd.com/skills/google/mantis-reflect
9---
10
11# Reflector (/mantis-reflect)
12
13## System Goal
14
15Execution Trajectory Analyst. Analyzes the sequence of thoughts, tool calls, and
16observations (the "trajectory" or "conversation") of the other Mantis agents.
17Extracts valuable insights to prevent future agents from making the same
18mistakes.
19
20## Command Definition
21
22- **Command:** `/mantis-reflect`
23- **Description:** Parses execution trajectories from the current loop and
24 appends structured insights to `workspace/learnings.jsonl`.
25
26## Input/Output Contract
27
28- **Reads**:
29 - `workspace/.mantis_state.json` (to track the current loop pass, and to read
30 `active_snapshot.snapshot_id` for provenance stamping — see Instructions
31 step 3). Read this file STATE-RELATIVE under `--state_root`; never derive
32 snapshot state by running live VCS.
33 - Subagent execution logs (`transcript.jsonl` files). The schema
34 `execution_log_entry` defined in `schema.json` is the normalized
35 representation. The orchestrator/adapter must normalize raw logs from
36 unsupported frameworks before passing them, or the reflector must parse
37 unsupported formats on a best-effort basis.
38 - **Locating Logs (harness-neutral):** The orchestrator SHOULD pass the list
39 of absolute file paths to the execution log files (e.g. `transcript.jsonl`)
40 for the subagents executed during this round; when provided, use these paths
41 directly. Do NOT hardcode any single framework's log layout. If no path list
42 was passed, resolve transcript paths from the ACTIVE harness's own
43 transcript convention — this is harness-specific and there are several. For
44 example, Antigravity stores them under
45 `<appDataDir>/brain/<conversation_id>/.system_generated/logs/transcript.jsonl`;
46 other harnesses (e.g. Gemini CLI, the Google ADK, Claude Code) use different
47 layouts. Antigravity is ONE example among several, not the default. If,
48 after both routes, no readable transcript exists for a stage that ran this
49 round, do NOT abort and do NOT silently emit zero learnings — record a
50 missing-transcript insight per Instructions step 1.
51- **Writes**:
52 - Appends structured trajectory insights to `workspace/learnings.jsonl`.
53- **Preconditions**:
54 - Execution logs for the current round SHOULD exist and contain entries. If a
55 stage's log is missing, unreadable, empty, or yields zero parseable entries,
56 this is NOT a fatal error and NOT a reason to stop: continue with the other
57 stages and record the gap as a `trajectory_insight` (see Instructions step
58 1\) so an absent log is never a silent zero-learnings result.
59- **Idempotency Guarantee**:
60 - Parses logs and filters already-recorded learnings to prevent duplicate
61 entries in `workspace/learnings.jsonl`. It should check existing lines in
62 `workspace/learnings.jsonl` to ensure it doesn't duplicate the same insight
63 if retried.
64 - When de-duplicating, compare on the semantic content (`target_entity` +
65 `insight` + `source_stage`) and treat `snapshot` as attached metadata, NOT
66 part of the identity, so a retry within the same pass does not
67 double-append. Missing-transcript insights (step 1) are de-duplicated the
68 same way.
69
70## Instructions
71
72### 0. Locator Resolution (Block A — FINDINGS-ONLY role)
73
74```
75LOCATOR RESOLUTION (before reading ANY target code or artifact):
760. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
77 you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
78 state for provenance/annotation; NEVER stop merely because a code root is unset.
791. Determine CODE_ROOT, in this priority order:
80 a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
81 It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
82 (used when a caller hands you a prepared tree, e.g. a patched shadow).
83 b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
84 c. Else read state_root/workspace/.mantis_state.json (state_root from
85 --state_root if passed, else ./workspace/... relative to the current dir)
86 -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
87 d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
88 treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
892. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
90 verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
91 or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
92 deliberately mutated and is sentinel-EXEMPT.)
933. PATH FIELDS:
94 - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
95 that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
96 containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
97 NOT of the form <existing-path>:<integer> is a non-source LOCATOR
98 (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
99 line-range and line-existence logic.
100 - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
101 kb_references, repro_file_path, reattack_file_path, helper scripts, report
102 files, and all state/findings JSON.
1034. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
104 compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
105 (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
106 cd into CODE_ROOT.
1075. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
108 run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
109 (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
110 lacks .git/.hg/.repo.
1116. Every shell command uses ABSOLUTE paths and sets its own working directory on
112 that call. Do NOT assume the working directory persists between calls.
113```
114
115Reflector is a FINDINGS-ONLY stage (same class as report and calibrate). Per
116Block A step 0 it SKIPS steps 2-6 — it resolves NO CODE_ROOT, checks NO
117`.mantis_snapshot_id` sentinel, and applies NO snapshot-relative path logic —
118but it STILL reads `active_snapshot` from state for provenance and NEVER stops
119because a code root is unset or unpinned. Reflector needs only `--state_root` to
120locate `workspace/.mantis_state.json`, `workspace/learnings.jsonl`, and the
121transcript log files; all of these are STATE-RELATIVE (Block A step 3) and MUST
122NEVER be prefixed with CODE_ROOT. Reflector MUST NOT run any live VCS command
123(`git`/`hg`/`repo`); its only snapshot signal is `active_snapshot.snapshot_id`
124read from state.
125
126Analyze the execution trajectories of all successfully executed subagents in the
127round (every stage that ran: history, summarize, architecture, threat-model,
128plan, researcher, dedupe, review, critic, reproduce, chain, patch, calibrate) to
129distill what went right and what went wrong.
130
131Execute the reflection stage as follows:
132
1331. **Extract Trajectories (Token Optimization):**
134
135 - Do not attempt to read the entire, raw `transcript.jsonl` files natively
136 with `read_file`, as they can be massive and blow out your context window.
137
138 - Use the absolute log file paths passed to you by the orchestrator to access
139 the log files.
140
141 - Instead of reading the full files, use your bash/command execution tools to
142 parse and filter the logs. For example, write a short Python script or use
143 `jq`/`grep` to extract key events (which should conform to the
144 `execution_log_entry` schema; if raw logs from different frameworks are
145 provided, parse them on a best-effort basis): tool error messages, final
146 agent summaries, instances where an agent "gave up", or messages indicating
147 a trust boundary assumption was incorrect.
148
149 - **Missing / empty logs (never silent):** For each stage that ran this round
150 whose transcript is missing, unreadable, empty, or yields zero parseable
151 entries, append exactly one `trajectory_insight` with `action: "add"`,
152 `source_stage: "mantis-reflect"`,
153 `target_entity: "<stage-name> transcript"`, and an `insight` naming the
154 stage and the reason (e.g. "no transcript file at <path>", "empty log", "0
155 parseable entries"). Do this BEFORE synthesizing insights, so even a fully
156 empty round produces auditable output instead of nothing.
157
1582. **Synthesize Insights:** Review the extracted events. Look for:
159
160 - **False Assumptions:** Did a researcher spend turns trying to exploit a
161 parameter, only to realize it was sanitized upstream in another file?
162 - **Tool Failures:** Did the reproducer fail consistently because of a
163 missing library in the sandbox?
164 - **Successful Strategies:** Did a patcher successfully fix a bug using a
165 specific idiomatic pattern that should be reused?
166
1673. **Append to the Inbox (`workspace/learnings.jsonl`):** For each distinct
168 insight, append a structured JSON object to `workspace/learnings.jsonl`.
169
170 ### Reflection Schema Format (`workspace/learnings.jsonl`)
171
172 ```json
173 {"type": "trajectory_insight", "action": "add | update | remove", "target_entity": "[e.g., auth_module.py or sandbox_env]", "insight": "The researcher assumed input was unsanitized, but it is actually cleansed by the middleware. Do not attempt XSS on this parameter.", "source_stage": "mantis-researcher", "snapshot": "<active_snapshot.snapshot_id from state; omit field entirely if unavailable>"}
174 ```
175
176 **Snapshot provenance stamp (never live VCS):** Before writing, read
177 `active_snapshot.snapshot_id` from `workspace/.mantis_state.json`
178 (STATE-RELATIVE, under `--state_root`). Set the OPTIONAL `snapshot` field on
179 EVERY emitted `trajectory_insight` (including the missing-transcript insights
180 from step 1) to that value, so each learning is attributable to the pass's
181 pinned snapshot. Do NOT run `git`/`hg`/`repo` or any live VCS command to
182 derive it. Backward-compat: if `active_snapshot` is absent, `snapshot` is
183 empty/null, or state is unreadable, OMIT the `snapshot` field entirely and
184 proceed (degraded) — never stop and never fabricate an id. `snapshot` is an
185 OPTIONAL field: the `trajectory_insight` sub-schema in `schema.json` does not
186 set `additionalProperties: false`, so existing consumers accept it unchanged.
187
188 Ensure the file is appended to, not overwritten. When complete, notify the
189 user.