118 lines
4.0 KiB
Markdown
118 lines
4.0 KiB
Markdown
---
|
|
name: docs
|
|
description: 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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. 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.
|
|
|
|
4. 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.
|
|
|
|
5. 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
rg -n "\]\(([^)]+)\)" docs/technical/zh/<doc>.md
|
|
```
|
|
|
|
## 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:
|
|
|
|
```md
|
|
Updated:
|
|
- docs/technical/zh/example.md — what changed
|
|
|
|
Verified:
|
|
- no identical en/zh docs
|
|
- no language-less docs/technical links in zh docs
|
|
```
|