# Documentation Templates > Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation. Use when this capability is needed. - Skill: `tomevault-io/documentation-templates-5` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/documentation-templates-5` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-templates-5/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/documentation-templates-5 --- ## Hallucination Traps (Read First) - ❌ Writing documentation that only AI-generated code can understand -> ✅ Docs are for HUMANS; use clear language and real examples - ❌ Documenting implementation details instead of behavior -> ✅ Document WHAT it does and WHY, not HOW (code shows how) - ❌ Skipping the 'Quick Start' section -> ✅ The first 30 seconds of a README determine if someone uses your project --- # Documentation Standards --- ## Documentation Types and Their Audiences |Type|Audience|Goal| |---|---|---| |README|New developer joining the project|"Get me running in 10 minutes"| |API docs|External integrator or frontend dev|"Tell me exactly what I can call and what I'll get back"| |Architecture decision (ADR)|Future engineer inheriting the codebase|"Tell me why it works this way, not just how"| |Code comment|Reviewer, maintainer|"Explain the non-obvious; skip the obvious"| |Runbook|On-call engineer at 2am|"Tell me what to do, not what to think about"| --- ## Skill Pattern Inheritance The Tribunal Agent Kit supports 5 standard Agent Design Kit (ADK) base patterns. To build a skill using a robust, tested agent behavior model, add `pattern: [pattern-name]` to the YAML frontmatter of your `SKILL.md`. |Pattern|Value|When to use| |---|---|---| |**Inversion**|`pattern: inversion`|Forces the agent to interview the user (Socratic Gate) before acting.| |**Reviewer**|`pattern: reviewer`|Evaluates artifacts against a checklist and severity levels.| |**Tool Wrapper**|`pattern: tool-wrapper`|Strictly executes external CLI tools via provided documentation without guessing.| |**Generator**|`pattern: generator`|Produces structured output (docs, boilerplate) by filling a rigid template.| |**Pipeline**|`pattern: pipeline`|Executes sequential tasks with strict halting gates between steps.| *Templates defining the specific rules for these patterns live in `.agent/patterns/`.* --- ## README Template ```markdown # Project Name One sentence: what this is and what problem it solves. ## Quick Start \`\`\`bash git clone ... cd project npm install cp .env.example .env npm run dev \`\`\` Open http://localhost:3000 ## Requirements - Node.js 20+ - PostgreSQL 15+ - [Any other hard requirements] ## Project Structure \`\`\` src/ api/ API routes lib/ Shared utilities services/ Business logic \`\`\` ## Environment Variables |Variable|Required|Description| |---|---|---| |DATABASE_URL|Yes|PostgreSQL connection string| |JWT_SECRET|Yes|Secret for signing JWTs| ## Running Tests \`\`\`bash npm test # unit tests npm run test:e2e # end-to-end tests \`\`\` ## Contributing [Brief contribution guide or link to CONTRIBUTING.md] ``` --- ## API Documentation Standards For each endpoint, document: ```markdown ### POST /api/users Creates a new user account. **Request Body** \`\`\`json { "email": "string (required, valid email)", "name": "string (required, 2–100 chars)", "role": "admin | user (optional, default: user)" } \`\`\` **Responses** |Status|Meaning|Body| |---|---|---| |201|User created|`{ data: User }`| |400|Validation failed|`{ error: string, details: string[] }`| |409|Email already exists|`{ error: string }`| **Example** \`\`\`bash curl -X POST /api/users \ -H "Content-Type: application/json" \ -d '{"email": "user@example.com", "name": "Jane"}' \`\`\` ``` --- ## Code Comment Rules **Comment the why, not the what:** ```ts // ❌ States what the code does (obvious from reading it) // Multiply price by tax rate const total = price * taxRate; // ✅ Explains why this specific value exists // Vietnamese tax law requires 10% VAT on all digital goods (Circular 92/2015) const VN_DIGITAL_TAX_RATE = 1.10; const total = price * VN_DIGITAL_TAX_RATE; ``` **When to always comment:** - Non-obvious business rules - Workarounds for external library bugs (with issue link if possible) - Performance decisions that look like premature optimization but aren't - Magic numbers and why they have that value --- ## AI-Friendly Documentation When a codebase will be worked on by AI assistants: - Keep a `CODEBASE.md` at root with: tech stack, folder structure, key conventions - Add a `ARCHITECTURE.md` with: system boundaries, data flow, key decisions - Add `// @purpose:` comments on complex functions so AI can understand intent without reading the full implementation - Document which files are auto-generated and should not be edited directly --- ## Runbook Template ```markdown # Runbook: [Service or Incident Type] ## Symptoms - [What the user or monitor reports] ## Likely Causes 1. [Most common cause] 2. [Second most common] ## Investigation Steps \`\`\`bash # Check service health kubectl get pods -n production # Check recent errors kubectl logs deployment/api --since=15m | grep ERROR \`\`\` ## Resolution Steps ### If Cause 1: [Exact steps to resolve] ### If Cause 2: [Exact steps to resolve] ## Escalation If unresolved after 30 minutes → page @on-call-lead ## Post-Incident [ ] Write incident report [ ] Add monitoring for this failure mode [ ] Update this runbook if steps changed ``` --- ## Output Format When this skill completes a task, structure your output as: ``` ━━━ Documentation Templates Output ━━━━━━━━━━━━━━━━━━━━━━━━ Task: [what was performed] Result: [outcome summary — one line] ───────────────────────────────────────────────── Checks: ✅ [N passed] · ⚠️ [N warnings] · ❌ [N blocked] VBC status: PENDING → VERIFIED Evidence: [link to terminal output, test result, or file diff] ``` --- --- AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden: 1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices. 2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`. 3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation. 4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions. 5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising. --- **Slash command: `/review` or `/tribunal-full`** **Active reviewers: `logic-reviewer` · `security-auditor`** ### ❌ Forbidden AI Tropes 1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`. 2. **Silent Degradation:** Catching and suppressing errors without logging or handling. 3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions. Review these questions before confirming output: ``` ✅ Did I rely ONLY on real, verified tools and methods? ✅ Is this solution appropriately scoped to the user's constraints? ✅ Did I handle potential failure modes and edge cases? ✅ Have I avoided generic boilerplate that doesn't add value? ``` ### 🛑 Verification-Before-Completion (VBC) Protocol **CRITICAL:** You must follow a strict "evidence-based closeout" state machine. - ❌ **Forbidden:** Declaring a task complete because the output "looks correct." - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended. ## Pre-Flight Checklist - [ ] Have I reviewed the user's specific constraints and requests? - [ ] Have I checked the environment for relevant existing implementations? ## VBC Protocol (Verification-Before-Completion) You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted. --- ## 🤖 LLM-Specific Traps AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden: 1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices. 2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`. 3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation. 4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions. 5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising. --- ## 🏛️ Tribunal Integration (Anti-Hallucination) **Slash command: `/review` or `/tribunal-full`** **Active reviewers: `logic-reviewer` · `security-auditor`** ### ❌ Forbidden AI Tropes 1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`. 2. **Silent Degradation:** Catching and suppressing errors without logging or handling. 3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions. ### ✅ Pre-Flight Self-Audit Review these questions before confirming output: ``` ✅ Did I rely ONLY on real, verified tools and methods? ✅ Is this solution appropriately scoped to the user's constraints? ✅ Did I handle potential failure modes and edge cases? ✅ Have I avoided generic boilerplate that doesn't add value? ``` ### 🛑 Verification-Before-Completion (VBC) Protocol **CRITICAL:** You must follow a strict "evidence-based closeout" state machine. - ❌ **Forbidden:** Declaring a task complete because the output "looks correct." - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended. --- > Source: [Harmitx7/tribunal-kit](https://github.com/Harmitx7/tribunal-kit) — distributed by [TomeVault](https://tomevault.io).