read-only-explorer

read-only-explorer

Use this skill for explorer, analyst, reviewer, and source-audit roles. These roles must inspect code without modifying it.

Tool availability (enforced — R27-D6). explorer (and librarian) ship without a bash tool: src/config/role-tools.ts:25-29 sets tools: ["read", "grep", "find", "ls", "glob", "ask"] + excludeTools: ["edit", "write", "bash", "web"]. The shell syntax below (rg …, find …, git status) is therefore reference syntax for the intent, not runnable in an explorer session. Map each example to the tool you actually have: rg → grep, find/shell globbing → find/glob, ls → ls, cat/sed -n → read (with offset/limit). analyst/reviewer roles keep bash (role-tools.ts:33-35, :64-68) — the restriction is per-role.

Core Contract

1. Do not edit files — no write, no edit, no delete
2. Do not write generated artifacts outside the run artifact directory
3. Prefer read-only tools: read, grep, find, ls, glob (explorer has no shell — see the note above)
4. Record exact files inspected — include path and relevant line numbers
5. Distinguish direct evidence from inference — don't guess
6. If implementation is needed, recommend — don't modify code

Tool Selection Guide

Choosing the right tool for the task reduces noise and speeds up discovery.

rg (ripgrep) — Code pattern search

Best for: Finding function definitions, imports, patterns, usages

# Find all uses of a function
rg "functionName" --type ts

# Find with context (2 lines before/after)
rg "pattern" -B2 -A2

# Case-insensitive
rg -i "error handling"

# Only match whole word
rg -w "agent"

# JSON output for machine parsing
rg "pattern" --json | head -20

# Respect .gitignore (skip node_modules)
rg "pattern" --type-add 'exclude:*.json' --type ts

find — File and directory search

Best for: Finding files by name, type, or path pattern

# Find all TypeScript files
find . -name "*.ts" -not -path "*/node_modules/*" | head -20

# Find recently modified files
find . -name "*.ts" -mtime -7 | head -20

# Find files larger than 100KB
find . -size +100k -name "*.ts"

# Find by path pattern
find . -path "*/runtime/*" -name "*.ts" | head -10