Documentation

This is NOT a changelog - it's an introduction to current product behavior.

Reference: See reference.md for templates, checklists, and examples.

Behavior Over History: Document what the product DOES, not what changed. When readers come back later, they need to understand current behavior, not archaeology.

Conciseness Over Completeness: A focused doc that gets read beats an exhaustive doc that gets skipped. Document what matters for understanding and usage.

Layered Documentation: Different scopes need different docs. System-level overviews, project guides, feature docs, and code comments each serve distinct purposes. See reference.md for layer definitions.

Documentation IS: Explaining WHY decisions were made, providing context for future changes, showing how pieces fit together, helping both humans and AI understand intent.

Documentation is NOT: A changelog of commits, implementation details without context, API reference without explanation.

NOT for: Individual commits, internal refactors that don't change behavior, changelog entries

Decision Questions:

The Overlap Rule:

• Summarize up, detail down: Higher layers summarize, lower layers elaborate
• Good overlap: System doc mentions "auth uses JWT" → Feature doc explains JWT implementation
• Bad overlap: Same paragraph copy-pasted across multiple docs (will drift)

Cross-Reference, Don't Duplicate:

• System doc: "See docs/auth.md for authentication details"
• Feature doc: "See UserID godoc for validation rules"
• Code doc: "See docs/auth.md for architectural context"

See reference.md "Choosing Documentation Layer" for detailed decision tree.

Cover:

• Problem & solution: What problem does this solve?
• Key players: Who are the main actors? (types, interfaces, services)
• Entry points: Where does execution start? (handlers, commands, events)
• Architecture: How does it work?
• Usage examples: How do I use it?
• Integration: How does it fit into the system?

For bug fixes: Don't create new docs. Update existing docs to reflect correct behavior. See reference.md "Bug Fix Documentation" guidelines.

1. Package godoc - Update to reflect feature's role
2. Type godoc - Explain purpose, design decisions, constraints
3. Function godoc - Only for non-obvious behavior
4. Testable examples - Example_* functions for complex types

Code docs should reference feature docs: See docs/[feature].md for detailed architecture

Key questions:

• Can someone unfamiliar understand the feature?
• Can AI use this for bug fixes without reading all code?
• Are design decisions clearly explained?
• Are integration points documented?

DOCUMENTATION COMPLETE

Feature: [Feature Name]

Generated Artifacts:
- docs/[feature-name].md (created/updated)
- Package godoc updated in [package]/[file].go
- Type documentation for: [list types]
- Testable examples: [list Example_* functions]

Validation:
- [ ] Feature doc checklist passed
- [ ] Code comments checklist passed
- [ ] Quality gates passed

Next Steps:
1. Review docs/[feature-name].md for accuracy
2. Run `go test` to verify testable examples
3. Commit documentation

Content:

• Feature doc created/updated at docs/[feature-name].md
• Package godoc updated to reflect feature's role
• Key types have godoc explaining purpose and design decisions
• Testable examples created for complex/core types

Quality:

• Describes current behavior (not history or changelogs)
• Someone unfamiliar can understand the feature
• AI can use this for bug fixes without reading all code
• Design decisions are clearly explained with rationale

Maintainability:

• Doc stays focused and scannable (split if >500 lines)
• No redundant information across layers
• Cross-references between doc layers are clear