Docs Maintainer

Docs Maintainer

Use this skill to decide whether public docs need updates and to make those updates in the right place.

Docs Boundaries

• Public website docs source lives under docs/public/**.
• Repository-facing public docs also include the root README.md and docs/screenshots.md; search them for feature, integration, and screenshot changes even when the website source is unchanged.
• Product context, requirements, and system designs stay under docs/specs/**.
• Implementation plans and work orders stay under docs/plans/**.
• Architecture decisions stay under docs/decisions/**.
• Raw supporting notes can remain under docs/** outside docs/public/**, but do not publish them unless rewritten for users.
• docs/public/meta.json owns published-page order and navigation groups. Page paths own routes, and page frontmatter owns titles and descriptions.
• The landing/docs website generates its content from this directory. Do not hand-edit generated files in the landing repository.

When Docs Need Updates

Check public docs when a change affects:

• CLI commands, flags, install commands, or runtime launch behavior.
• Configuration keys, environment variables, defaults, profiles, or feature flags.
• Workspaces, workflows, tasks, agents, executors, worktrees, Git behavior, or review flows.
• Docker, Kubernetes, service, desktop, remote environment, or Windows instructions.
• Public APIs, WebSocket messages, workflow import/export schemas, or integration contracts.
• Screenshots, visible UI labels, navigation, onboarding, or user-facing terminology.

Skip public docs when the change is:

• Purely internal refactoring with no behavior change.
• Test-only, fixture-only, or build-only without user-visible behavior.
• A speculative plan or design note that belongs in docs/specs/**, docs/plans/**, or docs/decisions/**.

Workflow

1. Identify docs impact from the diff and changed behavior.
2. Search docs/public/**, the root README.md, and docs/screenshots.md first for affected terms, features, integrations, and screenshots. For behavior changes, also search the same contract and old precedence/reset wording across docs/public, docs/specs, and docs/decisions; ensure the introductory summary agrees with later upgrade and recovery sections.
3. If public docs exist, update them with the same PR as the behavior change.
4. If no public docs exist but the behavior is user-facing, add or propose the smallest useful public page/section. When adding a page, include title and description frontmatter and list its page slug or path without the .md extension in docs/public/meta.json exactly once, for example cli. See docs/public/README.md.
5. If the change only updates implementation intent or architectural history, update specs/plans/ADRs instead.
6. For operational recovery guidance, distinguish permission-denied, active-lock, and stale-lock failures before recommending a fallback. Verify that the fallback uses a different execution or resource path; if it shares the same worktree, state that it cannot bypass the contention.
7. Classify each public page by its primary Diátaxis content type:
   • Tutorial: teach a beginner by leading them through one successful outcome.
   • How-to guide: help a reader complete a known task, with focused steps, choices, and recovery paths.
   • Reference: provide accurate, complete lookup information such as fields, commands, defaults, limits, or protocol contracts.
   • Explanation: build understanding of a concept, boundary, rationale, or trade-off. Keep one dominant type per page. Link to another page when a long section changes from learning to procedure, lookup, or explanation; do not force every page into a generic tutorial-shaped opening.
8. Keep public docs task-oriented and scan-friendly:
   • Tutorials should lead with prerequisites and a linear first success; how-to guides should lead with the task, expected result, and only the prerequisites it needs.
   • Reference pages should lead with scope and the contract readers need to look up; explanation pages should lead with the question or concept and why it matters.
   • Use short paragraphs (one idea, normally three sentences or fewer) and bullets for choices, limits, and consequences.
   • Prefer a link to the page that owns a detailed contract over repeating it.
   • Use native <details> / <summary> disclosures for non-essential edge cases, exhaustive option lists, and advanced configuration. Keep required steps, security warnings, destructive effects, and eligibility limits visible.
   • Use tables only for genuine comparisons, not narrative text.
   • Treat drafts or substantial rewrites over about 3,000 words as a structure-review trigger, not a word limit. Check that the page serves one main audience, content type, and reader goal; remove repeated explanations; move secondary detail to its owning page or a disclosure; and keep the common path near the top. Add a short grouped topic index when a long page needs to remain together. Preserve supported behavior, limits, security warnings, and recovery requirements instead of deleting them to reduce word count. See docs/public/README.md for the full long-page review rule.
9. Preserve internal links inside docs/public/** where possible. Link to source-only raw docs only when the raw note is intentionally not published.
10. Note docs impact and the page's primary content type in the PR body.