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.
• If a technical document should be visible in the public Docs page or linked from a technical README, register it in frontend/src/pages/Docs/docs-content.ts under DOCS_METADATA. The frontend uses this whitelist; files under docs/technical/{zh,en}/ are not automatically routable.
• For every public technical doc, keep the bilingual file pair in sync by filename: docs/technical/zh/<name>.md and docs/technical/en/<name>.md. If the content is intentionally Chinese-only or English-only, state that intentionally in the final note.
• 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.

Check that public docs are whitelisted in the frontend Docs registry. Any .md linked from docs/technical/{zh,en}/README.md and located under docs/technical/{zh,en}/ must have a matching DOCS_METADATA key:

python - <<'PY'
import re
from pathlib import Path

metadata = Path("frontend/src/pages/Docs/docs-content.ts").read_text()
known = set(re.findall(r"'([^']+\.md)':\s*\{", metadata))
known.add("README.md")

missing = []
for readme in [Path("docs/technical/zh/README.md"), Path("docs/technical/en/README.md")]:
    if not readme.exists():
        continue
    for href in re.findall(r"\]\(([^)]+\.md)\)", readme.read_text()):
        path = Path(href)
        if "docs/technical/" not in href:
            continue
        filename = path.name
        if filename not in known:
            missing.append(f"{readme}: {filename}")

if missing:
    raise SystemExit("docs README links missing DOCS_METADATA: " + ", ".join(missing))
print("docs README links are whitelisted")
PY

Check bilingual parity for public docs. Every whitelisted document except README.md should exist in both language directories unless intentionally documented otherwise:

python - <<'PY'
import re
from pathlib import Path

metadata = Path("frontend/src/pages/Docs/docs-content.ts").read_text()
filenames = sorted(set(re.findall(r"'([^']+\.md)':\s*\{", metadata)) - {"README.md"})
missing = []
for filename in filenames:
    for lang in ("zh", "en"):
        path = Path("docs/technical") / lang / filename
        if not path.exists():
            missing.append(str(path))
if missing:
    raise SystemExit("missing bilingual docs: " + ", ".join(missing))
print("public docs have zh/en file pairs")
PY

Check that Markdown links do not expose raw filenames as user-facing titles. This should return no matches for polished public docs:

rg -n "\[[^]]+\.md\]\(" docs/technical/zh docs/technical/en

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.
• Public technical documents must be registered in frontend/src/pages/Docs/docs-content.ts before considering them available in the Docs UI.
• Public technical documents should have both zh and en files with the same filename, unless intentionally exempted.
• Markdown link text in public docs should be a readable title, not a raw filename such as manual.md.
• 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
- public docs are registered in DOCS_METADATA
- public docs have zh/en file pairs
- no raw `.md` filenames as public link titles