# Annotate

> Adds comments that explain code: an overview above a function with numbered steps and matching inline checkpoints for multi-step methods, or a file-top block comment for specific behavior the user names. Use when the user says annotate, /annotate, say-so, /say-so, step annotations, file header explanation, or wants a concise walkthrough or behavior note.

- Skill: `morgs32/annotate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add morgs32/annotate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/morgs32/annotate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: morgs32 (https://skillmd.com/u/morgs32)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/morgs32/annotate

---


# Annotate

Add **comments only** — no behavior changes, renames, or refactors. Pick the mode that matches what the user asked for.

## Modes

| Mode                       | Trigger                                                         | Where                         | What                                           |
| -------------------------- | --------------------------------------------------------------- | ----------------------------- | ---------------------------------------------- |
| **Function walkthrough**   | `/annotate`, step annotations, numbered walkthrough of a method | Above a **function** + inline | What the exported method does in the larger architecture, then numbered phases and `// N — …` checkpoints for multi-step methods |
| **File-top behavior note** | `/say-so`, file header explanation, document specific behavior  | Top of **file**               | Prose about **prompted** behavior only         |

Do **not** mix modes unless the user asks for both. For say-so, do **not** add inline step markers or a function-level numbered overview.

## When to apply

- The user invokes `/annotate` or asks for step-by-step annotation of a specific function or method.
- The user invokes `/say-so` or asks to document **specific behavior** at the top of a file.
- Stay within the **stated file/scope** unless they ask for a broader pass.

## Function walkthrough

1. Read the **full** function, including nested callbacks, transactions, and early returns.
2. Identify the meaningful phases, not every statement. If the method has only one step, provide only a concise overview above it: no numbered list and no inline checkpoint. For multi-step methods, use one short line per ordered step; do not invent phases to meet a step count.
3. For an **exported** method, at the top of the overview block write 1–3 sentences on what the method **does** as part of the larger architecture: its role, who calls it, the effect it uniquely owns, and what neighboring paths do not do. Do not restate the numbered steps or tour callees. Skip this for file-local helpers unless the user asks.
4. Place the overview **immediately above** the function in a block comment — architecture prose first (when required), then the numbered list for multi-step methods:

   ```typescript
   /*
    * Public operator that promotes the owner's base pointer to a registered
    * candidate. The gateway RPC is the caller; this method compares one
    * shared edge, then promotes or invalidates. Background catch-up never
    * promotes; the canonical result always comes from the current base.
    *
    * 1. First phase.
    * 2. Second phase.
    * ...
    */
   export async function myMethod() { ... }
   ```

5. For multi-step methods, mark **checkpoints** inside the body with `// N — …` using the **same numbers** as the overview.
   - Inline text should be **more specific** than the overview line (RPC/table names, branches, what gets written).
   - Format: `// 3 — no rows in batch; skip transaction and cursor write`
   - Place markers at phase starts, early returns, and post-transaction cleanup.
   - Leave an empty line immediately above every inline step marker, including the first marker in a function, callback, branch, or other nested scope. This also applies when the preceding line opens the scope.
   - Do **not** annotate every line.

### Function walkthrough style

- Architectural overview (exported methods): 1–3 sentences in the same block, before step 1 when numbered steps apply answering what this method does in the larger architecture. Role, caller, unique effect, and what it is not — not a tour of callees or a paraphrase of the steps.
- Overview steps: one short imperative line each.
- Inline: same step number plus extra concrete detail — not a bare `// N`.
- Numbers in the overview and inline checkpoints must stay **in sync**.
- Prefer a block comment above the function. Use JSDoc only if the function already uses JSDoc for public API docs.

### Verification

- Exported methods have an architecture overview that says what the method does in the larger architecture.
- One-step methods have only the overview, with no numbered list or inline checkpoint.
- For multi-step methods, every step in the overview appears at least once as an inline checkpoint.
- Every inline step marker has an empty line immediately above it, including at scope starts.
- No logic changes; comments and checkpoint-spacing whitespace only.

## File-top behavior note (say-so)

1. Read the **full file** (or the sections needed to explain the prompted behavior accurately).
2. Distill the user's ask into **1–5 short paragraphs or bullets** — only what they asked for; no tour of unrelated code.
3. Insert a block comment **immediately after** any existing file-level directives that must stay first (`'use client'`, `'use server'`, `"use node"`, shebang, `@ts-nocheck`, license header). Otherwise place it at **line 1**.
4. Use a plain block comment, not JSDoc, unless the file already uses JSDoc for module-level docs.

   ```typescript
   /*
    * [Topic the user asked about]
    *
    * - Concrete behavior, invariant, or boundary.
    * - Why it matters or what breaks if ignored.
    * - Optional: pointer to related module/workflow when non-obvious.
    */
   ```

### File-top style

- Write for a maintainer who already reads the code — precise, not tutorial-length.
- Prefer **behavior and constraints** over restating identifiers line by line.
- If the user gave **exact wording**, use it verbatim for that part.
- If behavior is uncertain or WIP, say so in the comment instead of inventing semantics.
- Keep the header **short**; link to playbook or a sibling file only when it clarifies a cross-cutting rule.

### Verification

- Comment sits at the file top (respecting immovable first-line directives).
- Content matches **only** the behavior the user prompted.
- No logic changes; comments only.