mantis-summarize

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Summarizer (/mantis-summarize)

摘要生成工具（/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).

命令：
```
/mantis-summarize
```
描述： 通过为每个目录生成以安全为核心的摘要（
```
mantis-summary.md
```
）对代码仓库进行预处理，提升规划与调研效率。
参数（可选；由编排器提供，供模块A使用）：
```
--snapshot_root
```
/
```
--snapshot_id
```
/
```
--state_root
```
。在PINNED模式下，从CODE_ROOT读取源码，但跳过摘要生成（见输出位置）。若所有参数缺失→MODE-OFF模式（树内生成摘要，与当前逻辑一致）。

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.

读取内容：
- ```
workspace/.mantis_state.json
```
  （用于跟踪当前循环进度）。
- 代码库目录与源码文件（排除
```
node_modules
```
  、
```
vendor
```
  、
```
.git
```
  、构建输出及
```
tests/
```
  目录）。
- 子目录摘要（来自子目录的
```
mantis-summary.md
```
  文件）。
- ```
workspace/historical_learnings.jsonl
```
  （可选，用于丰富摘要内容）。
写入内容：
- 遍历脚本至工作区。
- MODE-OFF模式：在每个源码目录中生成
```
mantis-summary.md
```
  （与当前逻辑一致）。PINNED模式：跳过生成（见输出位置）。
前置条件：
- 必须存在源码文件与目录结构。
幂等性保证：
- 会确定性地原地覆盖已有的
```
mantis-summary.md
```
  文件，生成更新后的汇总内容。

Instructions

操作说明

Step 0: Locator Resolution + output location (run first)

步骤0：定位器解析 + 输出位置（优先执行）

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.

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.

输出位置（必填）：

PINNED模式（snapshot_pinned为true）：本次跳过摘要生成。在PINNED模式下，CODE_ROOT为只读（模块A步骤4），消费者（规划工具、历史工具、调研工具）从代码树的源码目录读取
```
mantis-summary.md
```
——而非从状态相关的镜像目录读取。写入无人读取的镜像目录会白白浪费工作量。PINNED模式下请勿生成任何
```
mantis-summary.md
```
文件。（若未来修改后，消费者改为从镜像目录读取并通过来源标记重新映射，则可重新考虑此逻辑；目前PINNED模式下的摘要生成是无效操作。）
HALT模式（存在active_snapshot且snapshot_pinned=false）：按MODE-OFF模式执行（在每个源码目录中写入
```
mantis-summary.md
```
）。该快照并非只读（未固定不可变副本），因此写入代码树是安全的。
MODE-OFF模式（无
```
active_snapshot
```
——当前默认模式）：完全按照当前逻辑执行——在每个源码目录中写入
```
mantis-summary.md
```
。
除PINNED模式外的所有模式下，
```
mantis-summary.md
```
文件必须对所有VCS脏检查不可见，且在任何同步操作前从目标树中删除（元代理会在模块C步骤0强制执行此规则）。绝不能让摘要文件导致代码树显示为脏状态。

你的任务是编写并执行一个脚本，遍历代码仓库目录树，在每个包含源码的目录中创建

mantis-summary.md

文件。

这是一个可选的预处理阶段，旨在大幅减少策略工具（

/mantis-plan

）所需的上下文窗口大小，并为调研人员（

/mantis-researcher

）提供快速参考映射。

按以下步骤执行摘要生成阶段：

编写遍历脚本（自底向上层级遍历）： 在工作区中编写一个脚本（如Python或bash），采用自底向上（后序）遍历方式遍历代码仓库目录树。
- 脚本必须忽略非源码目录，如
```
node_modules
```
  、
```
vendor
```
  、
```
.git
```
  、构建输出及
```
tests/
```
  。
- 通过自底向上遍历，脚本确保子目录先于其父目录完成摘要生成。
- 分析目录时，脚本应向LLM传入该目录下的本地源码文件以及其直接子目录的
```
mantis-summary.md
```
  文件。请勿将子目录的原始源码文件传入父目录。
- 分析超大目录时，可能会遇到上下文窗口大小问题。请勿批量传入文件和目录摘要，而是生成单个文件的摘要或采用更高效的分块方式，避免传入过多令牌导致LLM无法处理。
生成安全摘要（Map-Reduce方式）： 脚本应读取
```
workspace/historical_learnings.jsonl
```
（若存在），检查当前目录下文件相关的过往漏洞与安全修复记录，并将其作为上下文传入。脚本应指示LLM或代理工具生成简洁的、以安全为核心的目录摘要。为确保目录树更高层级的令牌长度合理，LLM应抽象掉底层细节，聚焦于汇总后的架构。脚本使用的提示应要求生成以下内容：
- 核心组件： 主要文件和子目录有哪些，各自的功能是什么？
- API端点与导出内容： 向其他模块暴露了哪些函数或类？
- 信任边界与外部输入： 该目录是否处理不可信数据、网络请求或用户输入？
- 敏感操作： 是否存在解析器、加密函数或内存管理操作？
- 历史漏洞与修复记录： 该目录下哪些文件或组件在
```
workspace/historical_learnings.jsonl
```
  中有历史漏洞或安全相关修复记录？汇总过往修复内容、受影响组件及漏洞类型，以突出过往回归或反复出现的弱点。
摘要大小需合理，以便融入更大规模的工作任务，因此目标为数千字以内。
输出至
mantis-summary.md
：在MODE-OFF（或HALT）模式下，将
```
mantis-summary.md
```
写入对应的源码目录（若已存在则覆盖）。在PINNED模式下，请勿写入——本次跳过摘要生成（见上文输出位置说明）。绝不能写入只读快照。
执行脚本： 运行你编写的脚本，在整个代码仓库中生成所有摘要。等待脚本成功执行完成。
完成： 摘要已生成。通知用户。

完成后，请通知用户。