Generate the API reference from the handlers
Reference documentation generated from the code it describes, so the two cannot disagree.
The ticket
Generate the API reference from the handlers rather than maintaining it by hand.
Acceptance criteria
- The reference is generated by a committed command
- Generation runs in the pipeline and fails when output is stale
- The hand-written reference it replaces is removed
- Prose that generation cannot produce is kept in a separate, linked file
What lands as proof
A pipeline check failing on a stale reference, which is what removes drift as a possibility.
Why teams defer it
- Hand-written references are correct on the day they are written and never again.
- Generated output is less readable, so the switch is a real tradeoff somebody has to accept.
Questions
- What does the agent actually change?
- The ticket is scoped to one outcome: generate the API reference from the handlers rather than maintaining it by hand. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.
- How do I know the work is done?
- The pull request carries the evidence, not only the diff. Here that means reference and code cannot drift apart again, so a reviewer can confirm the result without reproducing the work locally.
- How much oversight does this need?
- None is required before the run starts. Every claim this ticket makes can be checked by machine, so the agent works straight through and a person reviews the finished pull request like any other.