84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
---
|
||
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.
|
||
- For UI labels, chart labels, feature names, datasource names, and other terms that may become mixed Chinese/English copy, check `docs/technical/{zh,en}/naming-glossary.md` and use the documented display name. If a confusing term is missing, update the glossary in both languages as part of the docs change.
|
||
|
||
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
|
||
```
|