The problem this solves
Broken links are entropy made visible. Every restructure, every retired page, every renamed slug leaves a few links pointing at nothing, and the count only ever grows. Individually each one is trivial; collectively they leak crawl budget, dead-end users at the exact moment they were engaged, and signal neglect to both visitors and the systems that evaluate site quality. Soft 404s are worse for being invisible: pages that return success while showing nothing useful, quietly polluting the index.
The reason sweeps rarely happen is that the work splits awkwardly in two. Internal breakages are fixable but tedious: someone must find each broken reference in the codebase, work out the right target, and ship the edit. External breakages are unfixable from inside: links pointing at your site from elsewhere require outreach, and links from your site to dead external pages require editorial judgment about replacements. Handing one undifferentiated list of both to one person guarantees neither half gets done.
The sweep that works respects the split. Internal fixes arrive as a pull request against the actual codebase, reviewable and mergeable by engineering on their own terms, with nothing merging itself. External breakages arrive as a CSV built for the chase: what is broken, where it is referenced, and what the fix would require, ready for whoever owns outreach or content. Each half lands with the person who can act on it, in the format that action takes.
How the mission runs
- Sweep the full site. Site Audit crawls the site and catalogs every broken internal link, each recorded with its source page and dead target, plus soft 404s: pages returning success while serving no meaningful content. Everything is captured with evidence, so each finding is checkable before anything gets changed.
- Trace internal breakages to source. Each broken internal link is traced to where it lives in your GitHub repository: the template, content file, or component emitting it. This mapping is what turns a findings list into a fix, and references that cannot be confidently located are held for the report instead of guessed at.
- Fix the internal half in a PR. Repairs are authored as a pull request: dead targets updated to their correct destinations, genuinely retired targets unlinked, and soft-404 pages flagged with a proposed disposition per page. Commits are grouped by fix type, each explained, and the PR waits for human review, because nothing merges itself.
- Compile the external half as CSV. External breakages land in a CSV built for follow-through: the broken URL, every page referencing it, the breakage type, and what resolution would take - a replacement link, an outreach note, or removal. Sorted so the highest-visibility breakages surface first.
- Deliver both halves to their owners. The PR goes to engineering through the normal review flow; the CSV goes to whoever owns content and outreach. The closing summary counts what was found, what the PR fixes, and what the CSV hands off, so the sweep's full residue is visible and owned.
The prompt
This is the exact objective the agent receives. Swap the obvious placeholders for your own domain, segment or channel and run it as-is from the console, Slack, or the API.
What comes back
Two artifacts, each shaped for its owner: a pull request repairing every confidently-traceable internal breakage, commits grouped by fix type with reasoning, soft-404 pages flagged with proposed dispositions, and review and merge left entirely to your team; and a CSV of external breakages listing each broken URL, its referencing pages, and the resolution it needs, ordered by visibility so the chase starts where it matters most.
Make it yours
- Schedule the sweep monthly: after the first cleanup, subsequent runs are small, and link rot gets caught within weeks of appearing instead of years.
- Extend the soft-404 handling into the redirect conversation, proposing where each hollow page's traffic should actually land instead of merely flagging it.
- Scope a run to a single section before a relaunch, using the sweep as the pre-flight check for the part of the site about to change.
Frequently asked questions
What decides whether a fix goes in the PR or the CSV?
Actionability from inside the repository. Breakages the agent can trace to your own code or content are fixed in the PR; anything requiring editorial judgment about external replacements, or action by another site's owner, goes to the CSV with the context the chase needs. Untraceable internal references are reported rather than guessed.
How are soft 404s judged?
By what the page actually serves: success status paired with empty, placeholder, or error-like content. Each flagged page carries the evidence and a proposed disposition - redirect, restore, or properly retire - and the judgment stays with your team in PR review, since a soft 404 is sometimes a page mid-renovation.
Can the sweep run continuously?
Monthly scheduling gets most of the benefit: rot is caught early, PRs stay small enough to review in minutes, and the CSV becomes a short standing chase list rather than an archaeology project. Each run is idempotent in effect, since already-fixed links simply stop appearing in findings.