/skill:code-investigate — Cross-Repo Code Investigation
Purpose: Search code for a requested pattern or behavior across one or more repositories and produce a structured, versioned Markdown report. Unlike the Explore subagent (single-scope, no report), this skill produces a durable investigation artifact with structured matches and confidence scores.
When to Use
- You need a durable, versioned investigation report — not an ephemeral search
- Scope spans multiple repositories
- Findings will be cited in a ticket, PR, or postmortem
When NOT to Use
- Single-repo, throwaway search — use the Explore subagent or Grep directly
- You already know the file and just need to read it — use Read
- You are debugging an active bug — use
/skill:triage
Soft Pre-flight Config Check
This skill has a config file for defaults, but can run without it if arguments are provided.
Check ~/.claude/code-investigate.config.md:
- If it exists, load
report_root and default_repo_roots as defaults.
- If it does NOT exist, check whether the user provided scope and output args. If yes, continue. If no:
"No default config found. Provide search scope as an argument, or run /skill:configure code-investigate to set defaults."
Arguments
<description> — what to find (exact pattern, API name, regex, or natural-language behavior like "send email" or "reads files")
--repo <path> — search a single repo (default: current repo)
--repos <path1,path2,...> — search an explicit list of repos
--folder <path> — search all repos in a directory
--output <path> — report output directory (default from config: docs/code-investigations/)
--include-code — include matching code lines in the report
--include-summary — include a short behavior summary per match
--confidence <0.50-1.00> — minimum confidence threshold (default: 0.70)
Workflow
Step 1: Clarify Scope
Determine scope mode:
- repo — one repository (default: current)
- repos — explicit list
- folder — directory containing repositories
If unclear from arguments, ask once.
If not specified and not clear from context, ask:
- "Include matching code lines in the report?"
- "Add a short summary of what the code does at each match?"
Step 2: Build Search Plan
Convert the request into a search plan:
- Exact anchors — symbols, class names, method names, string literals, config keys
- Framework cues — common APIs and idioms for the behavior
- Structure clues — filenames, folder names, namespaces, service names
- Behavioral cues — patterns that imply the behavior even without keyword matches
For multi-repo scope, dispatch parallel searches using the Agent tool with one agent per repo.
Step 3: Search
Context-aware reading strategy: With 1M token context available, calibrate read depth to repo size:
- Small repos (<200 files): read all source files directly before grepping — comprehensive reads surface semantic matches that keyword search misses.
- Medium repos (200–2000 files): full read of entry points, public surfaces, and files matching structure cues; grep for anchors elsewhere.
- Large repos (2000+ files): layered approach below; sample by signal category rather than exhaustive read.
- Pre-retrieval pruning (
jev-gate): When the jev-gate MCP server is available (see _internal/jev-gate), pass the investigation prompt and candidate file list from Grep/Glob to triage_coding_task(task_prompt, candidate_files) before reading large file sets into the cloud context window. Read keep_full files completely, extract exported signatures (ast-grep) for keep_signatures_only files, and skip drop files.
For each repo in scope, search using a layered approach:
- Grep/Glob for exact anchors
- Read files matching framework/structure cues (full read for small/medium per above)
- Scan for behavioral matches in promising files
- Rate each match with a confidence score
Match Schema
Each match is a structured object:
| Field |
Type |
Required |
Notes |
repo |
string |
yes |
Repository name |
project |
string |
yes |
Nearest project identifier (package.json name, .csproj, folder) |
file |
string |
yes |
Repo-relative file path |
lineRange |
string |
yes |
e.g., 42-58 |
matchType |
string |
yes |
literal, regex, symbol, framework, semantic |
confidence |
number |
yes |
0.50 to 1.00 |
whyMatch |
string |
yes |
Why this code satisfies the request |
codeLines |
string |
no |
Only when --include-code |
summary |
string |
no |
Only when --include-summary |
Step 4: Write Report
Write a versioned Markdown report:
Default path: <report_root>/<YYYY-MM-DD>--<HHMMSS>--<scope>--<slug>.md
Report structure:
# Code Investigation Report
- **Date:** YYYY-MM-DD HH:MM
- **Scope mode:** repo | repos | folder
- **Scope:** <human-readable scope>
- **Request:** <search request summary>
- **Repos searched:** <count>
- **Matches found:** <count>
- **Confidence threshold:** <threshold>
- **Include code lines:** yes | no
- **Include summaries:** yes | no
## Matches by Repository
### <repo-name>
#### <project-name>
| File | Lines | Type | Confidence | Why |
|---|---|---|---|---|
| path/to/file.ts | 42-58 | semantic | 0.85 | Calls sendEmail() with SMTP config |
<optional code block>
<optional summary>
## Summary
- Total matches: <N>
- High confidence (>=0.90): <N>
- Medium confidence (0.70-0.89): <N>
- Repos with matches: <list>
- Repos with no matches: <list>
Update <report_root>/index.md and <report_root>/latest.md if they exist.
Step 5: Report
"Investigation report written to <path>. Found matches across repos."
CRITICAL: Do Not Guess
- Do NOT fabricate matches. Every match must reference real code.
- Do NOT inflate confidence scores. If unsure, rate lower.
- Do NOT modify any source code. This skill is read-only.
- Do NOT skip repos in scope without reporting them as "no matches."
- Do NOT assume repo structure. Detect it.
1---2name: code-investigate-23description: Search one or more repos for a code pattern or behavior and produce a4 versioned Markdown investigation report. Supports literal, regex, and semantic (behavioral)5 search across multi-repo scope.6whenToUse: Search one or more repos for a code pattern or behavior and produce a versioned7 Markdown investigation report. Supports literal, regex, and semantic (behavioral)8 search across multi-repo scope.9arguments:10- query11metadata:12 source: https://skillmd.com/skills/garyld1962/code-investigate-213---141516# /skill:code-investigate — Cross-Repo Code Investigation1718**Purpose:** Search code for a requested pattern or behavior across one or more repositories and produce a structured, versioned Markdown report. Unlike the Explore subagent (single-scope, no report), this skill produces a durable investigation artifact with structured matches and confidence scores.1920## When to Use2122- You need a durable, versioned investigation report — not an ephemeral search23- Scope spans multiple repositories24- Findings will be cited in a ticket, PR, or postmortem2526## When NOT to Use2728- Single-repo, throwaway search — use the Explore subagent or Grep directly29- You already know the file and just need to read it — use Read30- You are debugging an active bug — use `/skill:triage`3132## Soft Pre-flight Config Check3334This skill has a config file for defaults, but can run without it if arguments are provided.3536Check `~/.claude/code-investigate.config.md`:37- If it exists, load `report_root` and `default_repo_roots` as defaults.38- If it does NOT exist, check whether the user provided scope and output args. If yes, continue. If no:39 > "No default config found. Provide search scope as an argument, or run `/skill:configure code-investigate` to set defaults."4041## Arguments4243- `<description>` — what to find (exact pattern, API name, regex, or natural-language behavior like "send email" or "reads files")44- `--repo <path>` — search a single repo (default: current repo)45- `--repos <path1,path2,...>` — search an explicit list of repos46- `--folder <path>` — search all repos in a directory47- `--output <path>` — report output directory (default from config: `docs/code-investigations/`)48- `--include-code` — include matching code lines in the report49- `--include-summary` — include a short behavior summary per match50- `--confidence <0.50-1.00>` — minimum confidence threshold (default: 0.70)5152## Workflow5354### Step 1: Clarify Scope5556Determine scope mode:57- **repo** — one repository (default: current)58- **repos** — explicit list59- **folder** — directory containing repositories6061If unclear from arguments, ask once.6263If not specified and not clear from context, ask:641. "Include matching code lines in the report?"652. "Add a short summary of what the code does at each match?"6667### Step 2: Build Search Plan6869Convert the request into a search plan:7071- **Exact anchors** — symbols, class names, method names, string literals, config keys72- **Framework cues** — common APIs and idioms for the behavior73- **Structure clues** — filenames, folder names, namespaces, service names74- **Behavioral cues** — patterns that imply the behavior even without keyword matches7576For multi-repo scope, dispatch parallel searches using the Agent tool with one agent per repo.7778### Step 3: Search7980**Context-aware reading strategy:** With 1M token context available, calibrate read depth to repo size:81- **Small repos (<200 files):** read all source files directly before grepping — comprehensive reads surface semantic matches that keyword search misses.82- **Medium repos (200–2000 files):** full read of entry points, public surfaces, and files matching structure cues; grep for anchors elsewhere.83- **Large repos (2000+ files):** layered approach below; sample by signal category rather than exhaustive read.84- **Pre-retrieval pruning (`jev-gate`):** When the `jev-gate` MCP server is available (see `_internal/jev-gate`), pass the investigation prompt and candidate file list from Grep/Glob to `triage_coding_task(task_prompt, candidate_files)` before reading large file sets into the cloud context window. Read `keep_full` files completely, extract exported signatures (`ast-grep`) for `keep_signatures_only` files, and skip `drop` files.8586For each repo in scope, search using a layered approach:871. Grep/Glob for exact anchors882. Read files matching framework/structure cues (full read for small/medium per above)893. Scan for behavioral matches in promising files904. Rate each match with a confidence score9192### Match Schema9394Each match is a structured object:9596| Field | Type | Required | Notes |97|---|---|---|---|98| `repo` | string | yes | Repository name |99| `project` | string | yes | Nearest project identifier (package.json name, .csproj, folder) |100| `file` | string | yes | Repo-relative file path |101| `lineRange` | string | yes | e.g., `42-58` |102| `matchType` | string | yes | `literal`, `regex`, `symbol`, `framework`, `semantic` |103| `confidence` | number | yes | `0.50` to `1.00` |104| `whyMatch` | string | yes | Why this code satisfies the request |105| `codeLines` | string | no | Only when `--include-code` |106| `summary` | string | no | Only when `--include-summary` |107108### Step 4: Write Report109110Write a versioned Markdown report:111112**Default path:** `<report_root>/<YYYY-MM-DD>--<HHMMSS>--<scope>--<slug>.md`113114**Report structure:**115116```markdown117# Code Investigation Report118119- **Date:** YYYY-MM-DD HH:MM120- **Scope mode:** repo | repos | folder121- **Scope:** <human-readable scope>122- **Request:** <search request summary>123- **Repos searched:** <count>124- **Matches found:** <count>125- **Confidence threshold:** <threshold>126- **Include code lines:** yes | no127- **Include summaries:** yes | no128129## Matches by Repository130131### <repo-name>132133#### <project-name>134135| File | Lines | Type | Confidence | Why |136|---|---|---|---|---|137| path/to/file.ts | 42-58 | semantic | 0.85 | Calls sendEmail() with SMTP config |138139<optional code block>140<optional summary>141142## Summary143144- Total matches: <N>145- High confidence (>=0.90): <N>146- Medium confidence (0.70-0.89): <N>147- Repos with matches: <list>148- Repos with no matches: <list>149```150151Update `<report_root>/index.md` and `<report_root>/latest.md` if they exist.152153### Step 5: Report154155> "Investigation report written to `<path>`. Found <N> matches across <M> repos."156157## CRITICAL: Do Not Guess158159- Do NOT fabricate matches. Every match must reference real code.160- Do NOT inflate confidence scores. If unsure, rate lower.161- Do NOT modify any source code. This skill is read-only.162- Do NOT skip repos in scope without reporting them as "no matches."163- Do NOT assume repo structure. Detect it.