--- namespace: aiwg name: doc-sync-35e2eda8c1dd platforms: [all] description: Synchronize documentation and code with bounded, scope-first drift checks commandHint: argumentHint: [--scope "path" --dry-run --parallel N --incremental --guidance "text" --no-commit] allowedTools: Task, Read, Write, Bash, Glob, Grep, Edit model: haiku category: documentation modelRole: efficiency modelTier: economy --- # Documentation-Code Sync Detect and resolve drift between code and documentation without front-loading a full repository audit. Treat standard Sonnet context as the baseline. ## Invocation `/doc-sync [options]` Directions: - `code-to-docs`: code is source of truth - `docs-to-code`: docs are source of truth - `full`: bidirectional reconciliation; conflicts require human review Options: - `--scope "path"`: limit the run to a subtree or file group - `--incremental`: inspect changed files first - `--dry-run`: report only - `--parallel N`: cap concurrent auditors; default `2`, maximum `4` - `--guidance "text"`: use operator guidance for ambiguous cases - `--no-commit`: do not commit ## Artifact root resolution Treat every `.aiwg/...` path below as a logical artifact path. Before reading or writing sync state, working evidence, or reports, run `aiwg artifacts path` from the active workspace and use the returned absolute directory as `AIWG_ARTIFACT_ROOT`. Never write these payloads to a literal project-local `.aiwg/` when `AIWG_ARTIFACTS_PATH` or `.aiwg-location` redirects the corpus. ## Context Budget Rules - Start with `git status --short` and `git diff --name-only`; do not read broad diffs before the changed-file set is known. - If neither `--scope` nor `--incremental` is supplied, derive a candidate scope from changed files and ask before expanding to full repo. - Prefer shell inventories (`find`, `rg --files`, `git diff --name-only`) over reading file bodies. - Dispatch subagents only after scope is known. Use at most `min(--parallel, 4)` auditors, and prefer `2` for broad or release requests. - Each auditor must return at most 10 findings and 600 words. It should write detailed evidence to `$AIWG_ARTIFACT_ROOT/working/doc-sync/` and return only the path plus a summary. - Do not preload other skills into subagents. If another capability is needed, invoke it after this skill finishes or in an isolated follow-up. ## Workflow 1. Parse direction and options. 2. Build a cheap scope inventory: - `git status --short` - `git diff --name-only` - `git diff --cached --name-only` - `rg --files docs README.md CHANGELOG.md package.json src agentic tools` only when the changed-file set is insufficient. 3. Choose audit lanes from the scoped files: - CLI/API docs - provider/deployment docs - skill/agent catalogs - README, changelog, release, or blog material - config/schema docs 4. Run bounded auditors for only the selected lanes. Each prompt must include: - exact paths to inspect - direction - max 10 findings - max 600-word return summary - instruction to store detailed notes under `$AIWG_ARTIFACT_ROOT/working/doc-sync/` 5. Merge summaries into `$AIWG_ARTIFACT_ROOT/reports/doc-sync-audit-{date}.md` with: - scope - findings by severity - auto-fixable vs human-required items - files changed or proposed changes 6. If not `--dry-run`, apply high-confidence fixes only. 7. Validate modified files with targeted checks: - markdown link/anchor checks where available - `npm run lint:claude-context` if Claude-facing skills or agents changed - project-specific build/test checks only when source changed 8. Record `$AIWG_ARTIFACT_ROOT/.last-doc-sync`. 9. Commit only when requested by the surrounding workflow and not blocked by `--no-commit`; otherwise leave a concise final summary. ## Release or Blog Coverage Requests For combined requests such as "docSync code2doc, ensure the monthly blog covers the work, then commit-and-push": 1. Keep this skill to documentation drift detection and fixes. 2. Treat blog/release coverage as one selected audit lane with changed files plus month-bounded git history, not a full repository read. 3. Return a handoff summary for `commit-and-push` instead of invoking it inside this skill. ## Output Contract Return: - audit report path - files changed - remaining human-review items - validation commands run - next recommended skill, if any --- Source attribution: jmagly Original project: https://github.com/jmagly/aiwg/blob/bc0cd4d707708593ef15781cb9d38364ea29bdd5/agentic/code/frameworks/sdlc-complete/skills/doc-sync/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2024 Joe Magly Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jmagly Original project: https://github.com/jmagly/aiwg/blob/bc0cd4d707708593ef15781cb9d38364ea29bdd5/agentic/code/frameworks/sdlc-complete/skills/doc-sync/SKILL.md Attribution basis: Source repository record Fields of work: Content & Media, Development & Engineering, Product Management Roles: Backend Developer, DevOps / SRE, Product Manager, QA / Test Engineer, Technical Writer Specialties: API, Testing Tools: Aiwg Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 0e313eeff96e3a78c2acc67fcf97cf03d322b4dd6bb94c0d9603fd34d10f126f