docs-sync -- per-PR documentation impact panel

The docs corpus drifts silently and constantly. This skill catches drift at PR-open time, classifies its impact, and orchestrates a persona panel to produce a patch-ready advisory comment.

The pattern is A1 PANEL + B1 FAN-OUT/SYNTHESIZER + A8 ALIGNMENT LOOP. The classifier is the cost gate (~70% of PRs short-circuit to no-change with ~1 LLM call). When the panel does fan out, every agent reads a bounded context (~10 KB) -- never the full corpus.

This skill is ADVISORY. It does not gate merge, apply verdict labels, or push to the contributor's fork. The orchestrator is the sole writer to the PR: exactly one comment per run (idempotent edit-in-place), plus optional label sweeps.

Architecture invariants

• Cost ceiling: 15 LLM calls per run. Hard-wired. The orchestrator refuses to spawn beyond. Header prints N/15 for observability.
• Single-writer interlock. Only the orchestrator writes. Panelist subagents return JSON; they MUST NOT call any gh write command, post comments, or touch PR state.
• Idempotent comment. Exactly one comment per run, with a stable header ## Docs sync advisory. Re-runs edit-in-place using gh pr comment --edit-last.
• No fork-write. Companion docs PRs (only on structural verdict with docs-sync-confirm label) open from a bot branch in the BASE repo; never pushed to the contributor's fork.
• Index-not-corpus reads. Every classifier and architect agent reads .apm/docs-index.yml, NOT the corpus itself. The corpus is sampled only by the localizer (which reads the specific candidate pages) and by per-page panelists (which read one page each).
• S7 deterministic tool bridge. The python-architect panelist MUST run real apm --help, grep, and python -c commands to verify doc claims, never assert from prose.

Roster

Topology

   docs-sync SKILL (orchestrator thread)
                 |
   Step 1: classify (1 LLM call, may exit here)
                 |
                 v
            verdict?
            /    |    \
   no-change  in-place  structural
       |        |          |
     EXIT       |       architect (TOC delta)
                |          |
                +----<-----+
                |
   Step 2: localize (1 LLM call) -- per-page task brief
                |
   Step 3: FAN-OUT panel via task tool
                |
       +----+----+----+----+
       v    v    v    v    v
     writer  verify edit growth
     x N    x N   once  once
       (parallel; each <=10 KB context)
                |
   Step 4: schema-validate returns
                |
   Step 5: CDO synthesize (1 LLM call)
                |
            agree?
            / | \
        revise (N<=3 redrafts) | agree
                                  |
   Step 6: emit ONE comment via safe-outputs.add-comment
   Step 7: OPTIONAL companion docs PR (only if structural AND
           `docs-sync-confirm` label present)

Execution checklist

Step 1 -- Classify

Spawn ONE task: load the docs-impact-classifier skill, pass it the

…