Extracts learnings from execution trajectories at the end of a Mantis loop. Use to parse agent conversations, extract successes, failures, and false assumptions, and append them to workspace/learnings.jsonl. Don't use for analyzing source code or writing patches.

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) 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: 1. 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 <path ", "empty log", "0 parseable entries"). Do this BEFORE synthesizing insights, so even a fully empty round produces auditable output instead of nothing. 2. 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? 3. 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 ) 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.

mantis-reflect