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. 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/findings/ are STATE RELATIVE: read/write them under state root, NEVER under CODE ROOT. Never write, compile, or generate anything under CODE ROOT when pinned (Block A step 4). Perform a thorough memory safety, logical correctness, and robustness review of the targeted codebase. Execute the research stage as follows: 1. Load Reviewing Plan & Context: Read the active pass number from workspace/.mantis state.json and resolve the current ISO 8601 timestamp. Read the workspace/plan.json file to retrieve the target investigations. If workspace/plan.json is missing or empty, perform a general list of the directories and review any primary source files. If the investigation contains a "kb references" array, explicitly read those Markdown files (e.g., workspace/kb/entities/auth.md ) to gain compounded historical context before you begin auditing the "target files" . Also read active snapshot from workspace/.mantis state.json ( root , snapshot id , snapshot pinned ). Hold active snapshot.snapshot id in memory: it is the value you will stamp into every finding's discovery commit (see Findings Schema Format). If active snapshot is absent or snapshot pinned is false, you are in DEGRADED/legacy mode — do NOT stop (Block A step 1d); you will simply omit discovery commit . 2. Sub Agent Delegation (Wave Based Swarm Parallelization): If the CLI or agent platform supports spawning sub agents (e.g., using specialized sub agent tools or multi agent orchestrator directives): Do not execute investigations sequentially if sub agents are supported. Split the investigations in workspace/plan.json into parallel waves to maximize throughput and context efficiency. Wave 1: Lightweight Rapid Triage (Concurrency Peak): Spawn concurrent, lightweight sub agents (e.g. up to 10 20 in parallel) to sweep all files listed in workspace/plan.json . Each sub agent should only output a fast classification: {"potentially flawed": true/false, "reason": "..."} . Wave 2: Deep Security Flaw Hotspot Audits & Parallel Trajectory Search: Collect all files flagged in Wave 1. Spawn a wave of concurrent deep auditor sub agents (e.g. up to 4 8 in parallel) to focus exclusively on those identified hotspots. For particularly complex files, spawn multiple subagents targeting the same file using either different prompt constraints or a diverse set of less expensive LLMs to explore parallel attack vectors. Rely on the subsequent deduplication stage to merge any overlapping findings. Token Optimization (Distributed Writes): Instruct the Wave 2 sub agents to generate unique UUIDs and write their findings directly to individual workspace/findings/<id .json files on disk. Do not ask them to return the full JSON payload in their messages back to you, as aggregating them will blow out your context window. Ask them to only return the list of UUIDs they created. Snapshot Isolation (Wave Pinning) — MANDATORY: Pass the SAME snapshot root (CODE ROOT resolved in Step 0) and the same snapshot id value to EVERY Wave 1 and Wave 2 sub agent, and instruct each of them to obey Block A (resolve target files / code paths under that CODE ROOT, honor the sentinel). Any Wave 2 sub agent that writes a finding MUST stamp discovery commit with that snapshot id, exactly as specified in the Findings Schema Format. Sub agents MUST NOT run git pull / fetch / checkout / reset , hg pull / update , repo sync , or any command that changes the working tree or switches revisions — the snapshot is immutable for the whole pass. A sub agent that cannot see the snapshot must report that, not re sync. If sub agents or concurrency are not supported by the current environment, fall back to performing the sweeps and deep dives sequentially. Structural Index (HINT only enhancement): When a structural index is available ( workspace/kb/structural index/manifest.json exists), use it to SUPPLEMENT the wave based swarm above. The structural index decides ORDER, never MEMBERSHIP. It MUST NEVER replace the exhaustive Step 3 call site sweep. Resolution first protocol (MANDATORY before any structural query): 1. Resolve the symbol first: python3 workspace/helpers/query structural index.py resolve symbol name "<function name " [ language "<lang "] [ file "<path "] state root <state root 2. If the response has ambiguous: true , investigate ALL matched symbols — never silently pick one. Narrow with file / language if possible, or schedule investigations for every matched symbol. 3. Use the resolved symbol id for bounded queries: python3 workspace/helpers/query structural index.py find callers symbol id "<id " limit 100 offset 0 state root <state root Coverage aware interpretation: Check coverage.partition status in every structural index response: complete + precision == semantic + empty results = "no indexed callers" (authoritative for indexed code — still run grep per the HINT only rule). complete + precision != semantic + empty results = "no indexed callers" — NOT authoritative. MUST run exhaustive grep. partial / empty / failed + empty results = "not fully indexed" — MUST run exhaustive grep. Use the precision and backend fields on every result to weight trust ( semantic typecheck ast symbol only heuristic deferred coverage only ). Wave 1 (Rapid Triage): Use find callers() to SUPPLEMENT grep as a ranking HINT — ORDER, never MEMBERSHIP. Structural index results prioritize which files to flag as potentially flawed ; they MUST NEVER replace the exhaustive Step 3 call site sweep. Audit the union of grep results and structural index results. Wave 2 (Deep Audit): Use get function boundary(file, line) to start with the enclosing function, then expand to callers/callees/file as needed for deep dive context. Graceful degradation: If the structural index is absent (no manifest.json ), empty, or the query helper is missing, fall back to grep based discovery (today's behavior). The structural index is a coverage HINT only. 3. Exhaustive Interface and Call Site Reviewing: If a target source file defines public or API functions (such as numeric parsers, decoders, encoders, or converters) that document explicit size constraints or safety requirements (e.g., expecting callers to allocate buffers of a certain size): Run a repo wide grep for the function name to build the exhaustive set of candidate call sites — this is the mandatory floor. Then use the structural index query helper ( resolve symbol then find callers ) to RANK and prioritize which call sites to audit first (the index distinguishes actual calls from comments/strings/variable names). Audit the union of both result sets — the structural index may miss macro based calls, function pointers, and dynamic dispatch, so grep remains the floor. Search the codebase to find and review all call sites of these functions across the entire repository to ensure the safety contracts are respected globally. Read the calling files and verify if every call site strictly adheres to input constraints, properly manages bounds, and checks sizes. Flag any discrepancies as contract alignment bugs or missing checks. 4. Unconstrained / Exploratory Investigations: If the investigation plan in workspace/plan.json contains instructions or a question explicitly asking for an unconstrained sweep, adversarial audit, or random exploration: Ignore existing assumptions of safety and documented trust boundaries in workspace/kb/THREAT MODEL.md . Treat all inputs and boundaries as untrusted and potentially malformed. Analyze implementation from scratch with full freedom and autonomy. If it is a random exploration/digging task with minimal instructions, focus on mapping the behavior of the target files, identifying key entry points, and looking for unexpected side effects or boundary cases without being constrained by a specific threat model. 5. Compile and Write Findings: Instead of a single monolithic file, create a workspace/findings/ directory if it does not exist. For each potential finding, generate a unique UUID and write a valid JSON object into an individual file named workspace/findings/<id .json . This keeps findings isolated and prevents token limit issues during subsequent analysis. Do not include any text before or after the JSON in the files

mantis-researcher