---
name: docs-refresh-scout-summaries
description: "Refresh a stale documentation cluster without delegating the writing: scout subagents produce per-line verdict tables (holder verified by comma-insensitive grep), the parent makes every edit, and a port-before-cut census proves nothing was lost. Use for dedupe-our-docs, fix-the-stale-runbooks, pointers-instead-of-copied-numbers jobs."
---

# Refresh stale docs with scout summaries, parent-side writes

Use when a cluster of documentation pages is stale and/or restates facts another page owns, and
the fix touches many files. **Scouts read and classify; the parent writes.** Sibling skill
`vault-one-fact-one-owner-dedupe` covers collapsing era pages into owner pages - its section 3
(orphan census), section 7 (edit-tool hazard) and section 9 (verify/PR) apply unchanged.

## Why not writer subagents (measured cost)

Writer agents produce plausible output and cannot be trusted on the one claim that matters - the
owner page already holds this fact. In one run they asserted every cut was grep-confirmed while
FOUR cuts left pointers to pages that did not contain the fact (118->238 GiB, 16,095 tokens,
0.739/0.554/0.427/0.340, PR #23897). Each became a broken promise the next reader trusts.
Classification is the only part that parallelizes; writing is where taste (ownership, era
naming, what counts as a law) lives. So fan out read-only scouts and keep the pen.

If writer agents were already spawned and are no longer wanted: `write agent://all` to stop
them, then `git status` the target tree - `proc://` does not list agent jobs, and a finished
worker may already have edited files.

## Pipeline

1. **Cluster** targets into groups of 3-4 pages sharing subject matter (one cluster per scout).
   Know the owner map first (endpoint/service/host pages, plus the repo documentation law).
2. **Wave of 2 scouts** (harness cap is `task.maxConcurrency`, usually 2). Scout contract:

   > READ-ONLY, no writes of any kind. Per file, one table row per candidate fact:
   > `| lines | verbatim figure + 6 words | holder elsewhere (file:line) or none | VERDICT |`
   > Verdicts: `CUT -> [[Owner]]` (holder verified), `KEEP(owned here)` (no holder, this page is
   > the record), `PORT(parent)` (rightful owner lacks it - name page and section), `STALE`
   > (contradicted by current state; quote the contradicting line), `INDEX` (locator page).
   > Verify every holder claim with a COMMA-INSENSITIVE grep: a holder writing 1,350,182
   > satisfies a page writing 1350182 and vice versa; 16,095 does NOT satisfy a check for 16095
   > unless commas are stripped. Never name a holder line you have not read.
   > End with a per-file tally: kept / cut / port / stale.

   Put the law, the owner map and the verification rule in the batch-level `context`, never per
   task.
3. **Write while the next wave runs**: edit cluster N from wave N, launch wave N+1 in the same
   turn. Never launch a wave you have nothing to write.
4. **Verify each CUT yourself** before cutting - read the holder line. A scout row is a
   hypothesis, not evidence.
5. **PORT items are your edits**: add the fact to the owner page section (Eras row / Laws / spec
   table), then cut it from the technique page in the same commit.
6. **STALE items: check live state**, not another document - `ssh <host> systemctl is-active
   <svc>`, the endpoint `/health`, the env file. Then rewrite with a date, or drop transient
   live state an owner page already records.

## The ownership test that stops wasted ports

Two pages carrying one figure is the defect - a figure with exactly one holder is fine wherever
it lives. A technique page that is the sole record of a campaign owns that campaign's arm
tables; do not port such ledgers into an endpoint Eras table. Write the clause into the repo
documentation law so the next pass stops porting single-owner facts. Corollary: a worked example
may repeat a live number if it declares itself dated and names the owner (a snapshot, not fleet
state - recompute from the live files).

## Census after each cluster (catches your own slips too)

Run the sibling skill's section 3 census over `git diff -U0` for the cluster (deleted lines x
distinctive numeric keys vs the whole vault **plus AGENTS.md**), comma-insensitively; drive the
count to zero or list each accepted loss in the commit message.

```python
flat = corpus.replace(',', '')
pres = lambda n: n in corpus or n.replace(',', '') in flat
toks = lambda l: [n for n in re.findall(r'\d[\d,]*(?:\.\d+)?', l)
                  if len(n.replace(',', '').split('.')[0]) >= 4
                  or (len(n.split('.')[-1]) >= 2 and len(n.replace(',', '')) >= 5)]
orphan = [l for l in deleted if toks(l) and not any(pres(n) for n in toks(l))]
```

## Verify and land

- Vault link seam must print `0 unresolved links`; hard-wrapped `[[Two Word Page]]` links split
  across lines are the usual cause - unwrap them.
- Full suite once at the end, not per cluster; a docs seam running while scouts are live may
  read half-written files, so re-run after the last edit.
- Commit per cluster (docs-only means **no deploy**); push, open the PR through the API with a
  600-perm curl config, `xdg-open` the PR URL immediately.