Summarizer (/mantis-summarize)
System Goal
Repository Mapper. Automates the generation of security-focused, deterministic
summaries of directory contents to reduce token overhead for downstream planning
and research stages.
Command Definition
- Command:
/mantis-summarize
- Description: Pre-processes the repository by generating security-focused
summaries (
mantis-summary.md) for each directory to make planning and
research more efficient.
- Arguments (optional; supplied by the orchestrator, consumed by Block A):
--snapshot_root/--snapshot_id/--state_root. In PINNED mode, source is
read under CODE_ROOT but summaries are skipped (see Output location). All
absent → MODE-OFF (in-tree summaries, as today).
Input/Output Contract
- Reads:
workspace/.mantis_state.json (to track current loop pass).
- Codebase directories and source files (excluding
node_modules, vendor,
.git, build outputs, and tests/).
- Child directory summaries (
mantis-summary.md files from subdirectories).
workspace/historical_learnings.jsonl (optional, to enrich summaries).
- Writes:
- Traversal script to workspace.
- MODE-OFF:
mantis-summary.md in each source directory (as today). PINNED:
skipped (see Output location).
- Preconditions:
- Source files and directory structure must be present.
- Idempotency Guarantee:
- Deterministically overwrites existing
mantis-summary.md files in-place
with updated rollups.
Instructions
Step 0: Locator Resolution + output location (run first)
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.
Output location (MANDATORY):
- PINNED mode (snapshot_pinned true): summaries are skipped this pass. In
PINNED mode, CODE_ROOT is read-only (Block A step 4), and consumers (plan,
history, researcher) read
mantis-summary.md from the source directory in the
code tree — not from a state-relative mirror. Writing to a mirror that no
consumer reads would silently waste the work. Do NOT write any
mantis-summary.md files in PINNED mode. (If a future change wires consumers
to the mirror + re-maps via a provenance marker, this can be revisited; for
now, PINNED-mode summaries are inert.)
- HALT mode (active_snapshot present + snapshot_pinned=false): behave as
MODE-OFF (write
mantis-summary.md into each source directory). The snapshot
is not read-only (no immutable copy was pinned), so writing into the tree is
safe.
- MODE-OFF (no
active_snapshot — today's default): behave exactly as today —
write mantis-summary.md into each source directory.
- In all modes except PINNED,
mantis-summary.md files must remain invisible to
every VCS dirty check and be deleted from the target tree before any sync (the
meta-agent enforces this in Block C STEP 0). Never let a summary make the tree
look dirty.
Your task is to write and execute a script that will traverse the repository
directory tree and create a mantis-summary.md file in each directory
containing source code.
This is an optional pre-processing phase designed to drastically reduce the
context window size required for the strategist (/mantis-plan), and provide a
quick reference map for researchers (/mantis-researcher).
Execute the summarize stage as follows:
Write the Traversal Script (Bottom-Up Hierarchical): Write a script
(e.g., Python or bash) in your workspace that walks the repository directory
tree using a bottom-up (post-order) traversal.
- The script must ignore non-source-code directories such as
node_modules,
vendor, .git, build outputs, and tests/.
- By traversing bottom-up, the script ensures that subdirectories are
summarized before their parent directories.
- When analyzing a directory, the script should pass the LLM the local source
files in that directory PLUS the
mantis-summary.md files of its
immediate subdirectories. Do not pass the raw source files of
subdirectories to the parent.
- When analyzing very large directories, context window size might become a
problem. Instead of passing files and directory summaries in bulk, generate
per-file summaries or operate in more efficient chunks to avoid passing too
many tokens for the LLM to handle.
Generate the Security Summary (Map-Reduce): The script should read
workspace/historical_learnings.jsonl (if it exists) to check for past
vulnerabilities and security fixes associated with files in the current
directory, and pass them in context. The script should instruct the LLM or
agent tool to generate a concise, security-focused summary of the directory.
To keep token lengths reasonable at higher levels of the directory tree, the
LLM should abstract away lower-level details, focusing on the rolled-up
architecture. The prompt used by your script should ask for:
- Core Components: What are the primary files and subdirectories, and
what do they do?
- API Endpoints & Exports: What functions or classes are exposed to other
modules?
- Trust Boundaries & External Inputs: Does this directory handle
untrusted data, network requests, or user input?
- Sensitive Operations: Are there parsers, cryptographic functions, or
memory management operations?
- Historical Vulnerabilities & Fixes: What files or components in this
directory have historical vulnerabilities or security-related fixes
recorded in
workspace/historical_learnings.jsonl? Summarize the past
fixes, components affected, and vulnerability classes to highlight past
regressions or recurring weaknesses.
The summary must be a reasonable size to incorporate into work on larger
problems, so aim for several thousand words or fewer.
Output to mantis-summary.md: In MODE-OFF (or HALT), write
mantis-summary.md into the corresponding source directory (overwrite if
present). In PINNED mode, do NOT write — summaries are skipped this pass (see
Output location above). Never write into the read-only snapshot.
Execute the Script: Run the script you just wrote to generate all the
summaries across the repository. Wait for it to finish successfully.
Complete: Summaries are now generated. Notify the user.
When complete, notify the user.
1---
2name: mantis-summarize
3description: >-
4 Pre-processes the repository by generating security-focused summaries (mantis-summary.md) for each directory to make planning and research more efficient.
5 Use when starting a review campaign to map the codebase before threat modeling and planning.
6 Don't use for executing code reviews, writing test scripts, or patching code.
7metadata:
8 source: https://skillmd.com/skills/google/mantis-summarize
9---
10
11# Summarizer (/mantis-summarize)
12
13## System Goal
14
15Repository Mapper. Automates the generation of security-focused, deterministic
16summaries of directory contents to reduce token overhead for downstream planning
17and research stages.
18
19## Command Definition
20
21- **Command:** `/mantis-summarize`
22- **Description:** Pre-processes the repository by generating security-focused
23 summaries (`mantis-summary.md`) for each directory to make planning and
24 research more efficient.
25- **Arguments (optional; supplied by the orchestrator, consumed by Block A):**
26 `--snapshot_root`/`--snapshot_id`/`--state_root`. In PINNED mode, source is
27 read under CODE_ROOT but summaries are skipped (see Output location). All
28 absent → MODE-OFF (in-tree summaries, as today).
29
30## Input/Output Contract
31
32- **Reads**:
33 - `workspace/.mantis_state.json` (to track current loop pass).
34 - Codebase directories and source files (excluding `node_modules`, `vendor`,
35 `.git`, build outputs, and `tests/`).
36 - Child directory summaries (`mantis-summary.md` files from subdirectories).
37 - `workspace/historical_learnings.jsonl` (optional, to enrich summaries).
38- **Writes**:
39 - Traversal script to workspace.
40 - MODE-OFF: `mantis-summary.md` in each source directory (as today). PINNED:
41 skipped (see Output location).
42- **Preconditions**:
43 - Source files and directory structure must be present.
44- **Idempotency Guarantee**:
45 - Deterministically overwrites existing `mantis-summary.md` files in-place
46 with updated rollups.
47
48## Instructions
49
50### Step 0: Locator Resolution + output location (run first)
51
52```
53LOCATOR RESOLUTION (before reading ANY target code or artifact):
540. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
55 you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
56 state for provenance/annotation; NEVER stop merely because a code root is unset.
571. Determine CODE_ROOT, in this priority order:
58 a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
59 It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
60 (used when a caller hands you a prepared tree, e.g. a patched shadow).
61 b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
62 c. Else read state_root/workspace/.mantis_state.json (state_root from
63 --state_root if passed, else ./workspace/... relative to the current dir)
64 -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
65 d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
66 treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
672. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
68 verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
69 or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
70 deliberately mutated and is sentinel-EXEMPT.)
713. PATH FIELDS:
72 - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
73 that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
74 containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
75 NOT of the form <existing-path>:<integer> is a non-source LOCATOR
76 (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
77 line-range and line-existence logic.
78 - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
79 kb_references, repro_file_path, reattack_file_path, helper scripts, report
80 files, and all state/findings JSON.
814. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
82 compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
83 (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
84 cd into CODE_ROOT.
855. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
86 run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
87 (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
88 lacks .git/.hg/.repo.
896. Every shell command uses ABSOLUTE paths and sets its own working directory on
90 that call. Do NOT assume the working directory persists between calls.
91```
92
93Output location (MANDATORY):
94
95- PINNED mode (snapshot_pinned true): summaries are **skipped** this pass. In
96 PINNED mode, CODE_ROOT is read-only (Block A step 4), and consumers (plan,
97 history, researcher) read `mantis-summary.md` from the source directory in the
98 code tree — not from a state-relative mirror. Writing to a mirror that no
99 consumer reads would silently waste the work. Do NOT write any
100 `mantis-summary.md` files in PINNED mode. (If a future change wires consumers
101 to the mirror + re-maps via a provenance marker, this can be revisited; for
102 now, PINNED-mode summaries are inert.)
103- HALT mode (active_snapshot present + snapshot_pinned=false): behave as
104 MODE-OFF (write `mantis-summary.md` into each source directory). The snapshot
105 is not read-only (no immutable copy was pinned), so writing into the tree is
106 safe.
107- MODE-OFF (no `active_snapshot` — today's default): behave exactly as today —
108 write `mantis-summary.md` into each source directory.
109- In all modes except PINNED, `mantis-summary.md` files must remain invisible to
110 every VCS dirty check and be deleted from the target tree before any sync (the
111 meta-agent enforces this in Block C STEP 0). Never let a summary make the tree
112 look dirty.
113
114Your task is to write and execute a script that will traverse the repository
115directory tree and create a `mantis-summary.md` file in each directory
116containing source code.
117
118This is an **optional pre-processing phase** designed to drastically reduce the
119context window size required for the strategist (`/mantis-plan`), and provide a
120quick reference map for researchers (`/mantis-researcher`).
121
122Execute the summarize stage as follows:
123
1241. **Write the Traversal Script (Bottom-Up Hierarchical):** Write a script
125 (e.g., Python or bash) in your workspace that walks the repository directory
126 tree using a **bottom-up (post-order) traversal**.
127
128 - The script must ignore non-source-code directories such as `node_modules`,
129 `vendor`, `.git`, build outputs, and `tests/`.
130 - By traversing bottom-up, the script ensures that subdirectories are
131 summarized *before* their parent directories.
132 - When analyzing a directory, the script should pass the LLM the local source
133 files in that directory **PLUS** the `mantis-summary.md` files of its
134 immediate subdirectories. Do not pass the raw source files of
135 subdirectories to the parent.
136 - When analyzing very large directories, context window size might become a
137 problem. Instead of passing files and directory summaries in bulk, generate
138 per-file summaries or operate in more efficient chunks to avoid passing too
139 many tokens for the LLM to handle.
140
1412. **Generate the Security Summary (Map-Reduce):** The script should read
142 `workspace/historical_learnings.jsonl` (if it exists) to check for past
143 vulnerabilities and security fixes associated with files in the current
144 directory, and pass them in context. The script should instruct the LLM or
145 agent tool to generate a concise, security-focused summary of the directory.
146 To keep token lengths reasonable at higher levels of the directory tree, the
147 LLM should abstract away lower-level details, focusing on the rolled-up
148 architecture. The prompt used by your script should ask for:
149
150 - **Core Components:** What are the primary files and subdirectories, and
151 what do they do?
152 - **API Endpoints & Exports:** What functions or classes are exposed to other
153 modules?
154 - **Trust Boundaries & External Inputs:** Does this directory handle
155 untrusted data, network requests, or user input?
156 - **Sensitive Operations:** Are there parsers, cryptographic functions, or
157 memory management operations?
158 - **Historical Vulnerabilities & Fixes:** What files or components in this
159 directory have historical vulnerabilities or security-related fixes
160 recorded in `workspace/historical_learnings.jsonl`? Summarize the past
161 fixes, components affected, and vulnerability classes to highlight past
162 regressions or recurring weaknesses.
163
164 The summary must be a reasonable size to incorporate into work on larger
165 problems, so aim for several thousand words or fewer.
166
1673. **Output to `mantis-summary.md`:** In MODE-OFF (or HALT), write
168 `mantis-summary.md` into the corresponding source directory (overwrite if
169 present). In PINNED mode, do NOT write — summaries are skipped this pass (see
170 Output location above). Never write into the read-only snapshot.
171
1724. **Execute the Script:** Run the script you just wrote to generate all the
173 summaries across the repository. Wait for it to finish successfully.
174
1755. **Complete:** Summaries are now generated. Notify the user.
176
177When complete, notify the user.