Documentation & Comments Skill

Activate this skill when documenting modules, writing API specifications, authoring READMEs, adding inline code comments, or updating project memory.

Documentation Law: Document the "Why" and non-obvious constraints, never the self-evident "What".

1. Code Comments: Document "Why", Not "What"

• High-Value Comments (Encouraged):
  • Documenting subtle edge cases, workaround for upstream library bugs, concurrency locks, or regulatory/compliance reasons.
  • Explaining complex mathematical algorithms, bitwise tricks, or performance-critical micro-optimizations.
• Low-Value Comments (Forbidden):
  • Restating obvious code (// increment counter by 1, // return user object).
  • Stale comments that no longer match the active code behavior.