Write Go Docs

Treat information gain as the admission test: source documentation earns its place when it reduces uncertainty beyond the name, signature, types, and immediate context. Keep changes inside Go source and Go example tests; route README and architecture work to their own documentation workflows.

Workflow

1. Bound the work and gather evidence

• Follow the user's requested files, packages, declarations, or diff. Expand to callers, tests, interfaces, implementations, and history only as needed to establish public behavior or durable rationale.
• Honor audit-only or review-only requests by keeping source unchanged and returning evidence-backed decisions.
• Treat files carrying the standard // Code generated ... DO NOT EDIT. marker as read-only and report the generator or source artifact that owns their documentation.
• Inspect go.mod, nearby documentation style, and configured validation when syntax or lint policy may depend on them.
• Treat code and tests as evidence of behavior, not proof of unstated intent. Record a focused maintainer question when important rationale remains unresolved.

Continue once the documentation boundary, relevant conventions, enforced checks, and unresolved questions are explicit.

2. Apply the information-gain test

For each package, exported declaration, existing doc comment, and non-obvious internal declaration in scope, choose retain, add, revise, remove, or skip.