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

name, description

name	description
docs	Analyze current Planet repo changes and create or update technical documentation under docs/technical/zh. Use when the user asks to write docs, update technical docs, summarize implementation changes into documentation, or port the Claude docs-codex workflow into Codex.

Docs

Use this skill when the user asks to create or update Planet technical documentation, especially under docs/technical/zh/.

Goal

Write or update technical docs that explain why a change exists, not only what files changed.

Default target directory:

• docs/technical/zh/

Workflow

1. Gather change context:

git diff HEAD --stat
git diff HEAD --name-only
git log --oneline -10
ls docs/technical/zh/

If the user gives a specific topic, focus on that topic. Otherwise infer the documentation topic from the file list and diff stat. Do not read the full repository diff by default; inspect focused diffs only for the files that define the doc topic:

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

2. Decide document scope:

• Use one document for one coherent topic.
• Split documents when the changes cross meaningful domains, such as backend performance and ops startup behavior.
• Prefer updating an existing relevant doc over creating a duplicate.
• Name new files as lowercase hyphenated domain-topic-detail.md, for example:
  • backend-datasources-api-performance.md
  • ops-planet-sh-startup.md
  • earth-bgp-context.md

3. Apply the documentation coverage checklist before writing:

• User-visible workflow changes must update docs/technical/zh/manual.md and usually docs/technical/zh/quickstart.md.
• If an English counterpart exists for user-facing docs such as manual.md or quickstart.md, update docs/technical/en/... enough that it does not contradict the Chinese source.
• Control console page responsibility changes must update docs/technical/zh/frontend-admin-frontend-context.md.
• Earth frontend behavior changes must update docs/technical/zh/earth-frontend-context.md.
• Earth layer additions, renderOrder, altitude/radius offsets, depth strategy, pointer picking, legend modes, or layer panel/startup ordering must update docs/technical/zh/earth-render-layer-order.md.
• Earth layer visual style or legend symbol/color semantics should also update docs/technical/zh/earth-layer-style-reference.md when that reference is affected.
• Collector, datasource, credential, settings, connectivity, scheduler, or API changes must update the relevant backend docs, especially docs/technical/zh/backend-collectors.md and any datasource/settings-specific doc.
• When a change turns an old plan assumption into current behavior, update the relevant docs/plans/*.md with a status note instead of leaving contradictory instructions.
• If adding a new technical document, add it to docs/technical/zh/README.md when it should be discoverable from the technical docs index.
• Search docs for stale terms introduced by the change, for example old tab names, old route responsibilities, obsolete auth assumptions, or renamed UI labels.

4. Write the doc in Chinese:

• Write Chinese prose for docs/technical/zh/.
• Keep technical identifiers, API paths, config keys, code symbols, and standard product names in English where appropriate.
• Use ## and ### headings; avoid going deeper than three levels.
• Use fenced code blocks with language tags.
• Use tables when comparing options or listing parameters.

5. Required content:

• Background/problem: what was wrong before and why the change was needed.
• Core design decisions and rationale.
• Key code snippets, preferably before/after or focused excerpts.
• Related files and what each file contributes.

6. Verification:

• Read the completed doc and check that the reasoning is clear.
• Verify important referenced paths exist.
• Use rg --files or test -e for path existence instead of relying on memory.
• Run a quick duplicate-language check when editing bilingual docs:

python - <<'PY'
from pathlib import Path
same = []
for en in sorted(Path("docs/technical/en").glob("*.md")):
    zh = Path("docs/technical/zh") / en.name
    if zh.exists() and en.read_text() == zh.read_text():
        same.append(en.name)
if same:
    raise SystemExit("identical en/zh docs: " + ", ".join(same))
print("no identical en/zh docs")
PY

Also check that Chinese docs do not link to the old language-less technical docs path:

rg -n "/home/ray/dev/linkong/planet/docs/technical/(?!zh|en)" docs/technical/zh --pcre2

This command should return no matches.

If checking many links, prefer deterministic extraction:

rg -n "\]\(([^)]+)\)" docs/technical/zh/<doc>.md

Also run focused stale-term searches derived from the change, for example:

rg -n "old label|old route purpose|obsolete provider assumption" docs/technical docs/plans

Hard Constraints

• A file under docs/technical/zh/ must not be an English source file copied as a placeholder.
• Do not leave a Chinese doc with only an English title and English first-screen content.
• When an English counterpart exists in docs/technical/en/, never duplicate it byte-for-byte into docs/technical/zh/.
• Internal links inside docs/technical/zh/ should point to docs/technical/zh/... for Chinese docs, unless intentionally linking to an English-only file.
• Do not reference PR numbers, issue numbers, or the current conversation.
• Do not write changelog-style lists like "changed A, changed B, changed C" without the constraints and tradeoffs behind those changes.
• Keep code snippets concise and relevant.

Recommended Output

After editing, summarize:

Updated:
- docs/technical/zh/example.md — what changed

Verified:
- no identical en/zh docs
- no language-less docs/technical links in zh docs