Docs Sync

Use this skill when the user wants to audit documentation coverage, keep docs/ aligned with implementation changes, or update public technical docs.

Scope

This skill is for public documentation under docs/**.

Rules:

1. Treat docs/plans/** as internal tracking, not public documentation.
2. English only.
3. Keep edits concise and easy to maintain.

Workflow

1. Define the scope to review

Pick one of these modes:

1. full public-doc audit against the current branch
2. doc sync for a specific feature or directory
3. diff-based audit against main for in-flight changes

Prefer diff-based review when there is active branch work. Prefer a full audit when the user asks for broad documentation cleanup.

2. Build a feature inventory from code

Review the selected scope in code first.

Focus on user-facing behavior:

1. public exports
2. runtime behaviors and guarantees
3. configuration options and defaults
4. examples that define supported usage
5. important developer workflows
6. renamed, removed, or newly added features

Capture lightweight evidence:

1. file path
2. symbol or setting name
3. short note about the behavior that should be documented

3. Review the existing docs hierarchy

Use the current docs tree as the source of structure.

Start with docs/README.md, then inspect the relevant folders and pages. Follow the portal navigation contract for every section and nesting depth. Put related pages in their shared folder; the portal derives the hierarchy from these paths during each rebuild. Keep page titles concise within that hierarchy. Remove repeated parent names and use exact tool names for individual tool reference pages.

When reviewing, prefer updating an existing page over creating a new one unless the topic clearly has no home.

If you add, remove, or rename a public docs page, update docs/README.md. If you move a page or folder, repair incoming links because its route changes.

4. Compare docs against code

Look for:

1. missing public behavior
2. outdated names, defaults, or semantics
3. examples in docs that no longer match implementation
4. information that belongs on a different page for discoverability
5. public docs that accidentally expose internal rollout or planning details

5. Produce a Docs Sync Report

Before editing, produce a short report with:

1. doc gaps
2. inaccurate or outdated content
3. structural suggestions, if any
4. proposed file-level edits

Keep the report concise.

6. Apply updates if asked

Use the dev-docs skill before drafting or revising public documentation. Find it in the session's skill catalog and read its SKILL.md. Apply its review checklist to changed pages. Repository terminology and ASD-STE100 Simplified Technical English take precedence. If the skill is unavailable, report the missing dependency; do not claim that its review passed.

When applying edits:

1. edit only the relevant public docs under docs/**
2. keep the current writing style and section structure
3. keep examples short and directly tied to the repo
4. prefer current-state documentation over rollout history
5. do not add jokes, slang, rhetoric, puns, or contrastive-negation phrasing

7. Rebuild the documentation portal

After you apply public documentation updates, use the repository docs-portal skill to rebuild and check the website. Keep the Markdown in root docs/; the website reads it directly at build time. Do not create a second content copy under website/.

For a read-only audit, report the recommended updates without a rebuild.

Writing Style

Match the existing documentation style in this repository.

Rules:

1. write in plain technical English
2. prefer short sections and short paragraphs
3. use direct statements over persuasive or dramatic framing
4. explain the current behavior, boundaries, and intended usage
5. keep examples minimal and realistic
6. avoid figures of speech, jokes, slang, and rhetorical phrasing
7. avoid contrastive negation patterns such as “not X, but Y”
8. keep tone neutral and open-source appropriate

Public Docs Boundary

For this repository, public docs currently live under docs/**.

Internal tracking docs live under docs/plans/** and should not be treated as the public documentation surface.

Output format

Use this report shape when auditing before edits:

Docs Sync Report

• Scope
  • What was reviewed
• Missing or weak coverage
  • Doc file or missing page -> evidence -> proposed change
• Incorrect or outdated content
  • Doc file -> issue -> correct behavior -> evidence
• Structural suggestions
  • Proposed move/add/remove -> rationale
• Proposed edits
  • File -> short summary

References

• references/doc-coverage-checklist.md