Docs Sync

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 require Step 7's fresh responsible-human issue-scope checkpoint and open in the BASE repo; never pushed to the contributor's fork. Labels request advice, not implementation.
• 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 (structural AND fresh
           responsible-human issue-scope checkpoint)

Execution checklist

Step 1 -- Classify

Spawn ONE task: load the docs-impact-classifier skill, pass it the PR number. It returns the classifier JSON.

Validate the JSON against assets/classifier-return-schema.json. On schema failure, abort the run with a comment explaining the internal error.

If verdict is no_change: skip to Step 6 with a brief advisory ("No docs impact detected. Reason: <one-line>. LLM calls: 1/15.")

Step 2 -- Localize (in_place) or Architect (structural)

For in_place: spawn ONE task that loads the docs-impact-localizer skill with the classifier output. Returns per-page task briefs.

For structural: spawn ONE task that loads the docs-impact-architect skill with the classifier output. Returns TOC delta + new-page outlines + downstream in-place pages. THEN spawn the localizer for those downstream pages.

Step 3 -- Fan-out panel

Cascade-size mitigation (PR 1244 class). If scope_pages[] has

8 entries, the per-page fan-out at one writer call per page would approach the 15-call ceiling with no headroom for verifier redrafts. BEFORE spawning, group scope_pages[] into SECTIONS:

• Pages under the same TOC section (e.g. all consumer/**) with the SAME conceptual fix (e.g. "rename apm update -> apm self-update in every mention") become ONE writer task with a pages_in_section[] array in its brief.
• A 9-page rename cascade collapses to 2-3 section writer tasks.

The python-architect verifier still runs per verify_claims[] (not per page), because S7 evidence is keyed on claims, not pages.

For each page-or-section in the per-page task brief, spawn TWO parallel tasks:

1. doc-writer task -- drafts the patch for that page's (or section's) specific edits. Output: JSON with before:, after: for each location.
2. python-architect task -- for each verify_claims[] in the page brief, run the actual command (S7 tool bridge: apm <verb> --help, grep -n <symbol> src/). Output: JSON with claim: verified | refuted | inconclusive per claim.

In parallel with the per-page fan-out, spawn ONCE each:

3. editorial-owner task -- receives ALL writer drafts, returns tone fixes.
4. oss-growth-hacker task -- receives ALL writer drafts, returns ramp-clarity notes (does this read well to a cold OSS visitor).

All panelist tasks return JSON matching assets/panelist-return-schema.json. Schema-validate every return; on failure, abort.

Step 4 -- Validate

Cross-check:

• Every verify_claims from a python-architect comes back verified or inconclusive (never refuted). If any are refuted, the doc-writer's draft is wrong; re-run the writer for that page with the refutation as context.
• Cross-page constraints from the localizer are honored across all writer drafts.
• All drafts are ASCII-only (per repo encoding rule).

Step 5 -- CDO synthesize

Spawn ONE task: load the cdo persona with the full panel return (writer drafts + verifier reports + editorial notes + growth notes

• classifier verdict + (architect output if structural)) and .apm/docs-index.yml.

The CDO returns one of three verdicts:

• agree: ship. Proceed to Step 6.
• revise: re-spawn the writer panelists with the CDO's specific concerns as additional context. Re-run the editorial and growth passes if needed. Bounded N <= 3 redrafts. Increment a redraft counter; if it hits 3 and CDO still disagrees, ship with cdo_disagreement_noted: true.
• ship_with_disagreement: ship as-is with the disagreement surfaced in the comment for the maintainer to weigh.