Documentation Skill

Version: 1.0 Source: Documentation Standards

Non-negotiable documentation standards. Documentation ships with code, not after it.

Core Principles

• Documentation Ships with Code — Every feature includes updated documentation

• Single Source of Truth — /Documentation folder is THE reference

• Agent Continuity — Documentation enables agents to understand context

• Living Documents — Keep documentation current, not stale

The Documentation Feedback Loop

Agent reads /Documentation → Understands context → Does work → Updates /Documentation → Next agent reads

When you update /Documentation , you're helping the next agent (including future you) understand the project.

Semantic Versioning (SemVer)

Format

MAJOR.MINOR.PATCH

Type When to Bump Examples

MAJOR Breaking change to behavior, inputs, outputs, or structure API contract changes, removed features, renamed files

MINOR New user-visible capability or workflow New feature, new endpoint, new command

PATCH Bug fixes, small improvements, no new capability Fix typo, improve performance, formatting

Release Naming Convention

vX.Y.Z — [Program] / [Module]: [Feature]

Component Type Description

Program Noun Major domain (e.g., Kitchen, Garden)

Module Noun-phrase Capability area (e.g., Planning, Tasks)

Feature Verb/Noun-phrase Specific action (e.g., Create meal plan)

Examples:

• v0.2.0 — Kitchen / Planning: Create weekly meal plan

• v0.3.0 — Garden / Tasks: Track watering routine

• v0.4.1 — Kitchen / Planning: Fix missing quantities

Scope Tags (Machine-Friendly)

scope: program.module.feature

Examples:

• scope: kitchen.planning.generate-shopping-list

• scope: garden.tasks.track-watering-routine

Compatibility Rules

MAJOR bump when ANY of these change in a breaking way:

• File/folder paths or naming conventions

• Required inputs or workflow order

• Output contract (required sections, templates)

MINOR bump when:

• New workflow outcome added

• Module gains end-to-end feature

• Docs gain new non-breaking sections

PATCH bump when:

• Bug fixes, formatting, typos

• Performance improvements without contract change

Folder Structure

/Documentation/ project-roadmap.md # Living plan + progress tracking architecture.md # System design overview changelog.md # Version history (Keep a Changelog) features/ [program-name]/ [module-name]/ _[module-name].md # Module explainer (underscore sorts first) feature-name-1.md # Feature specification feature-name-2.md # Feature specification

Key Files

File Purpose

project-roadmap.md

Strategic roadmap (v0.1 → v1.0), milestones

architecture.md

System design, data flow, key components

changelog.md

Version history (Keep a Changelog format)

_*.md (module) Module overview, features list, dependencies

*.md (feature) User story, acceptance criteria, tech notes

Root README

The README is a bridge, not a brochure. Its job is to take someone from "what is this?" to "I have it running and understand how to use it." If a reader follows the README top to bottom and can't get the project working, the README failed — not the reader.

Two Audiences, One Document

• "Just run it" readers — Want a working state in 5 minutes. They'll read Title, Quick Start, and Setup.

• "Understand it" readers — Want to know why things work. They still want Quick Start first — understanding is easier once you've seen the thing running.

The section order below serves both. Skim readers exit early with a working result. Deep readers continue into structure and configuration.

Section Order

Section Purpose

1 Title + One-Liner "Is this relevant to me?" in 10 seconds

2 Quick Start First success in ≤5 minutes

3 What This Does / Doesn't Set correct expectations

4 Prerequisites Honest dependency list

5 Setup Full environment setup with validation

6 Usage Core workflows with real examples

7 Project Structure Where things live and why

8 Configuration What's customizable and how

9 Troubleshooting Common failures + fixes

10 Contributing How to help, where to start

Why this order: Sections 1–2 are engagement gates (fail here and the reader leaves). Sections 3–5 are foundation (skip these and the reader gets lost later). Sections 6–8 are reference (dip in and out as needed). Sections 9–10 are safety nets (when things go wrong or someone wants to contribute).

Key Principles

• Success Horizons — Every instruction ends with what the reader should see. npm run db:migrate alone is incomplete. Add: You should see: Migrations complete. 12 tables created.

• Honest Prerequisites — List exact versions with check commands. Hidden requirements become support tickets.

• Concrete Over Abstract — Use the project's actual names and paths, not {placeholder} patterns.

• Jargon Translation — If a term would make someone stop and Google, translate it immediately.

• Failure Modes — Document common failures inline (> If you see [error]: [cause]. Fix: [what to do] ), catch the rest in Troubleshooting.

• Scannable Structure — Headers, code blocks, tables, short paragraphs. Never walls of text.

Full guide: references/readme-guide.md — Section-by-section details with Good/Bad examples and anti-patterns Template: assets/readme-template.md — Copy-paste starter with all 10 sections

Feature Specifications

Required Elements

Every feature file MUST include:

• One-line description

• Module reference and status

• User story (As a / I want / So that)

• Overview and basic scenario

• Acceptance criteria (testable checkboxes)

• Data model (if applicable)

• Technical notes with Standards Checklist

• Open questions

• Related features

Use the template at assets/feature-template.md . Every feature file must include: one-line description, module reference + status, user story (As/Want/So), overview with basic scenario, testable acceptance criteria, data model (if applicable), technical notes with standards checklist, open questions, and related features.

Module Explainers

Use the template at assets/module-template.md . Each module explainer includes: one-line description, program reference + status count, overview, feature table (with status + links), dependencies, and architecture notes.

Changelog Format

Follow Keep a Changelog format. Use the template at assets/changelog-template.md .

Change Types

Type Description

Added New features

Changed Changes in existing functionality

Deprecated Soon-to-be removed features

Removed Now removed features

Fixed Bug fixes

Security Vulnerability fixes

Status Formats

Context Format Values

project-roadmap.md

Emoji ⏳ Planned, 🔄 In Progress, ✅ Complete, 🚫 Blocked

Feature/Module files Text Planned, In Progress, Complete

Open questions Text Open, Resolved

Rationale: Emoji in roadmap for visual scanning. Text in feature files for AI parsing.

Documentation Checklist

Before considering documentation complete:

Feature Files

• One-line description present

• Status is current and accurate

• User story follows As/Want/So format

• Acceptance criteria are testable checkboxes

• Standards checklist is complete

• Open questions addressed or documented

Module Explainers

• Feature table is current

• Status counts are accurate

• Dependencies listed

Project-Level

• Roadmap reflects current state

• Changelog updated for release

• Architecture doc current

References

• references/semver-guide.md — Complete semantic versioning guide

• references/changelog-format.md — Keep a Changelog format

• references/feature-spec-guide.md — Feature specification writing guide

• references/readme-guide.md — Root README writing guide

Assets

• assets/feature-template.md — Feature file template

• assets/module-template.md — Module explainer template

• assets/changelog-template.md — Changelog template

• assets/readme-template.md — README template

Scripts

• scripts/validate_docs.py — Validate documentation structure

• scripts/generate_feature.py — Generate feature file from template