paw-docs-guidance

name: paw-docs-guidance description: Documentation conventions for PAW implementation workflow. Provides Docs.md template structure, include/exclude guidelines, and project documentation update patterns.

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