udocument

name	udocument
description	Use when writing or editing documentation — project docs, AGENTS.md, READMEs, SKILL.md, docstrings, inline comments. Auto-triggers on `.md` files and docstring edits. Enforces lead-with-why, kill stale content, lists over tables, no aspirational sentences.

Document

Documentation is code's second user-facing surface. Treat it with the same care.

Scope — when this skill applies

• Project documentation (README.md, docs/**/*.md)
• AGENTS.md instructions
• SKILL.md files for skill packs
• In-code docstrings (classes, modules)
• Inline code comments

Core rules — apply to every form of documentation

- Lead with the why. What problem does this solve? Why does this exist? Answer before describing what. - Show, don't tell. One concrete example beats three paragraphs of description. - Kill stale content. If a doc describes behavior that doesn't exist anymore, delete — don't "update" with a note. - No aspirational sentences. "This system will eventually support X" — either it supports X now, or it doesn't belong in the doc yet. - Lists over tables. Tables render inconsistently in many viewers and are hard to edit. Lists unless the user explicitly wants a table. - Be terse. Sacrifice grammar for brevity. Short sentences. No "In this section we will discuss..." - Concrete always beats abstract. "The `Dataset` class must not import from `training/`" beats "respect module boundaries."

Project docs (README.md, docs/) — answer four questions

1. What is this? 2. Why does it exist? 3. How do I use it (minimum-viable example)? 4. Where does it fit (links to related docs)?

Keep READMEs under 200 lines. More than that → split into docs/.

AGENTS.md — project-wide agent guidance

• Principles and constraints that apply across the project
• One-line style preferences ("no markdown tables unless asked")
• Pointers to key files or scripts
• What NOT to do (often more useful than what to do)

Do not write per-task instructions here. Those belong in docs/tasks/<slug>.md.

SKILL.md — the frontmatter is load-bearing

• Frontmatter: name, description. The description is the auto-trigger signal — make it specific and action-oriented.
• Short body: when to use, process, key rules, terminal state.
• Section headers should summarize the section. A reader who skims headers should know the gist.
• Target under ~150 lines. A skill the agent won't read is worse than no skill.

In-code docstrings — for large classes and modules, describe responsibility AND non-responsibility

Every large class or module gets a docstring explaining what it's responsible for and what it is not:

class DatasetBuilder:
    """Build dataset shards from raw episodes.

    Responsibilities:
    - Orchestrate download → process → encode → verify stages
    - Persist per-episode progress for restart
    - Validate schema at stage boundaries

    Not responsibilities:
    - Training-time data loading (see training/loader.py)
    - Cloud sync (see ops/sync.py)
    """

For small utility functions, one-line docstring is enough. For short internal helpers, no docstring required.

Inline comments — reserved for non-obvious WHY

- Workarounds for specific bugs: `# sklearn 1.4.x requires args in this order` - Hidden invariants or contracts: `# caller guarantees items is sorted` - Counter-intuitive choices that would look like bugs otherwise - Narrating what the code does: `# increment counter` next to `i += 1` - Historical context: `# added for the Y flow` — belongs in the commit message - Placeholder apologies: `# TODO: clean up later`

Red flags — cut these when you see them

- Aspirational content — cut - Stale content describing removed behavior — delete, don't annotate - Walls of tables — convert to lists - Paragraphs longer than ~4 sentences — split or cut - Duplicate content across docs — consolidate and link - Comments explaining the obvious — delete

Process — six steps, always including "cut 30%"

1. Understand the audience (new contributor? operator? agent?) 2. Decide the shape (list, example, paragraph) based on content type 3. Draft terse 4. Cut 30%. Seriously. Re-read and cut 30%. 5. Show one concrete example if none present 6. Verify nothing is stale or aspirational