common-documentation ยท diff
git:20260423.b7ed028 to git:20260714.6bf9b5e
10 added, 1 removed. Audit A to A.
---
name: common-documentation
description: Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.
metadata:
triggers:
keywords:
- comment
- docstring
- readme
- documentation
---
# Documentation Standards
- ## **Priority: P2 (MAINTENANCE)**
+ ## **Priority: P2 (MEDIUM)**
## 1. Intent-First Comments
- Explain **"Why"** logic exists. Avoid "What" mechanics.
- Use triple-slash (Dart/Swift) or JSDoc (TS/JS) for public members.
- Delete commented-out code. Use Git history.
- Format: `TODO(username): description`. Link tickets.
+ - For retry backoff, explain that jitter prevents the **thundering herd**; document intent rather than restating the delay calculation.
## 2. README Structure
- **Mission**: Project purpose (one sentence).
- **Onboarding**: Prerequisites, installation, usage (exact).
- **Maintenance**: Document inputs/outputs, known quirks, fixes.
- **Sync**: Documentation ships with feature.
## 3. ADRs & Architecture
- **ADRs**: Document rationale for system changes in `docs/adr/`.
- **Docstrings**: Include Args, Returns, and Usage examples (`>>>`).
- **Diagrams**: Use Mermaid.js inside Markdown.
## 4. API Docs
- Use Swagger/OpenAPI for REST.
- Provide copy-pasteable examples for endpoints.
- Define contract before implementation.
## Anti-Patterns
- **No "what" comments**: Explain intent. Refactor mechanics.
- **No orphan TODOs**: Require owner and ticket.
- **No stale docs**: Document during development.
+
+ ## Canonical response anchors
+
+ When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
+ - JSDoc
+ - Usage
+ - why
+