/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](https://keepachangelog.com/) 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)