Code Documentation Skill#

Purpose#

This skill governs how code is documented at every level — from individual file headers to global architecture docs. Apply it consistently across all projects. When in doubt: document the why, not the what. The code already says what it does.

---

Phase 0 — Before You Write Anything#

1. Scan the repo structure. Understand what exists before touching anything.
2. Identify subsystems. Group files by domain (Auth, Billing, API Layer, etc.).
3. Read existing docs first. Check /docs/ in both frontend and backend. Note what's present, missing, or stale.
4. Confirm the active branch. Never document against stale or wrong code.

---

Phase 1 — Source File Standards#

Apply to every file that is ≥ 20 lines OR is imported by other modules.

1.1 — Line 1: Full Path Comment#

The very first line of every source file must be a comment containing the file's full path from the project root. Use the comment syntax appropriate to the language.

js

// src/services/auth/tokenService.js

py

# src/services/auth/token_service.py

1.2 — File Header Block (lines 2–N)#

Immediately after the path comment, add a header block. Use the language's block comment syntax. This block is mandatory and must be kept accurate.

text

/**
 * File: src/services/auth/tokenService.js
 *
 * Overview:
 *   Issues, validates, and refreshes JWT tokens for authenticated sessions.
 *   Exists to centralise all token logic so Auth routes stay thin.
 *
 * Exports:
 *   - issueToken(userId, role) → signed JWT string
 *   - verifyToken(token) → decoded payload or throws
 *   - refreshToken(oldToken) → new signed JWT string
 *
 * Imported By:
 *   - src/routes/auth.js
 *   - src/middleware/requireAuth.js
 *
 * Imports:
 *   - jsonwebtoken  — signing/verification
 *   - config/env    — JWT_SECRET, TOKEN_TTL
 *
 * Notes:
 *   - Tokens expire in 15 min; refresh window is 7 days.
 *   - verifyToken throws on expiry — callers must handle.
 */

Rules:

• Keep it current. If you add an export, update Exports. If a new file imports this, update Imported By.
• Do not pad with boilerplate. Every line must be accurate and useful.

1.3 — Function Headers#

Top of every non-trivial function (any function with logic beyond a single expression):

js

/**
 * Signs a new JWT for the given user. Embeds userId and role in payload.
 * Throws if JWT_SECRET is not set in env.
 */
function issueToken(userId, role) { ... }

Rules:

• Max 2 sentences.
• Explain why the function exists or what makes it non-obvious, not just what it does.
• No parameter/return type breakdown unless the types are genuinely surprising.

1.4 — Inline Comment Rules#

Allowed (rare exceptions only):

js

const TIMEOUT = 5000 // 5 seconds

Prohibited — remove on sight:

PatternExampleWhy bannedRestating the code// enable proxy above proxy: trueZero informationRemoved/old code notes// removed legacy handlerUse git for historyChange log comments// changed to use v2 APINot a changelogSection dividers// ---- helpers ----Use modules insteadObvious steps// loop through users above a users.forEachNoise

If you encounter these, delete them. They are clutter that erodes trust in real comments.

---

Phase 2 — Subsystem Documentation#

See references/subsystem-doc.md for the full template and field-by-field instructions.

One .md file per subsystem, located at:

• /backend/docs/<subsystem>.md
• /frontend/docs/<subsystem>.md

Subsystem identification heuristics:

• A cohesive domain handled by a directory or cluster of files
• Examples: auth, billing, search, notifications, api-layer, data-layer, file-upload, websockets, admin, onboarding

Discovery checklist — identify a subsystem when you find:

• A directory with 3+ related files
• A shared service/utility used by 3+ other files
• A distinct API surface (routes/controllers grouped by concern)
• A background job or scheduled process
• A third-party integration (Stripe, S3, Twilio, etc.)

If a subsystem doc already exists:

• Compare it against current code
• Remove anything describing code that no longer exists
• Add anything the doc misses
• Update all file maps, function names, and flow diagrams

---

Phase 3 — Global Architecture Document#

Location: /docs/architecture.md (or /backend/docs/architecture.md depending on repo layout)

See references/architecture-doc.md for the full template.

Required sections:

1. System Overview — what this product does in 2–3 sentences
2. Subsystems — bulleted list, one-liner per subsystem, link to its .md
3. High-Level Diagram — ASCII or Mermaid, showing subsystem relationships
4. Tech Stack — language, framework, DB, cache, queue, infra
5. Cross-Cutting Concerns — how auth, error handling, validation, config, logging, and testing work across the system (not per-subsystem)

---

Phase 4 — API Reference#

Required if a backend exists. Location: /backend/docs/api.md

For large backends: one file per subsystem, e.g. /backend/docs/api-auth.md, /backend/docs/api-billing.md, then an index in /backend/docs/api.md.

See references/api-reference.md for the full endpoint template.

Every endpoint must document:

• Method + path
• Description (1 sentence — what this does for the caller)
• Request: path params, query params, body schema
• Response: success schema + status codes + error codes
• Source mapping: which controller file and service methods handle it

---

Phase 5 — Validation Pass#

After writing or updating docs, audit them:

text

## Documentation Audit

### Missing
- List any subsystem without a doc

### Outdated
- List any doc that references removed files, functions, or endpoints

### Incorrect
- List any wrong dependency, wrong export name, wrong flow description

### Recommendations
- Specific fixes with file locations

Do not skip this pass. Stale documentation is worse than none — it actively misleads.

---

Enforcement Rules#

These apply any time you touch code:

1. Changed a function's logic? → Update its header.
2. Added or removed an export? → Update the file header's Exports section.
3. Added a new file that others import? → Add the file header; update importers' "Imported By" lists if practical.
4. Added or changed an API endpoint? → Update api.md.
5. Structural change to a subsystem? → Update that subsystem's .md.
6. Added a new subsystem? → Create its .md from the template in references/subsystem-doc.md.
7. Removed a file or feature? → Find every doc that mentions it and remove those references.

Never leave documentation in a state that describes code that doesn't exist.

---

Quick Reference: What Goes Where#

ConcernLocationFile path + module summaryTop of every source fileFunction purposeTop of every non-trivial functionSubsystem deep-dive/[frontend|backend]/docs/<name>.mdSystem-wide architecture/docs/architecture.mdAPI contracts/backend/docs/api.md (or per-subsystem)

---

Reference Files#

• references/subsystem-doc.md — Full subsystem doc template + instructions
• references/architecture-doc.md — Full architecture.md template
• references/api-reference.md — Full API endpoint documentation template