{"slug": "the-next-bottleneck-after-ai-writes-your-code-is-reviewing-the-docs-it-writes", "title": "The next bottleneck after AI writes your code is reviewing the docs it writes", "summary": "A developer identified that document review, not code writing, is the new bottleneck in AI-assisted software development. To solve the imprecision of natural-language feedback on generated docs, they built MDXG Redline, a tool that anchors reviewer comments to specific text ranges in markdown and exports them as structured JSON. This allows AI agents to precisely locate and act on feedback, reducing ambiguity and round-trips.", "body_md": "Coding agents draft specs, architecture docs, changelogs, and README updates in seconds — but a human still has to judge the quality of all that output.\n\nA year ago, the typical workflow was: you write a spec, you get comments, you revise, then you implement and get code review. Humans did most of the writing and coding. Now, agents produce first drafts of design docs, API references, runbooks, and onboarding guides — and they do it in seconds.\n\nCode implementation and code review can now be handled by agents, so those are no longer the bottleneck. What surfaced instead is the step right before: document review. A human has to read 2,000 lines of generated markdown and decide what's wrong. The writing part got dramatically faster. LLMs can assist with document review too, but compared to code implementation and code review, the human judgment required is still larger.\n\nThis asymmetry compounds fast. Every agent-assisted project now has a stack of \"needs human review\" documents growing in a shared folder. If you're running multiple agent loops in parallel — one for the spec, one for the implementation plan, one for the test strategy — review becomes a pipeline stall. GitHub PRs remain the right tool when you need third-party review. But the step before that — the fast local self-review loop where you and your agent iterate on a draft — doesn't belong in a PR. Branching, diffing, and assigning reviewers is a lot of process for a first draft the agent wrote in seconds.\n\nThe most common workaround today is to have the agent read the document and then fix things based on natural-language feedback:\n\n\"The error handling in section 3.2 is too vague — be specific about what happens on timeout.\"\n\nThis looks reasonable. The agent reads it, searches for something about error handling, and makes a change. But several things go wrong:\n\n**Position is ambiguous.** If section 3.2 has three paragraphs about error handling, which one did the reviewer mean? The agent guesses, and sometimes guesses wrong.\n\n**Context is lost.** The reviewer was looking at a *rendered* document — they saw the Mermaid diagram, the table layout, the code blocks with syntax highlighting. The prose feedback carries none of that visual context.\n\n**Round-trips are vague.** The agent applies a fix. Did it address the right spot? The reviewer pastes the updated draft back into the chat. No diff. No anchoring. Another round of guessing.\n\nThe fundamental problem: prose feedback loses the structure the reviewer had in mind. The reviewer knows which text range they're commenting on — but that spatial information is discarded the moment they express it in natural language.\n\nWhat if the reviewer's comments came back as structured JSON, with every comment anchored to a precise location in the source markdown?\n\nThat's what [MDXG Redline](https://github.com/oubakiou/mdxg-redline) ([online demo](https://mkdn.review/?url=https%3A%2F%2Fraw.githubusercontent.com%2Foubakiou%2Fmdxg-redline%2Frefs%2Fheads%2Fmain%2FREADME.md)) produces. The reviewer selects any text range in a rendered markdown document, leaves an inline comment, and on export the tool writes a JSON file like this:\n\n```\n{\n  \"document\": \"api-spec.md\",\n  \"docHash\": \"a1b2c3d4e5f6a7b8\",\n  \"exportedAt\": \"2026-06-15T10:30:00.000Z\",\n  \"comments\": [\n    {\n      \"id\": \"f3a1c8b2\",\n      \"quote\": \"The service retries up to 3 times\",\n      \"comment\": \"Specify the backoff strategy — is it exponential? Fixed interval? This matters for downstream timeout config.\",\n      \"headingPath\": [\"## 3. Error Handling\", \"### 3.2 Retry Policy\"],\n      \"sourceLine\": 142,\n      \"created\": \"2026-06-15T10:28:11.000Z\"\n    }\n  ]\n}\n```\n\nEvery comment carries:\n\n`quote`\n\n`comment`\n\n`headingPath`\n\n`[\"## 3. Error Handling\", \"### 3.2 Retry Policy\"]`\n\n), so the agent can navigate the document hierarchy`sourceLine`\n\n(The actual export also includes `blockId`\n\n, `startOffset`\n\n, and `endOffset`\n\n— internal anchoring fields used for round-trip re-import into the next review round. The four fields above are the ones your agent needs.)\n\nNo guessing, no ambiguity. The agent reads the JSON, opens the source file, goes to line 142, and applies the feedback directly. The feedback JSON is a plain file on disk — any agent that can read JSON and edit files can consume it, regardless of framework or provider.\n\nMDXG Redline is designed around a review loop where an agent and a human pass a document back and forth:\n\n`<name>-<hash>-review.html`\n\nfile from the markdown — a self-contained HTML file that renders the document with syntax highlighting, diagrams, and math.`<name>-<hash>-feedback.json`\n\nto the same folder.Each revision gets a unique hash in the filename, so review/feedback pairs for different revisions never collide.\n\nFor Claude Code and Codex users, there's a `md-review`\n\nskill that automates the entire loop — HTML generation, waiting for feedback, and applying revisions:\n\n```\n# install the skill\ngh skill install oubakiou/mdxg-redline md-review --agent claude-code --scope project\n\n# then just tell the agent:\n# \"please request a review for spec.md\"\n# or invoke the slash command directly:\n# /md-review README.md\n```\n\nThe skill is a convenience wrapper. Since the feedback JSON is a plain file, the loop works with any agent — you can wire it into a custom LangChain pipeline or a simple shell script that polls for the JSON.\n\nMDXG Redline isn't just a review overlay — it's a markdown rendering engine packed into a single standalone HTML file with no backend and no dependencies.\n\n**Smartphone support** — On mobile screens, the UI switches to a layout with a footer bar for TOC, Comments, and Search. You can review and comment from your phone — no need to wait until you're back at your desk.\n\n**Syntax highlighting for ~235 languages** — The CLI auto-detects which languages your document uses and injects only those Shiki grammars, keeping the file lean.\n\n**Mermaid diagrams and KaTeX math** — Fenced ```\n\n`mermaid`\n\nblocks render as SVGs; `$...$`\n\n/ `$$...$$`\n\nmath renders via KaTeX. Both are auto-detected and injected only when present.\n\n**Word-style stacked pages** — The document splits at H1/H2 boundaries into paper-like sheets you scroll through vertically, with a sidebar for navigation. Footnotes and left-hand keyboard navigation are also built in.\n\nSee the [full feature list in the README](https://github.com/oubakiou/mdxg-redline#features) for details.\n\n**No install needed** — open [mkdn.review](https://mkdn.review/) and load any public GitHub raw URL. Here's a one-click example that loads the project's own README:\n\nSelect any text in the rendered document, leave a comment, and click \"Copy as JSON\" to see the structured output.\n\nWant to try with your own project? Just replace the URL: `mkdn.review/?url=<your-github-raw-url>`\n\n.\n\n**Local review** — if you have Node.js:\n\n``bash`\n\nnpx mdxg-redline your-draft.md\n\n`\n\nThis generates a review HTML in the same directory and opens it in your browser. The generated file is fully self-contained — you can email it, drop it in Slack, or put it in a shared folder. Everything stays local; no content or comments are sent anywhere.\n\n**Privacy note**: The standalone and CLI builds enforce `connect-src 'none'`\n\nvia CSP — your document body and comments *cannot* leave the browser. The online version (`mkdn.review`\n\n) likewise never sends your content or comments anywhere — the only network request is the `?url=`\n\nfetch, which retrieves public raw content from a short allowlist (GitHub raw, Gist raw).\n\nMDXG Redline is a third-party implementation of the [Markdown Experience Guidelines (MDXG)](https://github.com/vercel-labs/mdxg) by Vercel Labs — the read-only Viewer rendering profile, with a review layer (inline commenting + structured JSON export) added on top. See the [compliance table](https://github.com/oubakiou/mdxg-redline#mdxg-compliance-status) for details.\n\n**MDXG Redline** is MIT-licensed and fully open source. If reviewing agent-generated documents is a bottleneck in your workflow, give it a try:\n\n`npx mdxg-redline draft.md`\n\n`gh skill install oubakiou/mdxg-redline md-review`\n\n(If you've tried it with your agent workflow, I'd love to hear how the structured JSON feedback format worked for you — drop a comment below or [open an issue on GitHub](https://github.com/oubakiou/mdxg-redline/issues).", "url": "https://wpnews.pro/news/the-next-bottleneck-after-ai-writes-your-code-is-reviewing-the-docs-it-writes", "canonical_source": "https://dev.to/kiou_ouba_afbd120335456f3/the-next-bottleneck-after-ai-writes-your-code-is-reviewing-the-docs-it-writes-3pc7", "published_at": "2026-06-17 03:43:15+00:00", "updated_at": "2026-06-17 04:21:55.501406+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents", "generative-ai"], "entities": ["MDXG Redline", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/the-next-bottleneck-after-ai-writes-your-code-is-reviewing-the-docs-it-writes", "markdown": "https://wpnews.pro/news/the-next-bottleneck-after-ai-writes-your-code-is-reviewing-the-docs-it-writes.md", "text": "https://wpnews.pro/news/the-next-bottleneck-after-ai-writes-your-code-is-reviewing-the-docs-it-writes.txt", "jsonld": "https://wpnews.pro/news/the-next-bottleneck-after-ai-writes-your-code-is-reviewing-the-docs-it-writes.jsonld"}}