---

name: annotations description: Annotation and documentation protocol for rapid-iteration projects (“vibe coding”). Enforces Google Docstring Style plus comment-as-contract: consistency with signatures/types, explicit pre/post-conditions, units/frames/conventions, and rich implementation comments. Use Notes with ASCII + pseudocode for complex algorithms.

Annotations (Google Docstring + Comment-as-Contract)

Core Principles

1. Google Docstring Style (primary)

   • Use Google-style sections: Args, Returns, Raises, Attributes, Notes, Examples
   • Docstrings must describe semantics and contracts, not restate names

2. Comment-as-Contract Document anything that can break silently:

   • Pre/post-conditions: ranges, shapes, dtype/device, required keys, ordering
   • Units and conventions: units, angle conventions, coordinate frames, axis order, quaternion convention, normalization
   • Determinism & randomness: seeds, sampling behavior, stochastic branches
   • Failure modes: when exceptions raised, undefined behavior, NaN/overflow hazards

3. Signature/type info and docs must agree

   • Signature + type hints are source of truth
   • Docs must not contradict; use prose for constraints types can't express

4. Implementation comments required

   • Dense, local explanations near the code they justify
   • Optimize for "future you" to modify safely without re-deriving intent

What Must Be Documented

Functions / Methods

• One-line summary (imperative mood)
• Args for every parameter (meaning + constraints)
• Returns for every return value (meaning + shape/unit/convention)
• Raises for intentional or common failures
• Notes if algorithm is non-trivial, involves math/geometry, has subtle invariants, or has performance/stability considerations

Classes / Components

• One-line summary + role in system
• Attributes documenting state, units/conventions, lifecycle (created/reset/updated)
• Public methods with side effects and invariants

Config / Schema / CLI

• Each field/flag meaning, default rationale (if non-obvious), units, valid range
• Cross-field constraints (e.g., min <= max, mutually exclusive flags)

Implementation Comments (inside code)

Required when code contains:

• non-obvious transforms or conventions
• branching logic encoding a design choice
• "magic numbers" (thresholds, scalings, epsilons)
• performance hacks (vectorization, caching, preallocation)
• "temporary" logic you might forget to remove

Guidelines: Comments answer why + what invariant (not narrating obvious operations)

Templates and Examples

See resource files for detailed templates and Python/IsaacLab examples:

• Templates - Function, Class, Config templates
• Examples - Python + IsaacLab code examples

Review Checklist

• Docstrings/comments match signature + type hints
• Constraints documented for non-obvious inputs (range/shape/unit/frame/convention)
• Frames/units/conventions stated wherever transforms occur
• Magic constants justified or replaced by named constants with rationale
• Notes exists for complex algorithms and includes pseudocode
• Implementation comments explain why and invariants, not trivial steps
• Documentation updated after refactors (no drift)

Anti-Patterns

❌ Docstrings only restate names without semantics
❌ Missing units/frames/conventions where misinterpretation is likely
❌ Comments narrating obvious operations rather than intent
❌ Silent assumptions (deg vs rad, axis order, quaternion convention) left undocumented
❌ Docstrings drifting after signature changes