opencode-thrum-pro 0.1.0

package/assets/skills/coordinator-running-review-cycles/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: coordinator-running-review-cycles
+description: "Use when an implementer reports DONE, when consolidating review findings, when handling implementer pushback on a finding, or when arriving at a review gate. Loads coordinator-specific discipline for running review cycles cleanly."
+---
+
+# Coordinator: Running Review Cycles
+
+## Run code-quality + spec-compliance review in parallel
+
+**Why:** Reviewers serve different purposes. `feature-dev:code-reviewer` catches
+security, error-handling, idiom, and dead-code issues. `verify-against-plan`
+catches missing scope, unmet acceptance criteria, and silent deviations from the
+plan. Running them sequentially doubles review-cycle latency for no reason —
+they're independent reads of the same diff.
+
+**How to apply:** When an implementer reports DONE on a branch, dispatch both
+reviewers as parallel sub-agents in the same message. Pass each a clear scope
+("review the diff at <BASE>...<HEAD> for <criteria>").
+
+> **Model tiers:** pass an explicit `model:` on every dispatch — `sonnet`
+> (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
+> operator-ask or a skill step that names it. See the
+> `choosing-subagent-models` skill for the full policy.
+
+## Wait for both reviewers before sending anything to the implementer
+
+**Why:** Sending findings from reviewer A while reviewer B is still running
+causes the implementer to fix batch 1 and miss batch 2 entirely, extending the
+review cycle by a full extra round.
+
+**How to apply:** Block until both review sub-agents return their full output.
+Do not send partial findings, even if the user is asking for an update. If one
+reviewer takes substantially longer, the right move is a status update to the
+implementer ("review running, hold"), not a partial batch.
+
+## Consolidate findings into ONE numbered list across all severities
+
+**Why:** A single numbered list with mixed severities lets the implementer work
+top-to-bottom without context-switching across "minor batch" and "critical
+batch" calls. Severity labels live next to each finding; ordering is by
+severity, then by file path. Two separate lists invite the implementer to skip
+one.
+
+**How to apply:** Merge both reviewers' output. Number sequentially from
+
+1. Each item: `<severity> · <file:line> · <one-line summary>` followed by the
+   detail and suggested fix. Keep the numbering stable across review rounds —
+   when re-reviewing fixes, refer to "finding #4" and the implementer can locate
+   it instantly.
+
+## Verify reviewer claims against actual code before forwarding
+
+**Why:** Reviewers reading a large diff sometimes cite wrong line numbers or
+describe behavior that doesn't match the current code. Forwarding a misread
+finding causes the implementer to waste time investigating a non-issue and
+erodes trust in the review process.
+
+**How to apply:** For any finding citing a specific file and line, read that
+file at that range before forwarding. For API-shape claims, grep for the symbol
+and read the signature. For behavior claims, trace the call path. Drop or
+correct findings that don't survive verification — silently forwarding wrong
+findings poisons the cycle.
+
+## Treat implementer pushback as a signal to verify, not dismiss
+
+**Why:** When an implementer disputes a finding ("you said X, but the actual
+shape is Y — here's the trace"), that is the correct behavior, not
+insubordination. The coordinator may have stated expectations that drift from
+runtime reality. Treating pushback as a challenge breaks the feedback loop and
+trains implementers to swallow corrections.
+
+**How to apply:** When an implementer pushes back: read the cited file at the
+cited lines, run the cited command, or `bd show <id>` for beads state. If
+they're right, acknowledge the correction explicitly and update session context.
+If the finding was based on a misread, drop it from the batch and tell them so.
+If you're still right after verification, restate with the new evidence — but
+never just reassert without verification.
+
+## Re-review after fixes land — repeat until both pass
+
+**Why:** A single review pass rarely catches everything, and fix commits can
+introduce new regressions. Skipping the re-review accepts an unknown risk that
+scales with diff size.
+
+**How to apply:** When the implementer reports fixes complete, re-dispatch both
+reviewers (in parallel) on the new diff. Most of the time, round 2 returns clean
+or with one minor finding. If round 3 still has Critical or Important findings,
+escalate to the user — repeated failure to land fixes signals a deeper scope or
+design issue, not just sloppy review.
+
+## Use structural evidence when a green test is blocked upstream
+
+**Why:** A test that cannot run (blocked upstream build, unrelated flake, CI
+environment issue) cannot validate behavior. Saying "no errors seen" is weaker
+than enumerating what a regression would produce and showing none of those
+signatures occurred.
+
+**How to apply:** When a green-test check is blocked, prove absence of
+regression by: (1) listing specific failure modes a regression would produce
+(error types, wrong status codes, missing state changes); (2) showing none of
+those modes occurred (wire-level status codes, specific log assertions, expected
+state present); (3) documenting the upstream blocker in a tracking issue so the
+green-test check can be re-run when it clears.
+
+## Run the philosophy merge gate before the actual merge
+
+**Why:** Dual review (code-quality + spec-compliance) is general-purpose and
+does not carry the project-specific structural lenses that
+`.thrum/philosophy.md` requires — folding them in as dual-review findings would
+dilute both the general review and the specialized gate.
+
+**How to apply:** After dual review passes clean, before running `git merge`,
+invoke `coordinator-philosophy-merge-gate` for any branch that introduces or
+materially changes a service, handler, background job, adapter, or RPC boundary.
+Skip it for small/mechanical fixes. The gate walks all anti-patterns and red
+flags in `.thrum/philosophy.md`, with single-responsibility (SRP) as one lens
+(Lens 10) among the full set — not a separate pass.
+
+## Prose-pre vs code-post: what this review cycle covers
+
+**Why:** Once the planning-skill review loop ships, there are two distinct
+review surfaces and conflating them double-reviews one artifact. The planning
+loop reviews PROSE artifacts (brainstorm, plan, impl-prompt) BEFORE
+implementation; the review cycle in THIS skill reviews the implementer's CODE
+AFTER they report DONE. They target different artifacts and both are needed.
+
+**How to apply:**
+
+- The planning loop's prompt gate already reviewed the impl-prompt; its
+  `THRUM-REVIEW: stage=prompt verdict=Ready:Yes` stamp satisfies the
+  pre-dispatch review (see `coordinator-dispatching-work`). Do not re-review the
+  prompt here.
+- This skill's dual review (code-quality + spec-compliance, in parallel) runs on
+  the CODE the implementer produced — the diff on their branch. That always runs
+  at DONE regardless of any planning-loop stamps, because the code is a new
+  artifact the planning loop never saw.
+- Net: the prompt is reviewed once (in the planning loop, pre-dispatch); the
+  code is reviewed once (here, post-DONE). No artifact is reviewed twice.
+
+## See also
+
+- `coordinator-branch-split-on-block` — when a Pass-3 gate or this skill's
+  dual review BLOCKS on one concern of a branch that bundles multiple
+  independent concerns, while the other concern(s) are clean.
+
+## Project-specific rules (already loaded)
+
+Read the shared partial at the absolute path:
+`claude-plugin/commands/_project-rules-protocol.md`
+
+If you accumulate a new rule mid-session (the user corrects you), capture it via
+the `coordinator-maintaining-memory` skill — it references the
+`memory-write-discipline` common for the canonical `thrum memory create` shape.

package/assets/skills/coordinator-single-responsibility-merge-gate/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: coordinator-single-responsibility-merge-gate
+description: "DEPRECATED — superseded by `coordinator-philosophy-merge-gate`. Invoke that skill instead. (This stub is retained for backward discoverability; it redirects immediately.)"
+---
+
+# Coordinator: Single-Responsibility Merge Gate (Deprecated)
+
+This skill has been superseded by `coordinator-philosophy-merge-gate`, which
+subsumes single-responsibility as one lens (Lens 10, with sub-probes
+10a/10b/10d) among the full `.thrum/philosophy.md` anti-pattern set.
+
+Invoke `coordinator-philosophy-merge-gate` instead. All content from this skill
+— the naming test (10b), the cost gate (10d), and the structural backstop (10a)
+— lives in that skill's Lens 10 section.

package/assets/skills/diagnosing-fleet-and-daemon/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: diagnosing-fleet-and-daemon
+description: "Use when the daemon or fleet looks broken and you need to find something FAST — daemon down, daemon not running, connection refused, dial unix, thrum.sock, socket refused, daemon crashed, daemon wedged, daemon hangs, fleet dark, fleet outage, agents unreachable, can't send, send failed, messages not delivering, no agents responding, daemon status wrong, daemon won't start, restart the daemon, is the daemon alive, where is the daemon log, which log file, searching logs, hooklog query, command log, jq returned nothing, empty log search, agent looks dead, agent stale, last_seen stale, is this agent alive, schema mismatch, cannot downgrade, migration on restart, SIGBUS, WAL poison, 522, database locked. Also use BEFORE restarting any daemon — the pre-restart migration check lives here."
+---
+
+# Diagnosing the Fleet and the Daemon
+
+**This is a LOOKUP TABLE, not a procedure.** You are here because something is
+broken and you need an answer in one command. Read the row you need and go.
+
+**If you are about to restart a daemon, read § Pre-restart check FIRST.** It is
+the only step here that can cause harm rather than merely waste time.
+
+---
+
+## § Canonical paths — get these wrong and you will report a false zero
+
+| What | Where | NOT |
+|---|---|---|
+| **Daemon log** | `.thrum/var/log/daemon.log` | ❌ `.thrum/var/daemon.log` |
+| Hook log | `.thrum/var/log/hooklog.jsonl` | |
+| Command log | `.thrum/var/log/command.jsonl` | |
+| Monitor log | `.thrum/var/log/monitor_log.jsonl` | |
+| Pane-inject log | `.thrum/var/log/inject.jsonl` | |
+| Database | `.thrum/var/messages.db` | |
+| Socket | `.thrum/var/thrum.sock` | |
+
+✅ **`daemon.log` now lives in the `log/` subdirectory, like every other log.**
+This was not always true — an older layout kept it at `.thrum/var/daemon.log`
+directly. **A missing-file error is not a finding — it is a wrong path until
+you have proven the file's absence.** If you are on an old checkout or an
+unmigrated install, check both locations before concluding the file doesn't
+exist.
+
+Worktrees redirect `.thrum/` to the main repo via `.thrum/redirect` — read that
+file to find the real path before concluding anything is missing.
+
+---
+
+## § Searching logs — use the primitive, never raw jq
+
+```bash
+thrum log search <logname> <query> [-i] [-n N]
+# logname: command | monitor_log | hooklog | ...
+thrum log search hooklog "thrum daemon start" -n 5
+```
+
+Brute-force line scan of **today's file only**. Older history is in `.gz`
+rotations under `.thrum/var/log/` — unzip and search those directly.
+
+🔴 **DO NOT hand-roll jq against the JSONL.** In `hooklog.jsonl`, `tool_input` is
+a **double-encoded JSON string**, not an object. Every one of these returns a
+clean, well-formed, WRONG empty:
+
+```bash
+jq '.tool_input.command'                       # empty — tool_input is a string
+jq '.raw_payload | .tool_input.command'        # empty — raw_payload is null
+jq 'select(.tool_name=="Bash") | .tool_input.command'  # empty — same
+```
+
+The decode that works is `.tool_input | fromjson | .command` — but prefer
+`thrum log search`, which needs no knowledge of the encoding and also matches
+record shapes a `tool_name=="Bash"` filter silently excludes (`PreToolUse` /
+`PostToolUse`).
+
+**Whatever you search: if you get zero, run a control** (see § Controls).
+
+---
+
+## § Is the daemon actually down?
+
+Ask in this order. **Do not stop at the first answer.**
+
+```bash
+thrum daemon status                    # may be WRONG during boot — see below
+pgrep -fl "thrum daemon run"           # process table
+thrum team | head -3                   # BY EFFECT — the real test
+```
+
+🔴 **`thrum daemon status` reports "not running" during background boot stages.**
+Boot takes roughly **25 seconds**. Checking at 3s and 15s and concluding
+"the status command is lying" is wrong twice over — it is accurate about a
+daemon that is not yet ready. **Wait, then re-ask.** Reach for
+instrument-failure only after the process table and a by-effect test disagree
+with it *at the same moment*.
+
+**By-effect beats status.** A successful `thrum team` / `thrum inbox` proves
+service; a status line proves only what status believes.
+
+---
+
+## § Pre-restart check — THE ONE THAT CAN CAUSE HARM
+
+**A restart can be a MIGRATING restart. Establish that before you type it.**
+
+```bash
+# What the DB is at now:
+sqlite3 "file:$PWD/.thrum/var/messages.db?mode=ro" \
+  "SELECT version FROM schema_version ORDER BY version DESC LIMIT 1;"
+# What binary is installed:
+thrum --version
+```
+
+**Have you CHANGED the binary since the daemon last ran?**
+
+- **NO (same binary, e.g. it crashed or was stopped)** → **restart is
+  non-migrating. Safe.** The inference: a daemon migrates on start, so if the
+  installed binary had wanted a higher schema it would already have taken it.
+  A daemon that ran at binary X with the DB at version N proves X wants N.
+- **YES (you upgraded, or ran an install)** → **the restart MAY MIGRATE,
+  one-way.** Take a backup first and treat it as its own decision.
+
+🔴 **A migrating restart can trigger a known crash class** — the migration
+rewrites the SQLite `-shm` sidecar, and the same process's next reader can fault
+on the now-stale shared mapping (SIGBUS, or a `SQLITE_IOERR_522` poison storm).
+Before a migrating restart: **take a backup, do it deliberately, and do not let
+it ride along on a decision about something else.**
+
+**Migration size is NOT a waiver.** A migration consisting of one `ADD COLUMN`
+plus one `UPDATE` has been observed to trigger this. Do not reason "this upgrade
+is small, so it is safe."
+
+> *Dev-fleet note (ignore if you are running a release build): the fix is a
+> boot-seam pool recycle.*
+
+⚠️ Read the DB with `mode=ro`. **Never `immutable=1`** — it reads the stale base
+file past a live `-wal` and answers confidently wrong.
+
+---
+
+## § Did it crash, or was it stopped?
+
+```bash
+grep -icE "SIGBUS|panic:|fatal error|walIndexRecover" .thrum/var/log/daemon.log
+tail -40 .thrum/var/log/daemon.log
+```
+
+- **Hits** → a crash. Capture the trace before restarting.
+- **Zero, and the log simply stops** → it was *stopped*, not crashed. Look for
+  who stopped it (§ Who did that) rather than hunting a nonexistent crash.
+
+**"No crash evidence" and "I looked in the wrong place" are indistinguishable
+without a control.** Confirm the file exists and is non-empty first.
+
+---
+
+## § Who did that?
+
+```bash
+thrum log search hooklog "daemon stop" -n 10
+thrum log search hooklog "daemon restart" -n 10
+thrum log search hooklog "<the command you're hunting>" -n 10
+```
+
+Read `cwd` on each hit — it identifies the worktree, and therefore the agent.
+**Beware two traps:**
+
+1. **Message bodies match too.** The hooklog stores full `thrum send` payloads,
+   so prose *about* a command matches a search *for* that command. Check whether
+   the hit is a command or someone talking about one.
+2. **`thrum daemon start` spawns `thrum daemon run --repo <path>`.** Seeing that
+   argv in the process table does **not** mean someone invoked it raw.
+
+---
+
+## § Is this AGENT alive? (different question from the daemon)
+
+| Signal | Legitimately supports | NEVER supports |
+|---|---|---|
+| Live tmux pane / ppid chain | **liveness** | |
+| `pid` + `start_time` | age, staleness | ❌ liveness verdict — wrong-DEAD on in-process restart |
+| `last_seen` | age of last **RPC contact** | ❌ liveness — it advances only when the agent calls the daemon |
+| DB row / tombstone / state file | nothing | ❌ liveness — the DB is often the thing that is wrong |
+
+🔴 **`last_seen` is an RPC-activity proxy.** An agent in a long tool run,
+thinking, or sitting at a permission prompt looks identically "stale" to a
+dead one.
+
+**Definitive-dead is by DIRECT OBSERVATION only.** Peek the pane.
+
+---
+
+## § Controls — the discipline that makes all of the above trustworthy
+
+**Every zero gets a control before you report it.** A control is a second
+instrument, aimed at something you KNOW is present, run the same way.
+
+If a must-exist control ALSO returns zero, **your instrument is broken, not your
+hypothesis confirmed.**
+
+---
+
+## § Known-noisy log lines — recognise, don't chase
+
+| Line | Meaning |
+|---|---|
+| `sync.apply: M1 relay loop detected … dropped` | Working as designed — loop suppression. |
+| `storagegw: gossip: peer … not connected` | Peer offline. Routine. |
+| `storagegw: gossip: peer call failed … caller-peer lacks required capability` | **NOT routine** — a live capability gap. Worth a bead if sustained. |
+| `dead_agent_sweeper: marked dead agent offline` | Routine sweeper work. |
+
+---
+
+## § Filing a bug report
+
+When the answer is "this is a defect in thrum, not in my setup", a report with
+the right artifacts is worth many times one without. **Collect these before you
+write the report** — several are lost or overwritten on the next restart.
+
+```bash
+thrum --version                                  # binary build
+thrum daemon status                              # or the exact failure text
+sqlite3 "file:$PWD/.thrum/var/messages.db?mode=ro" \
+  "SELECT version FROM schema_version ORDER BY version DESC LIMIT 1;"
+tail -200 .thrum/var/log/daemon.log
+grep -icE "SIGBUS|panic:|fatal error" .thrum/var/log/daemon.log
+uname -a                                         # OS + arch
+```
+
+A good report states, in this order:
+
+1. **What you expected and what happened** — the observable symptom, not your
+   theory of it.
+2. **Whether it reproduces**, and the smallest sequence that does it.
+3. **What changed just before** — an upgrade, an install, a restart, a config
+   edit, a migration. Most fleet faults are downstream of a change.
+4. **Which of your conclusions are MEASURED vs INFERRED.** A report that marks
+   its own guesses is far more useful than one that presents them as findings.
+5. The artifacts above.
+
+⚠️ **Redact before sending.** `daemon.log` and the JSONL logs can contain message
+bodies, file paths, hostnames, agent names, and anything an agent pasted —
+including secrets. Skim what you are attaching. If you cannot skim it all, send
+the version/status/schema lines and the specific error, and offer the full log
+separately.
+
+**Do not send the database.** It contains your full message history. If a
+maintainer needs schema state, the `schema_version` query above is what they
+want.
+
+---
+
+## § Contributing back
+
+**This skill is shared diagnostic memory. When you find a faster or more correct
+way — or get burned by a path, an encoding, or a command that lies — EDIT THIS
+FILE.** A lookup you had to rediscover is a defect in this page.
+
+Rules for edits: add the *command that works*, not a description of the problem;
+name the wrong path or wrong query explicitly, so the next reader recognises
+their own mistake rather than just reading the right answer; and if a claim is
+about runtime behaviour, say how it was measured.
+
+> *Dev-fleet only: after editing, run `scripts/sync-skills.sh` so every runtime
+> plugin picks it up.*

package/assets/skills/efficient-multi-agent-research/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: efficient-multi-agent-research
+description: "Use when investigating, auditing, or reviewing more than 6 items across a codebase - function call sites, pattern usage, file reviews, or any research task with partitionable items that would pollute the main agent's context if read directly"
+---
+
+# Efficient Multi-Agent Research
+
+## Overview
+
+When investigating N items (N > 6), reading everything into the main agent's
+context pollutes it and degrades decision-making. Instead, partition the work
+across parallel sub-agents that write findings to disk, then consolidate into a
+single report.
+
+**Core principle:** The coordinator decides, sub-agents investigate. Keep
+investigation results out of the main context until consolidated.
+
+**REQUIRED BACKGROUND:** Read superpowers:dispatching-parallel-agents before
+using this skill. That skill
+covers general parallel dispatch. This skill extends it with a specific research
+workflow: partition, investigate to disk, consolidate, then decide.
+
+## When to Use
+
+**Use when:**
+
+- Investigating many call sites of a function (N > 6)
+- Auditing usage of a pattern across a codebase
+- Reviewing multiple files for a common issue
+- Any research task with partitionable items
+
+**Don't use when:**
+
+- Simple searches (just use Grep/Glob)
+- Tasks with 6 or fewer items (single agent is fine)
+- Deeply interdependent items that can't be partitioned cleanly
+
+## Core Pattern
+
+### Partition > Parallel Investigate > Consolidate > Decide
+
+1. **Create output directory:** `mkdir -p dev-docs/<topic>/` — if re-running,
+   archive previous `findings_*.md` to a subdirectory (e.g., `run-01/`) before
+   starting so the consolidation glob only picks up current results.
+
+2. **Launch investigation agents** — all in one message, all
+   `run_in_background=true`:
+
+   ```text
+   Agent(run_in_background=true,
+     prompt="Investigate items A-D. Write to dev-docs/<topic>/findings_1.md
+     using table schema: [columns]. Flag uncertainties.")
+
+   Agent(run_in_background=true,
+     prompt="Investigate items E-H. Write to dev-docs/<topic>/findings_2.md ...")
+   ```
+
+   Specify exact table columns and consistent formatting in every prompt.
+
+   **Every prompt MUST scope the read-only restriction around its own output
+   file, in the same breath:** `READ-ONLY EVERYWHERE EXCEPT YOUR OUTPUT FILE —
+   do not modify source, tests, config, git state, or the issue tracker; you
+   MUST write exactly dev-docs/<topic>/findings_N.md, and that write is
+   expected and authorized.` Omitting the exception is the most common cause of
+   a fan-out that returns nothing — see Common Mistakes.
+
+3. **Wait** for all background agents to complete.
+
+4. **Launch consolidation agent** — always request these four elements:
+
+   ```text
+   Agent(prompt="Read all dev-docs/<topic>/findings_*.md.
+     Create consolidated_report.md with:
+     1. Unified table merging all agent tables
+     2. Cross-cutting patterns across findings
+     3. Summary statistics (e.g., '12/17 need fixes')
+     4. Prioritized recommendations")
+   ```
+
+5. **Review only `consolidated_report.md`** — never read individual findings
+   files into the main context.
+
+## Quick Reference
+
+| Aspect        | Guidance                                                  |
+| ------------- | --------------------------------------------------------- |
+| Group size    | 4-5 items per agent                                       |
+| Agent count   | Typically 3-5                                             |
+| Agent mode    | Always `run_in_background=true`                           |
+| Output        | `dev-docs/<topic>/findings_N.md` per agent                |
+| Consolidation | Always a dedicated agent writing `consolidated_report.md` |
+
+## Model tiers for this skill
+
+See the `choosing-subagent-models` skill for the full policy. Applied to this
+skill's fan-out:
+
+- **Level 1 — researchers / gatherers:** scope each one DOWN to a narrow slice
+  so you can run MANY in parallel. Use `model: "sonnet"` (low effort) —
+  bounded gather-and-report. Smaller scope = cheaper, concurrent (faster),
+  tighter per-agent context.
+- **Level 2 / Level 3 — summarizers / synthesizers:** use `model: "sonnet"` —
+  aggregating and reconciling Level-1 outputs is judgment work.
+
+Prefer many narrow sonnet-low gatherers over one broad subagent. This is the cheap,
+fast default — equivalent parallelism at a fraction of the token cost.
+
+## Common Mistakes
+
+**Skipping consolidation** - Reading 4 separate findings files into main context
+defeats the entire purpose. Always launch a consolidation agent.
+
+**Groups too large** - More than 5 items per agent gives diminishing returns.
+Partition further.
+
+**Using foreground agents** - Blocks the main agent and loses parallelism.
+Always use `run_in_background=true`.
+
+**Reading intermediate files** - The main agent should only read the
+consolidated report, never individual findings files.
+
+**Not specifying output format** - Agents produce inconsistent formats that are
+hard to consolidate. Specify table columns in every prompt.
+
+**Not specifying output file paths** - Agents may write to the working directory
+or not at all. Always include the exact output path in every prompt.
+
+**Have sub-agents write their findings file with a Bash heredoc, not the Write
+tool.** The Write tool refuses subagent report files ("Subagents should return
+findings as text, not write report files") regardless of how the brief is worded.
+The filesystem is writable; the tool is what refuses.
+
+**Put this in every prompt:**
+
+```text
+READ-ONLY EVERYWHERE EXCEPT YOUR OUTPUT FILE.
+Do not modify source, tests, config, git state, or the issue tracker.
+You MUST write your findings to exactly: dev-docs/<topic>/findings_N.md
+Write it with a Bash heredoc (cat > <path> <<'EOF' ... EOF), NOT the Write tool —
+Write refuses report files. That single write is expected and authorized.
+```
+
+If an agent still returns text instead of a file, persist it yourself verbatim
+and mark the provenance in the file — do not paraphrase.
+
+Put the exception in the SAME breath as the restriction, not in a later
+paragraph. An agent that reads "read-only" first and the write instruction
+forty lines later has already formed its posture.
+
+## Example: Auditing 17 Call Sites
+
+**Task:** Investigate 17 call sites of `resolveLocalAgentID()`
+
+**Partition:** 4 agents (4-5 call sites each, grouped by source file)
+
+**Table schema specified in every prompt:**
+
+| Line | Command | How ID Is Used | Behavior for 0/1/multiple | Needs Fix? |
+| ---- | ------- | -------------- | ------------------------- | ---------- |
+
+**Result:** Main context stayed clean. Consolidation agent identified
+cross-cutting pattern: "8/17 calls use identity for message filtering." Final
+report provided prioritized recommendations.
+
+## Variations
+
+| Variant       | When                                   | How                                                                       |
+| ------------- | -------------------------------------- | ------------------------------------------------------------------------- |
+| **Quick**     | Items are independent, output is small | Lightweight consolidation: brief merged summary instead of full synthesis |
+| **Deep**      | Very large N (50+)                     | Multi-level: 8 agents > 2 meta-agents > 1 final report                    |
+| **Iterative** | Need to refine criteria                | Run first pass, update prompts based on patterns, re-run                  |
+
+## See Also
+
+- `adversarial-critique` — decision-shaped sister pattern. Use this skill when
+  investigating _what's there_ across N>6 items; use `adversarial-critique` when
+  deciding _which option wins_ among 2-3 design forks.