repo-doc-synchronizer
Audit repository documentation coverage, detect doc drift against live code signatures, update stale references, and author missing Diátaxis documentation suites. Do not use for generic copyediting or non-technical prose.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- repo-doc-synchronizer
- description
- Audit repository documentation coverage, detect doc drift against live code signatures, update stale references, and author missing Diátaxis documentation suites. Do not use for generic copyediting or non-technical prose.
02 资源文件 7
- 参考文档CARD.md4.4 KB
- 参考文档config.default.yaml691 B
- 脚本scripts/doc_ast_inspector.py6.3 KB
- 脚本scripts/doc_synchronizer.py38.8 KB
- 其他templates/api_reference.md.template451 B
- 其他templates/howto_guide.md.template465 B
- 其他templates/package_readme.md.template379 B
03 SKILL.md 正文
Repository Documentation Synchronizer
repo-doc-synchronizer audits codebase documentation coverage, identifies stale or missing documentation across packages and plugins, and authors standardized technical documentation suites conforming to the Diátaxis taxonomy.
See CARD.md for companion cheat sheets, CLI triggers, and invariant checklists.
Overview
The skill operationalizes documentation as an active engineering contract ("Docs-as-Code"):
- AST Symbol Inspection: Extracts classes, callables, type annotations, and docstrings via static analysis.
- Coverage Auditing: Quantifies module documentation health (docstrings, public symbol coverage, dedicated Markdown guides).
- Drift Detection: Flags broken local file links and stale symbol signatures in existing documentation.
- Diátaxis Scaffolding: Synthesizes structured API references, how-to recipes, and package READMEs populated with live AST data.
- Visual Briefs: Emits interactive Mermaid.js diagrams illustrating coverage topology before making modifications.
Dependencies
- developer-docs-architect: Dispatched for deep Diátaxis quadrant authoring (API specs, C4 Mermaid architecture models, and developer guides).
- codebase-context-architect: Dispatched when synchronizing multi-layer agent context files (
AGENTS.md,CLAUDE.md). - crafting-skills: Followed for skill formatting, visual briefs, and summary cards.
Quick Start
1. Audit Repository Documentation Coverage
python .agents/skills/repo-doc-synchronizer/scripts/doc_synchronizer.py audit --root . --output coverage_scorecard.json
2. Detect Documentation Drift and Broken Links
python .agents/skills/repo-doc-synchronizer/scripts/doc_synchronizer.py drift-check --root . --output drift_report.json
3. Generate Interactive Visual Coverage Brief
python .agents/skills/repo-doc-synchronizer/scripts/doc_synchronizer.py visual-brief --root . --output %TEMP%/doc_brief.html
4. Scaffold Missing Diátaxis Documentation
python .agents/skills/repo-doc-synchronizer/scripts/doc_synchronizer.py scaffold --module src/harness/services/agentwikis.py --type api --output docs/api/agentwikis.md
Utility Scripts
The skill provides scripts/doc_synchronizer.py with four deterministic subcommands:
audit:- Analyzes Python modules against Markdown docs.
- Flags files with missing docstrings or missing dedicated documentation.
- Calculates overall coverage percentage against
--min-coveragethreshold.
drift-check:- Strips code blocks to eliminate false positives per Rule 47.
- Verifies relative markdown links against active filesystem files.
scaffold:- Ingests a module via AST.
- Pre-populates clean Diátaxis documentation templates (
api,readme,howto).
visual-brief:- Generates a self-contained HTML file rendering a dark-mode Mermaid diagram showing documented vs. deficit modules.
Workflow: 4-Stage Execution Loop
Stage 1: Documentation Coverage Audit
- Execute the
auditsubcommand across target modules or plugins. - Inspect the generated JSON coverage scorecard to identify undocumented public classes, methods, and modules.
Stage 2: Drift & Integrity Inspection
- Execute
drift-checkacross documentation directories (docs/,plugins/). - Identify broken relative links or stale symbol names resulting from code refactoring.
Stage 3: Visual Brief & Mandatory Checkpoint
- Render an interactive HTML visual brief using
visual-brief. - Present findings and planned additions to the user via
implementation_plan.mdwith explicit Mandatory Checkpoint review gates (RequestFeedback: true). - Halt and await explicit user approval before writing or updating documentation files.
Stage 4: Synthesis, Scaffolding & Verification
- Package-Level Diátaxis Scaffolding: Prioritize authoring package-level
README.mdguides for core packages (src/harness/commands/,src/harness/bridges/) and plugins (plugins/<category>/<plugin>/). A packageREADME.mdelevates all sibling modules by providing live AST symbol tables and manifest metadata without generating file sprawl. - Scaffold missing documentation using
scaffoldwith appropriate Diátaxis quadrant templates. - Update existing documentation files to repair broken links and update function signatures.
- Re-run
drift-checkandauditto verify 100% resolution of coverage deficits.
Anti-Patterns
- Premature File Mutation — Modifying existing documentation or creating new files without first auditing AST symbols and presenting an implementation plan.
- Ungrounded Prose — Writing speculative narrative text instead of deriving class and function documentation directly from active AST syntax trees.
- Broken Relative Links — Writing workspace-absolute
file:///URIs or unverified links that break in sandboxes or CI environments. - Monolithic Conflation — Combining tutorials, architecture rationale, and reference tables on a single page instead of adhering to Diátaxis quadrants.
04 同仓库更多 Skills
ui-behavior-primitive-architect
Architect, audit, and verify zero-dependency headless UI behavior primitives, WebMCP agent bridges, WAI-ARIA/SSR/RTL tri-modal checks, and framework expert routing. Do not use for static CSS theme styling or backend database migrations.
trustgraph-ontology-governor
Govern knowledge graphs, SHACL-AF triple policies, OntologyRAG subclass validation, PROV-O dual named graphs, and Laya entropy decision scoring. Do not use for relational SQL queries or generic web scraping.
shim-harness-governor
Govern universal CLI agent loops, 4-tier tool permissions, ancestor-symlink workspace sandboxes, deterministic-first command routing, collision-safe MCP namespacing, and layered skill loading. Do not use for static UI styling or external SQL analytics.
graphiti-zep-memory-governor
Govern bi-temporal knowledge graphs with Graphiti future-edge clamping, MinHash/LSH entity dedup, RRF/MMR reranking, and Zep typed ontologies. Do not use for static SQL joins or generic web crawling.
agora-mcp-workbench-architect
Architect, audit, and orchestrate Agora Workbench MCP servers, loopback sidecars, unified state graphs, gateway/dispatcher connectors, and policy-enforced data lakes. Do not use for static frontend CSS styling or non-MCP desktop GUI automation.
skill-eval-assurance-runner
Evaluate and assure agent skills using small-N Wilson confidence intervals, unbiased pass^k reliability, deterministic trajectory graders, preflight boundary honesty, and sealed digest verification. Do not use for subjective prose review or unconstrained production deployment.