Show HN: Agents report broken docs, you get a GitHub issue

2 points

4 hours ago

I tried having my agents read the vendor's docs before jumping into tasks, but in a lot of cases the docs are simply incomplete or stale. I burn tokens working around that — and the maintainer never finds out their docs are broken. The signal, "an AI just hit a wrong page in your docs," gets dropped on the floor.

FixYourDocs is an attempt to give that signal somewhere to go. It's an open protocol (one JSON shape, one POST /v1/reports) plus a hub that routes each report to whoever has verified they own the doc — by domain or by GitHub Pages repo — and opens a GitHub Issue on their repo. There are two SDKs (pip install fixyourdocs, npm i @fixyourdocs/sdk) and an MCP server (npx -y @fixyourdocs/mcp-server) that exposes a single file_doc_feedback tool.

Try it yourself: ``` curl -X POST https://hub.fixyourdocs.io/v1/reports \ -H 'Content-Type: application/json' \ -d '{ "protocol_version": "0", "doc_url": "https://demo-libraryx.com/payments", "agent": { "name": "claude-code" }, "report": { "kind": "outdated", "summary": "Payments guide still shows the v1 charge flow (change me to avoid dedup)" } }' ``` and watch it land here: https://github.com/fyd-demo-maintainer/demo-libraryx/issues

Heads-up: this example opens a real, public GitHub Issue on the demo repo, so don't put anything you wouldn't want public in the summary.

The landing page has a short demo that walks the whole loop — from an agent hitting a stale doc to the GitHub Issue that opens for the maintainer: https://fixyourdocs.io

It's built with Claude and open: the protocol and SDKs are Apache-2.0, the spec text is CC-BY, all at docsfeedback.org. The hosted hub is FSL, converting to Apache-2.0 in two years.

Landing page: https://fixyourdocs.io Spec: https://docsfeedback.org Code: https://github.com/fixyourdocs

Happy to go deep on any of the details.