planet/.codex/skills/docs/SKILL.md

name, description

name	description
docs	Create or update repository documentation from current code changes. Use when the user asks to write docs, update docs, summarize implementation changes into docs, or check documentation coverage. Load repository-specific coverage rules from docs/documentation-coverage-rules.md when present.

Docs

Use this skill when the task is documentation work: creating, updating, checking, or summarizing docs for code or behavior changes.

Goal

Write documentation that explains why a change exists, how it behaves, and what maintainers need to know. Keep the skill generic; repository-specific rules belong in the repository, not in this skill.

Repository Rules

Before deciding scope, check whether the repository has a documentation rules file:

test -f docs/documentation-coverage-rules.md && sed -n '1,240p' docs/documentation-coverage-rules.md

If it exists, apply it as the project-specific coverage checklist. If it does not exist, continue with the generic workflow below.

Workflow

1. Gather focused context:

git diff HEAD --stat
git diff HEAD --name-only
git log --oneline -10
rg --files docs

If the user gives a topic, focus on that topic. Otherwise infer the doc topic from changed files. Avoid reading large full diffs by default; inspect focused files and symbols:

git diff HEAD -- <path>
rg -n "class |def |function |export |router|@router|interface |type " <path>

2. Decide scope:

• Prefer updating an existing relevant doc over creating a duplicate.
• Use one document for one coherent topic.
• Split documents only when changes cross meaningful domains.
• Keep filenames lowercase and hyphenated.

3. Write the doc:

• Explain background/problem, design decisions, constraints, and operational impact.
• Keep code snippets short and directly relevant.
• List related files only when they help future maintainers navigate.
• Use the repository’s existing language, heading style, and naming conventions.

4. Verify:

• Read the completed doc once for clarity and stale statements.
• Verify important referenced paths exist with test -e or rg --files.
• Run repository-specific doc checks from docs/documentation-coverage-rules.md when present.
• For Markdown links, check that user-facing titles are readable and not raw filenames unless the repository rules allow it.

Hard Constraints

• Do not leave placeholder docs or copied source text pretending to be documentation.
• Do not duplicate bilingual files byte-for-byte.
• Do not reference PR numbers, issue numbers, or the current conversation unless explicitly requested.
• Do not write changelog-style lists without the reasoning, constraints, and tradeoffs behind the change.
• Keep docs concise enough to maintain.

Recommended Output

After editing, summarize:

Updated:
- path/to/doc.md — what changed

Verified:
- checks that passed
- checks that could not be run, if any