Your Docs Are Stale the Second You Merge: How GitHub Ships Docs Alongside Code

The Reverse-Engineering Tax

"Where are the docs?" It is a question nobody on a product team enjoys answering. The honest reply is almost always "behind."

The default workflow looks like this. An engineer ships a feature. A docs writer notices weeks later. They open a pull request, read the diff, and ping the engineer to clarify what changed. The engineer is already on the next feature. They vaguely remember and reply with half the picture. The docs draft ships, sometimes against a release that is already out.

This is the reverse-engineering tax. Your team pays it every release cycle.

The Aspire team at Microsoft lived this. They are a small team of ten building dev tooling for distributed applications. Their product lives in microsoft/aspire and their docs site lives in microsoft/aspire.dev -- different repos, different deploy targets, different review chains. The cross-repo gap meant their documentation was always a release behind.

Then they started experimenting with GitHub Agentic Workflows. The results: for Aspire 13.3 and 13.4, 82 feature-docs pull requests merged at a median of 44.8 hours after the product pull request. Every one of them reviewed by the engineer who shipped the feature. No new headcount. No process retraining.

How the Architecture Works

GitHub Agentic Workflows is a project from GitHub Next. Think of it as GitHub Actions with an LLM as the work-item processor, plus guard rails that pass security review.

The shape of it:

• You author a workflow as a single markdown file (.github/workflows/my-thing.md). YAML frontmatter on top, an English-language prompt underneath.
• Run compile and it generates a sibling .lock.yml -- a normal GitHub Actions workflow that you commit alongside.
• At runtime, the workflow runs an agent against your prompt with a constrained toolset.
• The agent does not write to GitHub directly. It emits "intent" -- a JSON blob describing the pull requests, issues, and comments it wants to create. A separate, narrowly scoped job called the safe-outputs handler materializes that intent against a per-workflow GitHub App.

That last bullet is the architectural unlock. The agent gets read access to the code repo and a prompt. Writes go through a tiny verifiable pipeline with explicit allow-lists. Security nods. You ship.

For the Aspire team, the prompt instructs the agent to find a merged product PR, read the diff, and open a docs PR in the docs repo. The agent knows which issues to track, which labels to apply, and how to format the content. The final review still belongs to the engineer who wrote the code. The median 44.8 hour turnaround proves the loop is tight enough.

The Pattern Is Bigger Than Docs

The architecture pattern -- read-only AI agent, structured intent output, verified write pipeline -- generalizes to any situation where code changes need supporting material to follow.

Stripe is working the same problem from the API side. Their data shows AI agents are fully capable of writing code and integrating with APIs. But the adjacent work -- understanding the API reference, writing integration examples, generating code snippets -- is still too hard for agents to do independently. Stripe Projects addresses this by giving agents a more structured development environment with pre-configured providers and controls. Same principle: reduce the friction between the code change and its supporting output.

Intercom's Fin team calls this the New Product Introduction problem. Every time you ship a product change, your AI agent's knowledge base needs to keep pace. Fin treats Agent readiness as a launch blocker: a feature is not "shipped" until the Agent can answer questions about it correctly. They follow a formal checklist: prepare new knowledge written in customer language, review and retire outdated content, then test the Agent before launch. They do it with process discipline. The Aspire team does it with automation. Either way, the principle is identical.

What to Steal for Your Own Product

You do not need GitHub Agentic Workflows specifically to apply this pattern. The design principles generalize:

Separate read and write capabilities. The agent should be able to read the source of truth (your code diffs, your API surface, your changelog) but emit structured output that a verified pipeline materializes. This is what makes the pattern safe enough to run unattended. If your agent can write directly to production repos, you will eventually have a bad day.

Close the loop with the SME. The Aspire team's docs PRs are auto-generated but reviewed by the engineer who shipped the feature. The automation does the drafting. The human does the verifying. A 44-hour median turnaround means the engineer sees the draft while the feature is still fresh in their head.

Cross-repo is the real unlock. Same-repo automation is table stakes. The hard problems live at repo boundaries: docs in one repo, code in another. API reference in a separate system. Knowledge base in a third. That is where the value lives.

One markup file, one workflow. The single-markdown-file approach is elegant because it makes the workflow readable, auditable, and editable by anyone on the team. Anyone can see exactly what the agent is instructed to do and tweak the prompt without learning YAML.

Where the Pattern Breaks

The obvious failure mode is a bad prompt. If the agent does not understand the context of your documentation, it generates content that looks right but is wrong in subtle ways. The Aspire team handles this by keeping the SME in the review loop and iterating on the prompt over successive releases. Plan for 3-4 release cycles before the prompt stabilizes.

Another failure mode: documentation that involves design decisions rather than implementation details. An AI can describe what a parameter does from reading the type signature. It cannot decide whether a feature name should change for clarity or whether a concept needs a new page. Those decisions stay with the human.

And the pattern assumes your diffs are informative. If your PRs are 5,000-line refactors with no structure and generic commit messages, no AI can write useful docs from them. The agent works best when your code changes are well-structured. This is a forcing function for better engineering discipline.

The Bottom Line

Documentation lags because the loop is manual and crosses organizational boundaries. GitHub Agentic Workflows shows that an AI agent with read access to the code repo and a constrained write pipeline to the docs repo can close the gap from weeks to under two days.

The specific tooling will evolve, but the architecture pattern will stick: read-only agents emitting structured intent through verified write pipelines, with humans reviewing the output. If your team still ships code and then "gets to the docs later," you are leaving days of value on the table every release cycle.