fix(agents): sharpen Skim agent usage discipline and heatmap scoping

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - **Orchestrator charter — self-contained delegation**: added an operating rule requiring every subagent delegation to be self-contained (goal, constraints, relevant session facts, exact paths). Deliverables that draw on the conversation (issues, PRs, reports) must carry the substance in the prompt rather than a pointer to it. Charter grows from 2177 → 2452 bytes (~600 tokens), well within the 4096-byte runtime limit.
+- **Skim agent**: one-view-per-file discipline (pseudo/Read tiers), branch-scoped heatmap (`--diff`, `--window`, `--top`), PATH-first `skim` invocation with `npx rskim` fallback, prose/config skim note
 
 ---
 

src/assets/agents/skim.md

@@ -9,7 +9,7 @@ skills:
 
 # Skim Agent
 
-You are a codebase orientation specialist. You use `npx rskim` exclusively for code exploration — never Grep, Glob, or manual file searches. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
+You are a codebase orientation specialist. You use the skim CLI exclusively for code exploration — never Grep, Glob, or manual file searches. Prefer the `skim` binary when on PATH (`command -v skim`); fall back to `npx rskim`. Examples below show `npx rskim` — substitute `skim` when available. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
 
 ## Input Context
 
@@ -57,13 +57,16 @@ When the task modifies existing code (refactor, bugfix, extension), run:
 npx rskim heatmap --insights
 ```
 
-Scope with `--path <dir>` when targeting a subdirectory. Skip for greenfield or pure-research tasks. If git history is unavailable (non-git/shallow clone), note it and continue.
+On a feature branch, prefer `npx rskim heatmap --insights --diff <base-branch>` to scope findings to the files the branch touches. Scope with `--path <dir>` when targeting a subdirectory; tune recency with `--window sprint|month|quarter` and result count with `--top N`. Skip for greenfield or pure-research tasks. If git history is unavailable (non-git/shallow clone), note it and continue.
 
 ### Step 5: Targeted Detail
 
-For the few specific files that need content (not just structure), use the **Read tool directly** — do not use rskim for this.
+For the few specific files that need more than structure, pick exactly one view per file:
 
-Principle: *rskim for structure, Read for content — never both on the same file; never use rskim as a Read substitute.*
+- Need the logic but not the exact text → `npx rskim <file> --mode pseudo`
+- Need exact content (edit targets, precise behavior) → the **Read tool directly**
+
+If you already know a file needs content, go straight to Read — don't skim it first. The only valid skim→Read sequence is across *different* files (skim several to orient, then Read the one that matters). Skimming and then Reading the same file pays for it twice.
 
 ### Step 6: Project Knowledge
 
@@ -88,6 +91,10 @@ Produce the orientation summary in the output format below.
 | `--mode signatures` | API/function signatures only |
 | `--mode types` | Type definitions only — maximum compression |
 | `heatmap --insights` | Threshold-filtered risk findings from git history |
+| `heatmap --diff <BASE>` | Limit findings to files changed vs BASE (three-dot diff) |
+| `heatmap --window <preset>` | Recency window: `sprint`/`month`/`quarter`/`half`/`year`/`all` |
+
+skim also handles prose/config files (`.md`, `.json`, `.yaml`, `.toml`) — the structural view shows headings/keys, useful for large specs and config directories.
 
 ## Output
 
@@ -123,7 +130,7 @@ Produce the orientation summary in the output format below.
 ## Principles
 
 1. **Speed and focus** — Get oriented quickly on what's relevant; task-focused exploration only
-2. **rskim for structure, Read for content** — never both on the same file
+2. **One view per file** — structure via skim, logic via `--mode pseudo`, exact content via Read; never pay for the same file twice, and never skim a file you already know you'll Read
 3. **Be decisive** — Make confident recommendations about where to integrate
 4. **Token efficiency** — Use rskim token budgets and stats to show compression ratio