The docs PR should land before the memory fades

A pull request merges into microsoft/aspire on an ordinary afternoon: a renamed parameter, a resource type that now behaves differently under load, a configuration option nobody outside the team has tried yet. The engineer who wrote it closes the tab and picks up the next ticket, which is exactly what should happen. Three days later, someone on the docs side opens that same PR to work out what changed and why. The commits are all there. What's mostly gone is the reasoning behind them — the tradeoff that got dropped, the edge case that shaped the API, the thing the engineer would have explained in thirty seconds if anyone had asked while it was still warm.

That gap isn't a discipline problem. Docs programs don't fall behind because writers are lazy or engineers don't care about documentation. They fall behind because the product repo and the docs repo run on different clocks, with different reviewers, and nobody is watching the product repo closely enough to catch every change worth writing up before the person who made it stops remembering why.

Microsoft's Aspire team, about ten people building developer tools for distributed apps, published a plain account on July 8 of the automation it built to close that gap, in a post on the GitHub blog by David Pine and Peli de Halleux. It's worth reading past the "AI writes your docs" headline. The interesting part isn't that an agent can draft documentation — plenty of tools can do that. It's the shape of the automation built around the agent: the parts that decide what it's allowed to see, decide, and ship before a human looks at any of it.

What actually runs, and what it did over 30 days

Aspire splits its work across two public repos: microsoft/aspire, the product, and microsoft/aspire.dev, the docs site. When a PR merges into the product repo, a GitHub Agentic Workflow fires. It reads the diff, checks the linked issue and the PR's milestone, decides whether the change needs documentation, and — if it does — opens a draft PR against the docs repo with a first pass at the content. It also comments back on the original PR, so the record of what happened lives in both places.

Over a 30-day window, May 3 through June 2, 2026, the workflow ran against 396 merged product PRs and opened 82 draft docs PRs. By the team's account, all 82 merged. Median time from draft to merge: 44.8 hours. Thirty-eight percent merged within a day; 96% within a week. Of the 82, 52 targeted the release/13.3 branch, 27 targeted release/13.4, and 3 went to main — the workflow resolved the right branch for each one without anyone deciding it case by case.

Those numbers describe an automation doing real, sustained work without turning into a second thing to babysit. That holds up not because the agent is unusually smart, but because almost none of the judgment calls that actually matter (where a draft goes, what it's allowed to touch, who signs off on it) were left for the agent to decide.

The witness loop

Four moments carry the weight, in order.

Before the agent runs, routing is deterministic. The workflow resolves the target docs branch from the PR's milestone, the linked issue's milestone, or the source PR's base ref — plain logic, not a model's guess. On large diffs, that same pre-agent step pulls the milestone, linked issue, and base ref out in a bash script before the agent is invoked, so a big PR doesn't exhaust the prompt budget before the model has done anything useful.

During the run, the agent's job stays narrow: read, decide, draft. It reads the diff, scans the linked issue, judges whether the change is documentation-worthy, and if so, drafts content in the docs workspace. That's the one place fuzzy judgment enters the loop, and it's boxed in on both sides.

After the agent decides what it wants to do, it doesn't do it directly. The agent emits its intent as JSON. A separate, narrowly scoped job, running through a per-workflow GitHub App, reads that intent and materializes the actual PR, issue, or comment. As Pine and de Halleux put it: "The agent’s reasoning is fuzzy. The action surface is not." The agent never holds write credentials to either repo; the handler does, and the handler only knows how to do a small, named set of things.

What comes out the other end is deliberately unfinished. Every docs PR is draft-only, its title prefixed [docs], labeled docs-from-code, restricted to a fixed list of allowed target branches, and routed back to the subject-matter reviewer from the original product PR — the person who already understood the change well enough to approve it in the first place. Protected paths, including AGENTS.md, manifests, and security configuration, are blocked outright, regardless of what the agent decides. If PR creation fails, the workflow falls back to filing an issue instead of going quiet. Nobody but that reviewer merges the docs PR.

That last moment deserves its own sentence: the agent never merges. Someone who already has context on the change reviews the draft while that context is still theirs to check against. As the same post frames the payoff: "Docs no longer trail along behind it like a tin can on a string. The engineer’s review is the gate; the bot does the typing."

Where it broke, and how they fixed it

The team is candid about two failure modes, and both are more useful than the success numbers.

The first version of the docs-worthiness gate was too generous. It drafted PRs for changes that had no business being written up — CI tweaks, logging refactors, the kind of internal churn that produces a real diff but nothing a docs reader needs. Across an earlier 69-PR sample, 9 of those drafts closed without merging, roughly 13%. The fix wasn't a smarter model; it was a tighter prompt, with explicit negative examples of the kind of change that doesn't qualify. A gate defined only by what counts will always run looser than one that also states what doesn't.

The second: big diffs blow prompt budgets. A large product PR can carry more context than a single agent turn can reasonably hold. Aspire's fix was structural, not a bigger context window — pull the milestone, the linked issue, and the base ref out in plain bash before the agent is invoked, so the model spends its attention on the diff and the docs-worthiness call instead of re-deriving facts a script could hand it for free.

Both fixes point the same direction: when an agent workflow misbehaves, the fix that lasts usually lives outside the agent, in the scaffolding that decides what it gets to see and do — not in a better prompt asking it to try harder.

A portable pattern, not a GitHub-specific one

None of this requires GitHub Agentic Workflows specifically. It generalizes to any team automating documentation, changelogs, or release notes off a merge event in one repo that has to land as a reviewable artifact in another.

Call it a docs witness loop: the workflow doesn't just produce documentation, it captures evidence of a change while someone who understands it is still around to check the writeup against reality — and it never lets the agent decide, on its own, that the draft is done.

It's worth contrasting with two patterns we've covered before. Sourcegraph's fleet-migration tooling solves a different problem: dozens of repos need the same fix, so the risk is coordinating one change across many places at once, and the answer is a contract written before the second repo starts. A docs witness loop runs the opposite way — one change, captured once, routed to one reviewer, repeated every time a PR merges. And where a Copilot Actions run card asks a team to decide a workflow's budget and ownership before it spends its first credit, Aspire's safe-outputs handler applies the same discipline to the write itself: constrain what the automation is structurally capable of doing, not just what it's told to do.

Where to start

If your product and docs live in different repos, or different tools entirely, you don't need GitHub's exact machinery to borrow the shape. You need the four moments, in order: a routing step that doesn't ask the model to guess, an agent whose job is bounded to reading and drafting, a materialization step that holds the only write credential, and a human reviewer who's the same person who already understood the change.

Skip the routing step and the agent misroutes drafts to the wrong release. Skip the materialization boundary and a fuzzy decision gets a real write token. Skip the human gate and you've automated the exact failure this industry keeps rediscovering: a bot that's technically right and that nobody actually reviewed.

BaristaLabs helps teams turn one recurring documentation lag (the PR that ships without the writeup, the runbook that's a release behind the product) into a governed loop like this one, with the routing, drafting, hand-off, and review boundaries mapped out before any agent gets access to a second repo. For a broader look at where these boundaries belong across a whole workflow, see our notes on AI workflow controls.