distill: flush prior-session best-practice additions

Additive/refining entries left uncommitted in the working tree from an earlier
distill session (found during the 2026-07 sweep commit): agent-repos 5-step
plan pattern; ai-parallel-agents cheap-model scope; spec-driven spec-inversion
and caller/callee cross-reference rules.

ai-parallel-agents.md

@@ -104,8 +104,52 @@ Cross-references: [Agent Repos & Container Agent Operations](agent-repos.md) cov
 - No dedicated output folder — research artifacts get lost alongside code.
 - Never reading the research output after dispatch — a "fire and forget" audit with no human review has no value.
 
+### Cheap-Model Sub-Sessions: When to Use, When to Skip
+
+Tools that fork a cheap-model session for grunt work (`/ask-minimax`, similar MiniMax-, Qwen-, or Haiku-backed delegators) shine on a narrow band of tasks. Reach for them when **the file payload dwarfs the answer payload**.
+
+**Use for:**
+- Summarising large files (logs, dumps, generated reports >500 lines)
+- Extracting specific facts from many files or long reference docs
+- Generating big files (migrations, fixtures, large docs) whose content does not need to flow back
+- Format conversion of large files (CSV↔JSON, XML↔YAML)
+- Bulk find-and-extract where only the matches matter
+
+**Skip for:**
+- Iterative design or debugging — the parent session needs the content in context
+- Small files (<500 lines) — overhead exceeds savings
+- Tasks where you will immediately re-read the result to act on it
+- Anything requiring tools the cheap model lacks (web fetch, MCP, browser, agent dispatch)
+- Architecture or quality-sensitive output — cheap models are for grunt work, not nuanced reasoning
+- **Per-test verification loops** — the LLM round-trip cost dwarfs the test's own cost; the cheap model also stalls silently on tasks requiring sustained state across iterations. Replace with an AST script.
+
+**Delegate by reference, not content:** pass file paths, not file contents. If you read the input files yourself before invoking, you have already paid the token cost the skill exists to avoid.
+
+---
+
+## 6. Cost-Effective Models: Single-File, Single-Rule Task Scope
+
+**Principle:** Cheap/small models (MiniMax, Qwen3.x, Haiku via airouter) reliably produce output when scoped to ONE file and ONE rule per task. Multi-file or multi-rule tasks silently produce no output even when the agent's reasoning logs look correct.
+
+**Why it matters:** Cost-effective models trade context-management ability for token cost. With multi-file scope, the model loses track of which file it has already edited and produces empty output or commits without the expected files. The failure is silent — exit code 0, reasoning logs look fine, no output file. Verified in a 9-dispatch batch: single-file scope succeeded 8/8, multi-file scope failed 2/2 with no output.
+
+**How to implement:**
+- **One file per task** — split multi-file changes into separate dispatches. Each task creates or edits exactly one file.
+- **Reference the template, don't inline it** — give the agent the path to an existing similar file to read, rather than including all structure in the prompt.
+- **State the file path explicitly** — "Create `<exact/path/to/file>`" at the start of the prompt, not implied by context.
+- **Verify output before treating as done** — check the agent-repo branch (or output directory) for the expected file immediately after task success. Don't trust the exit code alone.
+
+**Sequential chain for unavoidable multi-file work:** dispatch task-1 to produce file-A, wait for success, then dispatch task-2 to produce file-B referencing task-1's output (passed via git branch artifact). This bounds the agent's scope to one artifact at a time and lets each task verify the previous one's output before continuing.
+
+**Anti-patterns:**
+- Dispatching a single cheap-model task with "create files X, Y, Z" — silent no-output is the typical result.
+- Trusting `exit code = 0` from a cheap-model dispatch — always verify the expected file landed on disk or the agent-repo branch.
+- Using a cheap model for tasks that require sustained state across many turns — the failure mode is silent stall, not error.
+
+Cross-reference: [Agent Repos](agent-repos.md) "Airouter Qwen3.6 — Scope Decomposition" has the production dispatch pattern and time-to-success bands.
+
 ---
 
 ## Summary
 
-Parallel agent orchestration multiplies throughput when agents have narrowly scoped work, disjoint file sets, and the right tool capabilities. The main thread holds responsibilities subagents cannot do: web fetches, file writes on contested paths, and final integration of returned text. For large datasets, a single background sweep with a research-document output usually beats interactive back-and-forth.
+Parallel agent orchestration multiplies throughput when agents have narrowly scoped work, disjoint file sets, and the right tool capabilities. The main thread holds responsibilities subagents cannot do: web fetches, file writes on contested paths, and final integration of returned text. For large datasets, a single background sweep with a research-document output usually beats interactive back-and-forth. Cost-effective models need tighter scope still — one file, one rule, verified output.