documentation

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

Reference: See reference.md for templates, checklists, and examples. </objective>

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. </philosophy>

<when_to_use> Features: After implementing significant new functionality (may span multiple commits) Bug Fixes: Update existing docs to reflect corrected behavior (don't add "bug fix" sections) Refactors: Only if external behavior or usage patterns changed

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

<quick_start>

1. •Understand feature scope - Review all commits related to the feature
2. •Analyze architecture - Identify core types, data flow, design decisions
3. •Generate docs/[feature-name].md - Use template from reference.md
4. •Update package godoc - Use template from reference.md
5. •Add type documentation - Use template from reference.md
6. •Create testable examples - Example_* functions for complex types
7. •Validate - Run through checklists in reference.md </quick_start>

<step_1_understand_scope>

• •Review all commits related to the feature
• •Identify all modified/new files
• •Understand the problem being solved
• •Map out integration points with existing system </step_1_understand_scope>

<step_2_analyze_architecture>

• •Identify core domain types
• •Map data/control flow
• •Document design decisions (WHY choices were made)
• •Note patterns used (vertical slice, self-validating types, etc.) </step_2_analyze_architecture>

<step_3_choose_documentation_layer> Before writing, decide where each piece of documentation belongs.

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. </step_3_choose_documentation_layer>

<step_4_generate_feature_doc> Create docs/[feature-name].md using the template in reference.md.

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. </step_4_generate_feature_doc>

<step_5_update_code_documentation> Using templates from reference.md:

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 </step_5_update_code_documentation>

<step_6_validate> Run through the checklists in reference.md:

• •Feature documentation checklist
• •Code comments checklist
• •Quality gates (clarity, AI, maintenance, example tests)

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? </step_6_validate>

<step_7_manage_size> If documentation grows too large (>500 lines), split into folder structure. See reference.md "Managing Documentation Size" for guidelines. </step_7_manage_size>

<output_format> After generating documentation:

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

</output_format>

<success_criteria> Documentation is complete when ALL of the following are true:

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 </success_criteria>