Annotate

Annotate

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

Modes

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:

   /*
    * 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.

   /*
    * [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.