planet/.claude/commands/docs.md

description: Create or update repository documentation from current code changes argument-hint: Optional: topic to document, or leave empty to infer from git diff allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]

/docs — Documentation Workflow

Goal

Create or update documentation that explains why a change exists, how it behaves, and what maintainers need to know. Keep this command generic. Repository-specific coverage rules live in the repository and must be loaded separately.

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

Step 1 — Understand The Change

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

If $ARGUMENTS specifies a topic, focus on that topic. Otherwise infer the documentation topic from the changed files. Do not read the full repository diff by default; inspect focused files only:

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

Step 2 — Decide Scope

• Prefer updating an existing relevant document over creating a duplicate.
• Use one document for one coherent topic.
• Split documents only when the change crosses meaningful domains.
• Keep filenames lowercase and hyphenated.
• Apply the repository-specific rules file before writing.

Document Audience Routing (Planet)

In this repository, classify the action's performer before picking a target file:

• Browser/UI end user → docs/technical/{zh,en}/manual.md or quickstart.md.
• Shell / Docker / log paths / planet.sh / SMTP fallbacks / port forwarding → docs/technical/{zh,en}/ops-runbook.md (or an existing ops-*.md).
• Second-party developers → existing *-context.md / backend-*.md / earth-*.md files.

Never put shell commands, log paths, or Docker operations into manual.md / quickstart.md. Never put UI button labels or screenshots into ops-*.md. When the same action has both a UI and a CLI path, write each in its own home and cross-link them with one sentence.

For ambiguous or large documentation changes, briefly state the intended doc plan before editing. For clear small changes, proceed directly.

Step 3 — Write

Explain:

• Background/problem: what was wrong or missing before.
• Core design decisions and rationale.
• Operational or user-facing impact.
• Relevant code paths, only when useful for future maintainers.

Style:

• Follow the repository’s existing language and heading conventions.
• Use fenced code blocks with language tags.
• Prefer tables for comparisons or parameter lists.
• Keep snippets concise and relevant.
• 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.

Step 4 — Verify

• Read the completed docs once for clarity and stale statements.
• Verify referenced paths exist with test -e or rg --files.
• Run applicable checks from docs/documentation-coverage-rules.md.
• Check Markdown links use readable user-facing titles unless repository rules allow otherwise.

Step 5 — Report

Summarize changed docs and verification:

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

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

Hard Constraints

• Do not leave placeholder docs.
• 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 and tradeoffs behind the change.
• Keep docs maintainable and concise.