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:

Include	Why
Design decisions and rationale	Not visible in code
Architecture and integration points	High-level view
User-facing behavior and usage patterns	User perspective
How to test/exercise as a human	Verification guidance
Migration paths and compatibility	Operational knowledge
Reusable components for other code	API surface
Edge cases and limitations	Gotchas users should know

What NOT to Include

Avoid duplicating information already in code or other artifacts:

Exclude	Why
Code reproduction	Already in the code
Every function/class	Internal details
Exhaustive API docs	Over-documentation
Test coverage checklists	In PRs and tests
Acceptance criteria verification	In implementation artifacts
Project doc updates list	In PR description
Unnecessary code examples	Only when essential

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

Mode	Docs.md Depth	Project Docs
full	Comprehensive with all sections	Full updates
minimal	Essential information only	Minimal updates
custom	Per Custom Workflow Instructions	As specified

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