Code Documentation

Comprehensive code documentation skill — use this any time documentation is requested, after any significant code change, when onboarding a new subsystem, auditing existing docs for accuracy, or when asked to "document", "update docs", "write docs", or "clean up comments". Covers three tightly coupled concerns: (1) inline file/function headers in source code, (2) subsystem-level .md docs, and (3) global architecture + API reference docs. Always apply this skill — do not improvise documentation standards. Also triggers for requests like "add comments", "document this file", "our docs are out of date", "generate API reference", or after a PR or feature branch is completed.

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.

// src/services/auth/tokenService.js

# 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.

/**
 * 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):

/**
 * 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):

const TIMEOUT = 5000 // 5 seconds

Prohibited — remove on sight:

Pattern	Example	Why banned
Restating the code	// enable proxy above proxy: true	Zero information
Removed/old code notes	// removed legacy handler	Use git for history
Change log comments	// changed to use v2 API	Not a changelog
Section dividers	// ---- helpers ----	Use modules instead
Obvious steps	// loop through users above a users.forEach	Noise

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:

## 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

Concern	Location
File path + module summary	Top of every source file
Function purpose	Top of every non-trivial function
Subsystem deep-dive	/[frontend|backend]/docs/<name>.md
System-wide architecture	/docs/architecture.md
API 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