Documentation Guidance

Docs.md Purpose

Docs.md is the authoritative technical reference for implemented work. It serves as:

• •The most comprehensive documentation of what was implemented
• •A standalone technical reference for engineers
• •The source of truth for understanding how the implementation works
• •The basis for generating project-specific documentation
• •Documentation that persists as the go-to reference

Docs.md is NOT: A list of documentation changes or a changelog.

Docs.md Template

# [Work Title]

## Overview

[Comprehensive description of what was implemented, its purpose, and the problem it solves]

## Architecture and Design

### High-Level Architecture
[Architectural overview, system components, data flow]

### Design Decisions
[Key design choices made during implementation and rationale]

### Integration Points
[How this implementation integrates with existing systems]

## User Guide

### Prerequisites
[What users need before using this implementation]

### Basic Usage
[Step-by-step guide for common use cases with examples]

### Advanced Usage
[Complex scenarios, customization options, power-user features]

## API Reference

### Key Components
[Document reusable components that other code will call]

### Configuration Options
[Available settings and their effects]

## Testing

### How to Test
[How to exercise the implementation as a human user]

### Edge Cases
[Known edge cases and how they're handled]

## Limitations and Future Work

[Known limitations, planned improvements, out-of-scope items]

What to Include

Focus Docs.md on information not easily discovered from code:

What NOT to Include

Avoid duplicating information already in code or other artifacts:

Project Documentation Updates

When updating README, CHANGELOG, guides, or API docs, follow these principles:

Style Matching (CRITICAL)

STUDY FIRST: Before updating any project documentation:

1. •Read multiple existing entries/sections
2. •Understand the style, length, and detail level
3. •Match it precisely

CHANGELOG Discipline

• •Create ONE entry for the work, not multiple sub-entries
• •Follow existing format exactly (bullet style, sentence case, etc.)
• •Group related changes into a single coherent entry

Example:

## [Unreleased]

### Added
- Skills-based architecture for implementation workflow (#164)

README Discipline

• •Match section length and detail level of surrounding sections
• •Don't expand sections beyond the existing style
• •Keep additions proportional to the significance of the change

When Uncertain

Err on the side of LESS detail in project docs. Docs.md contains the comprehensive detail; users can ask for more if needed.

Surgical Change Discipline

• •ONLY modify documentation files required to describe the completed work
• •DO NOT format or rewrite implementation code sections
• •DO NOT introduce unrelated documentation updates or cleanups
• •DO NOT remove historical context without explicit direction
• •When unsure if a change is purely documentation, pause and ask

Documentation Depth by Workflow Mode

Quality Checklist

Before completing documentation:

• • Docs.md covers all sections relevant to the implementation
• • Design decisions and rationale documented
• • User-facing behavior explained with examples
• • No code reproduction or over-documentation
• • Project docs match existing style
• • CHANGELOG has single coherent entry
• • README changes proportional to significance