| name | write-topic-docs |
| description | Draft the embedded help text for ui: topics whose doc is still empty. For each topic it gathers the transcript passages where the maintainer explains it (via the ui: deep-link index), the implementing class, and any existing .help/ page, then distills a short user-facing doc into .help/references/topics/ui-topics.md. Use after the videos are transcribed and analyzed (stage 2), when the user wants to write or fill in the ui topic docs. |
write-topic-docs
STAGE 4 (authoring) of the docs pipeline. The ui: topic registry
(.help/references/topics/ui-topics.md) holds metadata + synonyms + class pointers; the doc body
of each topic is the help shown on hover / in the help panel. This skill fills the _TODO_ bodies —
sourced primarily from the maintainer's own video explanations, located via the ui: deep-link
index and fact-checked against the implementing class.
Run only after stage 2 (/analyze-videos) has populated mentions.json with [ui:Id] mentions —
without them there are no transcript passages to distill from. Full design: .agentic/DOCUMENTATION_ECOSYSTEM.md.
Hard invariants
- Never
git add / commit. Write the docs; the user reviews and commits.
- User-facing voice (
.help/docs/STYLE.md): plain English, second person, no marketing tone.
- Never name the C# class in the prose. The class is your fact-check, not content — STYLE.md
keeps implementation detail out of
.help/. Operators go in [Brackets] (the docs build
auto-links them); bold a UI element on first mention.
- Ground every claim in a source. Distill the transcript passages + class behaviour; don't invent
features. If a topic has no usable video coverage and the class is unclear, leave
_TODO_ and flag it.
Step 1 — find the work
python .help/scripts/topic_doc_sources.py (no arg) lists every topic whose doc is still empty and
prints each one's source bundle. Target one with python .help/scripts/topic_doc_sources.py ui:Timeline.
Step 2 — read the source bundle (per topic)
The helper prints, for the topic: its classes, any existing .help/ page, and the top transcript
passages where it's discussed (ranked in-depth > explained > passing, most recent first) — each with
the video, timestamp and deep-link URL. That bundle is the raw material; prefer recent, in-depth
passages (a lone passing mention is usually too thin to write from).
Step 3 — draft (per topic)
Spawn a subagent with the bundle (or draft directly for a single topic). Produce:
- First line: one sentence — what it is and when you'd reach for it. This is the hover text, so it
must stand alone.
- a blank line, then 2–4 sentences: where to find it, the key actions/parameters, one practical
tip. Second person; bold a UI element on first mention; bracket operators.
Open the classes file(s) only to verify terminology and behaviour — keep the code detail out of the
prose. If a fuller .help/ page exists, keep the embedded doc short and let that page carry detail.
Step 4 — write + refresh
- In
.help/references/topics/ui-topics.md, replace that topic's _TODO_ with the drafted body,
matching the ## <Term> block so it lands on the right topic.
- After the batch, run
python .help/scripts/analysis_to_index.py to fold the docs into topics.json.
- Report which topics were written and which stayed
_TODO_ for lack of sources. Nothing is committed
— the user reviews ui-topics.md and commits.
Notes
- Batch: loop Steps 2–3 over the empty-doc topics, write each as you go, run Step 4 once at the end.
- A meet-up demo distilled into a doc: per STYLE.md, the deep-link URL already records which video and
moment it came from, so the cross-reference is preserved automatically.
