docs-sync

Featured

Use this skill whenever a pull request is opened, reopened, or synchronized in microsoft/apm to assess whether and how the documentation corpus must change to stay truthful with the proposed code change. Activate even when the PR title or body says nothing about docs -- the skill must run on every PR to detect silent drift between code and docs. Classifies impact as no-change, in-place edit (one to a few paragraphs), or structural change (new page or TOC reshape), then orchestrates a CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop to produce a patch-ready advisory. Does NOT review code quality, security, or test coverage. Does NOT auto-merge or auto-push doc edits.

AI & Automation 3,385 stars 300 forks Updated 2 days ago MIT

Install

View on GitHub

Quality Score: 91/100

Stars 20%
100
Recency 20%
100
Frontmatter 20%
70
Documentation 15%
100
Issue Health 10%
50
License 10%
100
Description 5%
100

Skill Content

# 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-...

Details

Author
microsoft
Repository
microsoft/apm
Created
10 months ago
Last Updated
2 days ago
Language
Python
License
MIT

Integrates with

GitHub · DevTools

Similar Skills

Semantically similar based on skill content — not just same category

Code & Development Featured

docs-corpus-audit

Use this skill to run a holistic regrounding pass on the entire microsoft/apm documentation corpus against current source code, page-by-page, and emit surgical fixes for stale claims. Activate when the maintainer wants a WHOLE-CORPUS audit (not per-PR review) -- typical triggers include "audit the docs", "reground the corpus", "check every page against code", "pre-release docs sweep", "the docs have drifted everywhere", or "we just reshaped the TOC, find dead links". Wave-batched and S7-verified; scales to the full ~112-page corpus in ~10 minutes wall-time. This is a SIBLING to docs-sync, not a replacement: docs-sync is per-PR (triggered by a diff); this skill is per-corpus (triggered by a maintainer ask). They share agent personas, schemas, and the docs index, but their triggers MUST NOT collide. Does NOT auto-merge, does NOT push without maintainer review, and does NOT replace per-PR drift detection.

3,385 Updated 2 days ago
microsoft
Data & Documents Listed

doc-sync

Detect documentation drift against current code and confirmed decisions, then propose only the smallest accurate doc updates. Never edit docs without explicit human approval. Use when user asks whether docs need updating, code behavior has changed, interfaces or identifiers have changed, or suspected drift needs investigation. For a full-surface audit across all canonical docs, use the bug-hunt skill's full doc-sync audit (explicit request only), not this skill.

0 Updated today
davidleberknight
AI & Automation Solid

docs-sync

Reconciles `README`, `docs/*`, `CLAUDE.md`, and agent/skill/plugin prompt files with what the code actually does: fixes stale, missing, or overpromising claims and verifies every quoted command/flag/path. Use after a change alters documented behavior, when a tool's output shape or fields change, or to sweep all docs.

5 Updated today
uwuclxdy