hm-l3-detective

Files (15)

• SKILL.md
• .gitkeep · evals/
• evals.json · evals/
• .gitkeep · metrics/
• rich-gate-scorecard.md · metrics/
• document-pipeline.md · references/
• reading-modes.md · references/
• surgical-edits.md · references/
• swarm-recovery.md · references/
• tech-registry.md · references/
• token-budget.md · references/
• .gitkeep · scripts/
• validate-rich-package.sh · scripts/
• .gitkeep · templates/
• assumption-verification.md · templates/

SKILL.md (first lines)

## Overview

Investigate codebases using three reading modes: SCAN for targeted extraction, READ for standard review, and DEEP for interface analysis. Use when navigating large codebases, finding definitions, recovering session context, or estimating token budgets. Produces structured codebase findings with surgical edit guidance.

## Quick Jump

| Investigation Need | Section | Jump |
|--------------------|---------|------|
| "How do I read this?" | Reading Modes | [Three Reading Modes](#three-reading-modes) |
| "How much context will this cost?" | Token Budget | [references/token-budget.md](references/token-budget.md) |
| "I lost context — recover" | Swarm Recovery | [references/swarm-recovery.md](references/swarm-recovery.md) |
| "What tech stack is this?" | Tech Registry | [references/tech-registry.md](references/tech-registry.md) |
| "How do I edit safely?" | Surgical Edits | [references/surgical-edits.md](references/surgical-edits.md) |
| "Where do notes go?" | Document Pipeline | [references/document-pipeline.md](references/document-pipeline.md) |
| "Is this design assumption true?" | Assumption Verification | [templates/assumption-verification.md](templates/assumption-verification.md) |

## Three Reading Modes

Every file read costs tokens. Choose the cheapest mode that answers your question.

| Mode | Token Cost | When | Tools |
|------|-----------|------|-------|
| **SKIM** | ~5% | Orientation: "what is this?" | glob, ls, frontmatter-only, grep -c |
| **SCAN** | ~15% | Targeted: "find X" | grep -n, offset reads ±20 lines, TOC navigation |
| **SCAN (Tech Stack)** | ~10% | Stack detection: "what's this built with?" | grep indicator files, read 5-10 config files |
| **DEEP** | 100% | Understanding: "need every line" | Read full file, repomix pack + grep |

**Escalation rule**: START → SKIM → (if insufficient) SCAN or SCAN (Tech Stack) → (if still need context) DEEP. Never skip to DEEP.

### Assumption Verification Mode

Use this mode when asked to validate a design assumption, locate an existing pattern, prove whether behavior exists, or recover truth from a large codebase.

1. Write the assumption as a falsifiable claim.
2. Search for at least two independent evidence paths: definitions, call sites, tests, docs, config, runtime state, or git history.
3. Classify the result using `templates/assumption-verification.md`: confirmed, discrepancy, addition, missing, or blocked.
4. If nothing is found, report the search paths and exact queries; do not silently treat absence as proof.
5. End with an answer-first finding and file:line evidence.

**Not-found rule:** A definitive "not found" requires at least two search strategies and a documented scope boundary.

### Mode Selection Decision Tree

```
What do you need?
|
+-- "What files exist?" or "What is this project?"
|   -> SKIM: glob patterns, ls directory, grep -c for match counts
|
+-- "Where is function X defined?" or "What imports Y?"
|   -> SCAN: grep -n "pattern" file → get line numbers → offset read ±20
|
+-- "What tech stack is this?" or "What framework is this built with?"
|   -> SCAN (Tech Stack): grep for package.json/go.mod/Cargo.toml → read 5-10 config files
|
+-- "How does this algorithm work?" or "I need to understand every branch"
|   -> DEEP: Read full file (only after SKIM + SCAN confirm it's the right file)
```

### Case Study: Finding a Bug in a 600-Line File

**Wrong**: Read the entire 600-line file. Cost: ~600 lines of context.

**Right**:
1. SKIM: `grep -c "error" file.ts` → 12 matches. File is relevant.
2. SCAN: `grep -n "error" file.ts` → lines 45, 120, 234, 310, 445, 501, 520, 533, 540, 555, 567, 580
3. SCAN: Read offset=40 limit=30 (lines 40-70), offset=115 limit=30 (lines 115-145), etc.
4. DEEP: Only if the bug spans multiple sections you've already identified.

**Cost**: ~200 lines vs 600 lines. 67% savings.

## Token-Efficient Retrieval Patterns

These patterns apply across all reading modes. Master them before any investigation.

| Pattern | How | Savings |
|---------|-----|---------|
| **Offset Hop-Reading** | Read offset=N limit=30 instead of reading N lines to get to line N | 90%+ vs full read |
| **Grep-Before-Read** | grep -n → get line numbers → offset read only those sections | 80%+ vs blind read |
| **Frontmatter-Only** | For planning docs, read only between --- markers | 95%+ vs full doc |
| **TOC-First** | grep ## headings first, then targeted reads | 70%+ vs full read |
| **Repomix Compress** | Always use compress: true (70% token reduction) | 70% vs uncompressed |

### Worked Example: Finding Where a Function Is Called

**Goal**: Find all callers of `processTask` in a 47-file codebase.

```
Step 1 (SKIM): grep -rn "processTask" src/ --include="*.ts" | wc -l → 23 matches
Step 2 (SKIM): grep -rn "processTask" src/ --include="*.ts" | cut -d: -f1 | sort -u → 8 files
Step 3 (SCAN): For each of 8 files, grep -n "processTask" → get line numbers
Step 4 (SCAN): Read ±20 lines around each call site (8 files × ~2 calls × 40 lines = 640 lines)
Step 5 (DEEP): Only if a call site's context is unclear after SCAN
```

**Cost**: ~700 lines total vs reading all 47 files (~14,000 lines). **95% savings**.

---

## Hierarchical Tech Registry

The `.tech-registry.json` file is your persistent memory across sessions. Read it FIRST before any investigation.

### What It Contains

- **Stack**: Language, runtime, framework, test tool, build tool
- **Modules**: Every source file with its role (leaf/core/entry), LOC, and dependencies
- **Concerns**: Active issues and resolved problems

### Read-First Protocol

```
1. Read .tech-registry.json
2. If exists → use stack for conventions, modules for dependency graph
3. If missing → run discovery (see references/tech-registry.md)
4. If stale → spot-check 3 files, update if mismatched
```

### Update Protocol

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin