documentation-standards

# Documentation Standards **Purpose**: Defines the non-negotiable standards for code comments, docstrings, and global artifacts. ## 1. Red Flags (Anti-Rationalization) **STOP if you are thinking:** - "I'll add comments later" -> **WRONG**. Undocumented code is technical debt from the moment it is written. - "The code is self-documenting" -> **WRONG**. Code explains *how*; comments explain *why*. - "Artifacts are optional, I can skip them entirely" -> **WRONG**. Artifacts are part of delivery quality; `.AGENTS.md` must follow project memory policy. ## 2. Docstrings & JSDoc All classes and functions MUST have documentation. ### Python Use Google-style docstrings. > [!TIP] > See `assets/templates/python_docstring.py` for the format. ### JavaScript / TypeScript Use JSDoc standards. > [!TIP] > See `assets/templates/jsdoc_template.ts` for the format. ## 3. Comments - **Why vs What**: Explain the *reason* for logic, not the syntax. - **Work Tracking**: Use `# T O D O:` (Python) or `// T O D O:` (JS/TS) for future work. ## 4. Path Standards (CRITICAL) - **Relative Paths Only**: When linking to internal files in Artifacts (PLAN.md, TASK.md), ALWAYS use relative paths. - ✅ `[Ref](src/main.py)` - ✅ `[.agent/skills/core.md](.agent/skills/core.md)` - ❌ `file:///Users/username/project/src/main.py` - ❌ `/Absolute/System/Path` ## 5. Artifacts (`.AGENTS.md`) Policy: keep `.AGENTS.md` for source-code directories under memory tracking. Missing file should not fail execut...