docs(discovery): the $ARGUMENTS-on-preload claim is unsupported at five sites, and three files state three different write boundaries

[kyle-sexton]

Two of discovery's own explanatory claims are not backed by the surfaces they cite. A harness behavior — that $ARGUMENTS substitutes to the empty string on the preload path — is stated as settled fact at five sites and is not covered by current documentation in either direction. And three files state three different versions of the agents' write boundary, with a sanctioned scratch location that no file assigns a naming convention or a cleanup owner. In both cases the operational conclusion is correct; the stated reason is what is wrong, and a wrong reason is what survives a rewrite.

#2222 explicitly left the first claim alone ("That older claim is untouched here and is tracked separately") — this issue is that tracking.

Rows

• I1 F8 / I9 D-F6 (one defect, two ledgers) — plugins/discovery/agents/explorer.md:23, plugins/discovery/agents/researcher.md:27, plugins/discovery/skills/explore/SKILL.md:85, plugins/discovery/skills/research/SKILL.md:74, plugins/discovery/skills/research/context/dispatch.md:17 — the "$ARGUMENTS substitutes to the empty string on the preload path" claim, asserted as fact at five sites. A weaker sixth instance at skills/explore/SKILL.md:161 ("under dispatch, where $ARGUMENTS is empty") should be swept with them.
• I1 F6 — plugins/discovery/reference/artifact-protocol.md:27, plugins/discovery/agents/explorer.md:72, plugins/discovery/agents/researcher.md:91 — three statements of the write boundary that do not agree; scratch is sanctioned in the memory slice by one, out of bounds under another, and admitted only incidentally by the third. No file assigns a scratch naming convention or a cleanup owner.

Evidence

The unsupported claim — skills/research/SKILL.md:74:

**A dispatched run does not read that line.** `$ARGUMENTS` substitutes to the empty string on the preload path, and a non-fork subagent has no view of the conversation to fall back on

Docs check, https://code.claude.com/docs/en/skills, fetched 2026-08-11: the substitution table reads "$ARGUMENTS — All arguments passed when invoking the skill" — invocation only. Preload is explicitly a different path: "Subagents with preloaded skills work differently: the full skill content is injected at startup." https://code.claude.com/docs/en/sub-agents, same date: "The full content of each listed skill is injected into the subagent's context at startup" — and nothing about argument substitution on that path. The nearest documented analogue points the other way: the context: fork walkthrough shows the subagent receiving the skill content as its prompt with the placeholder arriving as literal unsubstituted text.

This is recorded as unsupported, not as false. The docs are silent; nothing here establishes that the plugin's sentence is wrong. What is wrong is asserting an uncovered harness behavior as the stated reason, in five places.

The three write boundaries — reference/artifact-protocol.md:26-27 sanctions scratch:

- Memory tier: `EXPLORE.md`, `RESEARCH.md`, `<stage>-checklist.md`, `baselines/`, raw captures, and
  scratch under `<memory_dir>/<topic-slug>/`.

agents/explorer.md:71-73 puts it out of bounds:

`Write` has exactly two permitted destinations: the artifact files inside the memory-slice path
named in your dispatch prompt, and the memory root's self-ignoring `.gitignore` guard when it is
absent.

agents/researcher.md:91-93 gives a third formulation — "Your write destination is exactly one place: files inside the memory-slice path named in your dispatch prompt, plus the memory root's self-ignoring .gitignore guard" — which technically admits scratch while the surrounding prose is about artifact files, and agents/researcher.md:90 separately sanctions "curl into the session scratch dir." grep -rn -i 'clean up\|cleanup' across both agents, both SKILL.md files, both dispatch spokes and artifact-protocol.md finds no cleanup obligation assigned to anyone.

Notes for the fix

• The $ARGUMENTS claim's operational conclusion holds under either harness behavior — scope must come from the dispatch prompt and the agent must refuse to guess. Soften all six copies to the form that holds either way: the scope does not reach a preloaded body by argument substitution; do not rely on seeing an unfilled slot. Strictly stronger than what is there now.
• Keep the boundary fix(discovery): make the by-value fallback reachable, declare the researcher's real tool grant, and echo the input back #2222 already drew. Both SKILL.md files now carry a caveat explicitly separating this claim (a placeholder the plugin's own body carries, preload path) from the caller-supplied-${CLAUDE_…} observation (skills/explore/SKILL.md:87, skills/research/SKILL.md:76). Neither is evidence for the other; a fix must not re-merge them.
• F6 is not a leak: the scratch location is sanctioned. The defect is ownership and naming — reconcile the three statements to one, pick a scratch prefix, and state who cleans up and what happens when the run dies.

Provenance

Severity: LOW · Provenance: AUDITOR_VERIFIED
Origin: handoff-inbox items 20260810-225904-discovery-dispatch-persistence-contract and 20260811-021645-plugin-audit-four-components-and-guard-deadlock-ownership
Ledgers: .work/handoff-inbox-batch-4/ledgers/I1-discovery-dispatch.md §§ F6, F8 · .work/handoff-inbox-batch-4/ledgers/I9-021645-four-components.md § "Lane B — discovery / research" (D-F6)
Verified against origin/main 9b34a82a. discovery went 0.13.1 → 0.14.0 in #2222 (d6e4b452) after the ledgers were written at dacb8661; the five sites are unchanged in number — #2222 added zero new ones — but their line numbers are re-pinned at 9b34a82a and differ from the ledgers'.

[kyle-sexton]

Skipping this wave — not clearly docs-only/small after reading the body.

• F8 ($ARGUMENTS-on-preload): six-site prose soften is tractable docs-only, but…
• F6 (write boundaries): reconciling three conflicting scratch/write-boundary statements, picking a scratch prefix, and assigning cleanup ownership is a design decision beyond a tiny mechanical fix.

Recommend splitting F8 into its own issue if you want a docs-only pass without the F6 boundary reconciliation.

[kyle-sexton]

Skip — covered by open PRs #2306 (partial, I1/F8 row) and #2311 (full batch including F6 write boundary). No additional PR from this drain lane.