Grounding drafts in a GitHub repo

Connect a repository and technical drafts are written from the code, rather than from what is plausible.

Why it matters

An assistant writing about your API without seeing it produces something that reads correctly and is wrong in the details — the parameter that does not exist, the response shape from a different version, the endpoint that was renamed last quarter. Those errors are expensive precisely because the prose is fluent.

Grounded in the repository, a draft describes what the code does. It can still be wrong, but it is wrong in ways you can check against a file.

Connecting

Workspace settings → Integrations → GitHub. This installs the Workover GitHub App on the organisation or account that owns the repositories, and you choose which repositories it may read.

Install it on the organisation, not your personal account, if the repositories belong to a company — otherwise the connection breaks the day you change roles.

Access is read-only. Workover does not open pull requests, push commits, or comment on issues.

Using it

Reference the repository in your brief and say what to look at: a directory, a file, an area of the product. “Document the webhook payloads in apps/api/src/modules/webhooks” is a better instruction than “document our webhooks”, for the same reason it would be to a new engineer.

Broad prompts across a whole repository take longer — the draft runs in the background and streams in as it goes, so a large grounding pass does not time out.

What it reads

The repository contents it has been granted: source, README files, types, comments. It does not read your issues, pull requests or CI logs.

Keeping documentation honest

The pattern worth adopting: when an API changes, re-run the draft against the changed files rather than editing the prose from memory. The diff lands as tracked suggestions, so you review the delta rather than re-reading the whole page.