/documentation-standards

name: documentation-standards
description: "KB conventions: YAML frontmatter, 10-category taxonomy (reference/howto/procedures/troubleshooting/best-practices/decisions/runbooks/planning/business/templates). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base."
effort: medium
user-invocable: false
allowed-tools: Read

Documentation Standards

Auto-loaded knowledge skill enforcing KB document conventions across all agents and skills.

Frontmatter Specification (MANDATORY)

Every document in `kb/` MUST start with YAML frontmatter:

---
title: "Document Title"                    # REQUIRED — English, descriptive
category: reference                        # REQUIRED — one of the 10 valid categories
service: ai-toolkit                        # REQUIRED — service identifier
tags: [tag1, tag2, tag3]                   # REQUIRED — minimum 1, recommended 3+
last_updated: "YYYY-MM-DD"                 # REQUIRED — ISO format
created: "YYYY-MM-DD"                      # REQUIRED — creation date
description: "One-line summary."           # REQUIRED — for search indexing
version: "1.0.0"                           # optional — semver
---

**All 7 fields above are REQUIRED.** Documents without valid frontmatter **fail `scripts/validate.py` and block CI**.

`section`: a legacy alias, not a second field

Older documents and the `kb-migration` SOP write `section:` where this specification writes `category:`. Both names are read in the wild, so a document may carry both — and when it does **they must hold the same value**. A document filed as `category: reference` and `section: howto` is indexed twice, found once, and the reader gets whichever the index ranked higher.

New documents should write `category:`. `section:` is accepted, never required, and never authoritative on its own.

Category Taxonomy

| Category | Directory | Purpose | Examples | |----------|-----------|---------|----------| | `reference` | `kb/reference/` | Technical specifications, catalogs, architecture notes, API docs | `agents-catalog.md`, `architecture-overview.md` | | `howto` | `kb/howto/` | Step-by-step task guides | `use-corrective-rag.md`, `configure-mcp-server.md` | | `procedures` | `kb/procedures/` | SOPs a person follows: release, migration, review | `sop-maintenance.md`, `sop-release.md` | | `troubleshooting` | `kb/troubleshooting/` | Problem resolution, debugging guides | `database-connection-issues.md` | | `best-practices` | `kb/best-practices/` | Guidelines, recommendations, standards | `security-checklist.md` | | `decisions` | `kb/decisions/` | Architecture decision records and design rationale | `adr-004-kb-migration.md` | | `runbooks` | `kb/runbooks/` | Procedures run against a live system, usually under pressure | `deployment.md`, `incident-response.md` | | `planning` | `kb/planning/` | Roadmaps, PRDs, work not yet done | `q3-roadmap.md` | | `business` | `kb/business/` | Domain model, requirements, use cases, user stories | `domain-model.md`, `user-stories.md` | | `templates` | `kb/templates/` | Reusable document templates | `adr-template.md`, `sop-template.md` |

**Rule:** A document filed under one of the directories above MUST declare that category. The rule is scoped to those directories deliberately: `kb/history/` and `kb/summaries/` are lifecycle and runtime locations rather than types, and a finished plan filed under `history/completed/` is still a `planning` document.

**Templates carry placeholders on purpose.** A file under `templates/` exists to be copied, so a literal `YYYY-MM-DD` date and `[placeholder]` body text are correct there rather than defects. Every other convention still applies.

This taxonomy lives in three places: ai-toolkit's `scripts/validate.py`, rag-mcp's `scripts/validate_kb_frontmatter.py`, and this document. They are one list, and a change belongs in all three.

Naming Conventions

• **Filename:** kebab-case, descriptive, no dates (`merge-friendly-install-model.md`)
• **Title:** English, clear, matches filename semantics
• **No prefixes:** no `001-`, no `YYYY-MM-DD-` in filenames (dates go in frontmatter)
• **Max length:** keep filenames under 60 characters

Language Rule

**All KB content MUST be in English.** No exceptions for:

• Document titles
• Body content
• Code comments within docs
• Table headers and descriptions

Quality Standards

Required for every KB document:

• [ ] Valid YAML frontmatter with all 7 required fields
• [ ] Category matches directory
• [ ] Written in English
• [ ] Title is clear and descriptive
• [ ] Content is actionable (not just placeholders)

Required for procedural docs (howto, procedures):

• [ ] Prerequisites listed
• [ ] Steps are numbered
• [ ] Commands are copy-pasteable
• [ ] Verification section present

Required for troubleshooting docs:

• [ ] Symptoms described
• [ ] Root cause identified
• [ ] Resolution steps provided
• [ ] Prevention notes included

Templates

Reference Document

---
title: "AI Toolkit - [Topic]"
category: reference
service: ai-toolkit
tags: [topic, subtopic]
version: "1.0.0"
created: "YYYY-MM-DD"
last_updated: "YYYY-MM-DD"
description: "Brief summary."
---

# [Topic]

## Overview
[What this document covers]

## Details
[Technical content]

## Related
- [Other relevant KB docs]

How-To Guide

---
title: "How to [Task]"
category: howto
service: ai-toolkit
tags: [howto, task-name]
created: "YYYY-MM-DD"
last_updated: "YYYY-MM-DD"
description: "Step-by-step guide for [task]."
---

# How to [Task]

## Prerequisites
- [Requirement]

## Steps

### 1. [Action]
[Instructions + commands]

### 2. [Action]
[Instructions + commands]

## Verification
[How to confirm success]

## Troubleshooting
| Problem | Solution |
|---------|----------|
| [Error] | [Fix]    |

SOP / Procedure

---
title: "SOP: [Process Name]"
category: procedures
service: ai-toolkit
tags: [sop, process-name]
created: "YYYY-MM-DD"
last_updated: "YYYY-MM-DD"
descripti