{"skill":{"slug":"code-documentation","displayName":"Code Documentation","summary":"Comprehensive code documentation skill — use this any time documentation is requested, after any significant code change, when onboarding a new subsystem, au...","description":"---\nname: code-documentation\ndescription: >\n  Comprehensive code documentation skill — use this any time documentation is requested, after\n  any significant code change, when onboarding a new subsystem, auditing existing docs for accuracy,\n  or when asked to \"document\", \"update docs\", \"write docs\", or \"clean up comments\". Covers three\n  tightly coupled concerns: (1) inline file/function headers in source code, (2) subsystem-level\n  .md docs, and (3) global architecture + API reference docs. Always apply this skill — do not\n  improvise documentation standards. Also triggers for requests like \"add comments\", \"document\n  this file\", \"our docs are out of date\", \"generate API reference\", or after a PR or feature branch\n  is completed.\n---\n\n# Code Documentation Skill\n\n## Purpose\n\nThis skill governs how code is documented at every level — from individual file headers to\nglobal architecture docs. Apply it consistently across all projects. When in doubt: document\nthe *why*, not the *what*. The code already says what it does.\n\n---\n\n## Phase 0 — Before You Write Anything\n\n1. **Scan the repo structure.** Understand what exists before touching anything.\n2. **Identify subsystems.** Group files by domain (Auth, Billing, API Layer, etc.).\n3. **Read existing docs first.** Check `/docs/` in both frontend and backend. Note what's\n   present, missing, or stale.\n4. **Confirm the active branch.** Never document against stale or wrong code.\n\n---\n\n## Phase 1 — Source File Standards\n\nApply to every file that is ≥ 20 lines OR is imported by other modules.\n\n### 1.1 — Line 1: Full Path Comment\n\nThe very first line of every source file must be a comment containing the file's full path\nfrom the project root. Use the comment syntax appropriate to the language.\n\n```js\n// src/services/auth/tokenService.js\n```\n```py\n# src/services/auth/token_service.py\n```\n\n### 1.2 — File Header Block (lines 2–N)\n\nImmediately after the path comment, add a header block. Use the language's block comment\nsyntax. This block is mandatory and must be kept accurate.\n\n```\n/**\n * File: src/services/auth/tokenService.js\n *\n * Overview:\n *   Issues, validates, and refreshes JWT tokens for authenticated sessions.\n *   Exists to centralise all token logic so Auth routes stay thin.\n *\n * Exports:\n *   - issueToken(userId, role) → signed JWT string\n *   - verifyToken(token) → decoded payload or throws\n *   - refreshToken(oldToken) → new signed JWT string\n *\n * Imported By:\n *   - src/routes/auth.js\n *   - src/middleware/requireAuth.js\n *\n * Imports:\n *   - jsonwebtoken  — signing/verification\n *   - config/env    — JWT_SECRET, TOKEN_TTL\n *\n * Notes:\n *   - Tokens expire in 15 min; refresh window is 7 days.\n *   - verifyToken throws on expiry — callers must handle.\n */\n```\n\n**Rules:**\n- Keep it current. If you add an export, update Exports. If a new file imports this, update\n  Imported By.\n- Do not pad with boilerplate. Every line must be accurate and useful.\n\n### 1.3 — Function Headers\n\nTop of every non-trivial function (any function with logic beyond a single expression):\n\n```js\n/**\n * Signs a new JWT for the given user. Embeds userId and role in payload.\n * Throws if JWT_SECRET is not set in env.\n */\nfunction issueToken(userId, role) { ... }\n```\n\n**Rules:**\n- Max 2 sentences.\n- Explain *why* the function exists or what makes it non-obvious, not just what it does.\n- No parameter/return type breakdown unless the types are genuinely surprising.\n\n### 1.4 — Inline Comment Rules\n\n**Allowed (rare exceptions only):**\n```js\nconst TIMEOUT = 5000 // 5 seconds\n```\n\n**Prohibited — remove on sight:**\n\n| Pattern | Example | Why banned |\n|---|---|---|\n| Restating the code | `// enable proxy` above `proxy: true` | Zero information |\n| Removed/old code notes | `// removed legacy handler` | Use git for history |\n| Change log comments | `// changed to use v2 API` | Not a changelog |\n| Section dividers | `// ---- helpers ----` | Use modules instead |\n| Obvious steps | `// loop through users` above a users.forEach | Noise |\n\nIf you encounter these, **delete them**. They are clutter that erodes trust in real comments.\n\n---\n\n## Phase 2 — Subsystem Documentation\n\nSee `references/subsystem-doc.md` for the full template and field-by-field instructions.\n\n**One `.md` file per subsystem, located at:**\n- `/backend/docs/<subsystem>.md`\n- `/frontend/docs/<subsystem>.md`\n\n**Subsystem identification heuristics:**\n- A cohesive domain handled by a directory or cluster of files\n- Examples: `auth`, `billing`, `search`, `notifications`, `api-layer`, `data-layer`,\n  `file-upload`, `websockets`, `admin`, `onboarding`\n\n**Discovery checklist — identify a subsystem when you find:**\n- [ ] A directory with 3+ related files\n- [ ] A shared service/utility used by 3+ other files\n- [ ] A distinct API surface (routes/controllers grouped by concern)\n- [ ] A background job or scheduled process\n- [ ] A third-party integration (Stripe, S3, Twilio, etc.)\n\n**If a subsystem doc already exists:**\n- Compare it against current code\n- Remove anything describing code that no longer exists\n- Add anything the doc misses\n- Update all file maps, function names, and flow diagrams\n\n---\n\n## Phase 3 — Global Architecture Document\n\nLocation: `/docs/architecture.md` (or `/backend/docs/architecture.md` depending on repo layout)\n\nSee `references/architecture-doc.md` for the full template.\n\nRequired sections:\n1. System Overview — what this product does in 2–3 sentences\n2. Subsystems — bulleted list, one-liner per subsystem, link to its `.md`\n3. High-Level Diagram — ASCII or Mermaid, showing subsystem relationships\n4. Tech Stack — language, framework, DB, cache, queue, infra\n5. Cross-Cutting Concerns — how auth, error handling, validation, config, logging, and\n   testing work *across* the system (not per-subsystem)\n\n---\n\n## Phase 4 — API Reference\n\n**Required if a backend exists.** Location: `/backend/docs/api.md`\n\nFor large backends: one file per subsystem, e.g. `/backend/docs/api-auth.md`,\n`/backend/docs/api-billing.md`, then an index in `/backend/docs/api.md`.\n\nSee `references/api-reference.md` for the full endpoint template.\n\nEvery endpoint must document:\n- Method + path\n- Description (1 sentence — what this does for the caller)\n- Request: path params, query params, body schema\n- Response: success schema + status codes + error codes\n- Source mapping: which controller file and service methods handle it\n\n---\n\n## Phase 5 — Validation Pass\n\nAfter writing or updating docs, audit them:\n\n```\n## Documentation Audit\n\n### Missing\n- List any subsystem without a doc\n\n### Outdated\n- List any doc that references removed files, functions, or endpoints\n\n### Incorrect\n- List any wrong dependency, wrong export name, wrong flow description\n\n### Recommendations\n- Specific fixes with file locations\n```\n\nDo not skip this pass. Stale documentation is worse than none — it actively misleads.\n\n---\n\n## Enforcement Rules\n\nThese apply any time you touch code:\n\n1. **Changed a function's logic?** → Update its header.\n2. **Added or removed an export?** → Update the file header's Exports section.\n3. **Added a new file that others import?** → Add the file header; update importers'\n   \"Imported By\" lists if practical.\n4. **Added or changed an API endpoint?** → Update `api.md`.\n5. **Structural change to a subsystem?** → Update that subsystem's `.md`.\n6. **Added a new subsystem?** → Create its `.md` from the template in\n   `references/subsystem-doc.md`.\n7. **Removed a file or feature?** → Find every doc that mentions it and remove those\n   references.\n\n**Never leave documentation in a state that describes code that doesn't exist.**\n\n---\n\n## Quick Reference: What Goes Where\n\n| Concern | Location |\n|---|---|\n| File path + module summary | Top of every source file |\n| Function purpose | Top of every non-trivial function |\n| Subsystem deep-dive | `/[frontend\\|backend]/docs/<name>.md` |\n| System-wide architecture | `/docs/architecture.md` |\n| API contracts | `/backend/docs/api.md` (or per-subsystem) |\n\n---\n\n## Reference Files\n\n- `references/subsystem-doc.md` — Full subsystem doc template + instructions\n- `references/architecture-doc.md` — Full architecture.md template\n- `references/api-reference.md` — Full API endpoint documentation template\n","topics":["Documentation","Source Code","Docs","Document"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":443,"installsAllTime":16,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1778090864309,"updatedAt":1778492864292},"latestVersion":{"version":"1.0.0","createdAt":1778090864309,"changelog":"Initial release of the code-documentation skill, standardizing comprehensive documentation practices.\n\n** Code documentation makes it so humans can ramp up on the code faster and makes ti so Agentic AI can really hit the ground running, working with your code. Leveraging this skill will make your Agentic coders noticably better!\n\n- Defines strict templates and enforcement rules for in-code file/function headers, subsystem-level docs, and architecture/API references.\n- Outlines when and how documentation must be updated after every significant code change.\n- Details prohibited inline comment patterns and mandates accurate, purposeful documentation over boilerplate.\n- Provides audit/validation steps to catch missing, outdated, or incorrect docs.\n- Includes quick reference tables to clarify responsibilities and doc locations.","license":"MIT-0"},"metadata":null,"owner":{"handle":"encryptshawn","userId":"s17acjjwshpqj4xkbngejj57nx83zbcy","displayName":"EncryptShawn","image":"https://avatars.githubusercontent.com/u/56897824?v=4"},"moderation":null}