documentation-guide

name	documentation-guide
description	Documentation standards enforcing Keep a Changelog format, README structure, ADR templates, and Google-style docstrings. Use when writing CHANGELOG entries, updating READMEs, or documenting APIs. TRIGGER when: changelog, readme, documentation, docstring, ADR, API docs. DO NOT TRIGGER when: code-only changes, test files, config updates without API changes.
allowed-tools	["Read","Write","Edit","Grep","Glob"]

Documentation Guide Enforcement Skill

Ensures all documentation is consistent, current, and complete. Used by the doc-master agent.

Keep a Changelog Format

All CHANGELOG entries MUST follow Keep a Changelog format.

Categories (in this order)

• Added — new features
• Changed — changes to existing functionality
• Deprecated — soon-to-be removed features
• Removed — removed features
• Fixed — bug fixes
• Security — vulnerability fixes

Structure

# Changelog

## [Unreleased]

### Added
- New authentication module (#123)

### Fixed
- Token expiry off-by-one error (#124)

## [1.2.0] - 2026-02-15

### Added
- Batch processing support (#100)

The [Unreleased] section MUST always exist at the top for accumulating changes.

---

README Required Sections

Every README.md MUST contain these sections in order:

1. Overview — 1-2 sentence project description
2. Installation — How to install/set up
3. Usage / Quick Start — Minimal working example
4. Commands Table — Available commands with descriptions
5. Configuration — Config files, env vars, options
6. Contributing — How to contribute, link to CONTRIBUTING.md

---

Docstring Format: Google Style

All public functions MUST have Google-style docstrings.

def process_data(
    data: List[Dict],
    *,
    validate: bool = True,
) -> ProcessResult:
    """Process input data with optional validation.

    Args:
        data: Input records as list of dicts with 'id' and 'content' keys.
        validate: Whether to validate input before processing.

    Returns:
        ProcessResult with metrics and processed items.

    Raises:
        ValueError: If data is empty or missing required keys.
    """

Include Args, Returns, and Raises for every public function. Omit sections only if truly not applicable (e.g., no exceptions raised).

---

HARD GATE: Sync Rules

Documentation MUST stay in sync with code at all times.

FORBIDDEN:

• Updating code without updating corresponding docs
• Hardcoded component counts (e.g., "17 agents") — use dynamic discovery or verify against filesystem
• Undocumented public APIs — every public function needs a docstring
• Stale cross-references — links to files/sections that no longer exist
• CHANGELOG entries without issue/PR numbers
• Version dates that do not match actual release dates

REQUIRED:

• CHANGELOG entry for every user-visible change
• Version date updated when changes are made
• Component counts verified against filesystem before committing
• Cross-references validated (all linked files exist)
• README updated when commands or configuration change
• Docstrings updated when function signatures change

---

When to Update Which Docs

Change Type	README	CHANGELOG	Docstrings	ADR
API change	Yes	Yes	Yes	Maybe
New feature	Yes	Yes	Yes	Maybe
Bug fix	No	Yes	No	No
Refactor (no behavior change)	No	No	Maybe	Maybe
Architecture decision	No	No	No	Yes
Config change	Yes	Yes	No	No
Deprecation	Yes	Yes	Yes	Maybe

---

ADR Template

For major architectural decisions, create an ADR (Architecture Decision Record).

# ADR-NNN: [Title]

**Date**: YYYY-MM-DD
**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-NNN

## Context
What is the issue or decision we need to make?

## Decision
What did we decide and why?

## Consequences
What are the positive and negative outcomes?

## Alternatives Considered
What other options were evaluated and why were they rejected?

Store ADRs in docs/adr/ directory, numbered sequentially.

---

Anti-Patterns

BAD: Hardcoded counts

This project has 17 agents and 40 skills.

These numbers drift immediately. Verify against filesystem or use dynamic discovery.

GOOD: Verified counts

# Count before documenting
ls plugins/autonomous-dev/agents/*.md | wc -l
ls plugins/autonomous-dev/skills/*/SKILL.md | wc -l

BAD: Stale cross-references

See [architecture guide](docs/ARCHITECTURE.md) for details.

If docs/ARCHITECTURE.md was renamed to docs/ARCHITECTURE-OVERVIEW.md, this link is broken.

GOOD: Validated references

Check all links exist before committing documentation changes.

BAD: Missing CHANGELOG entry

Shipping a user-visible feature with no CHANGELOG entry. Users cannot discover what changed.

GOOD: CHANGELOG-first workflow

Write the CHANGELOG entry before or during implementation, not as an afterthought.

---

Cross-References

• git-github: Commit message and PR conventions
• code-review: Documentation checklist item (#8)