mantis-researcher

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 9702f6eef495 · 31 Oct 2026Report an issue or request a re-scan

• Publishergoogle GitHub organizationOwner of the repository this skill is read from
• Source foldergoogle/mantis/skills/mantis-researcherThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict9702f6eef495A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Audits production source code files based on the strategy in workspace/plan.json. Use when a review plan exists and you need to perform static analysis and deep-dive reviews of targeted files. Don't use for planning,…

---
name: mantis-researcher
description: >-
  Audits production source code files based on the strategy in workspace/plan.json.
  Use when a review plan exists and you need to perform static analysis and deep-dive reviews of targeted files.
  Don't use for planning, deduplicating, or writing patches.
---

# Mantis Researcher (/mantis-researcher)

## System Goal

Resilience Code Auditor. Performs rapid triage and deep-dive reviews of source
files to identify boundary checks, preconditions, missing sanitization, and
interface violations.

## Command Definition

- **Command:** `/mantis-researcher`
- **Description:** Audits production source code files based on the strategy in
  `workspace/plan.json`.
- **Arguments (optional; supplied by the orchestrator, consumed by Block A):**
  - `--snapshot_root` / `SNAPSHOT_ROOT`: absolute path to the pinned, read-only
    code snapshot for this pass. This is the CODE_ROOT that all
    snapshot-relative path fields resolve against (Block A step 1b).
  - `--snapshot_id` / `SNAPSHOT_ID`: the pass snapshot identifier. Used for the
    sentinel check (Block A step 2) and stamped verbatim into every finding's
    `discovery_commit`.
  - `--state_root`: absolute path to the `workspace/` state directory
    (`plan.json`, `.mantis_state.json`, `findings/`, `kb/`). State paths are
    STATE-RELATIVE and are NEVER prefixed with CODE_ROOT (Block A step 3).
  - `--target_root` (authoritative override, Block A step 1a) is also honored if
    supplied.
  - **All flags absent -> DEGRADED/legacy mode:** CODE_ROOT falls back to the
    current directory, `snapshot_pinned` is treated as false, and behavior
    matches today's exactly (no `discovery_commit` is written).

## Input/Output Contract

- **Reads**:
  - `workspace/plan.json` (falls back to codebase sweep if missing/empty).
  - `workspace/.mantis_state.json` (to track current loop pass).
  - referenced Markdown files in `"kb_references"` (e.g.
    `workspace/kb/entities/*.md`).
  - Target source code files.
  - `workspace/kb/structural_index/manifest.json` (to check structural index
    availability/status).
  - `workspace/helpers/query_structural_index.py` (to invoke bounded
    structural-index queries).
- **Writes**:
  - Raw finding files to `workspace/findings/<uuid>.json` (creates
    `workspace/findings/` if missing).
- **Preconditions**:
  - Target files must be accessible.
- **Idempotency Guarantee**:
  - Writes new findings as separate files with unique UUIDs. Rely on
    `mantis-dedupe` to cluster and merge duplicate findings on subsequent steps.

## Instructions

### Step 0: Locator Resolution (Snapshot-Aware Path Handling)

Run this BEFORE the numbered research steps below. It fixes the single CODE_ROOT
that every `target_files` / `code_paths` reference in this stage resolves
against, so all sub-agents audit the same pinned snapshot.

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

Skill-specific notes for the researcher:

- The researcher is a CODE-READING stage, so Block A step 0's findings-only skip
  does NOT apply here — you MUST resolve CODE_ROOT and honor the sentinel.
- `workspace/plan.json` `target_files` and finding `code_paths` are
  SNAPSHOT-RELATIVE: resolve them under CODE_ROOT (Block A step 3).
- `kb_references`, `workspace/plan.json`, `workspace/.mantis_state.json`, and
  everything under `workspace/fi

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/google/mantis
git -C mantis checkout 9702f6eef495

Works in

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source 9702f6eef495

Questions about mantis-researcher

• github.com/google/mantis/tree/main/skills/mantis-researcher — the audited source at commit 9702f6eef495 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology