---
name: docs
description: 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:

```bash
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:

```bash
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:

```bash
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:

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

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