documentation-templates

name	documentation-templates
description	Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
allowed-tools	Read, Write, Edit, Glob, Grep
version	1.0.0
last-updated	"2026-03-12T00:00:00.000Z"
applies-to-model	gemini-2.5-pro, claude-3-7-sonnet
routing	{"domain":"general","tier":"basic"}

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

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

### 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": "[e-mail]", "name": "Jane"}'
\`\`\`

---

Code Comment Rules

Comment the why, not the what:

// ❌ 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.1;
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

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