Back to Cookbook
KiloClaw

Docs Drift Sweeper

Find broken setup docs before new contributors do

Detect drifting documentation (broken links, wrong setup steps, missing prerequisites) by testing docs as code and filing fix PRs/issues automatically.

CommunitySubmitted by CommunityWork15 min

INGREDIENTS

🐙GitHub

PROMPT

Create a skill called "Docs Drift Sweeper". Given: - Repo link and docs locations (README, CONTRIBUTING, docs/) - The preferred clean environment (Docker/CI runner) Output: - A docs audit checklist and automation plan - Broken link detection approach - A "docs setup test" workflow spec (commands + expected outputs) - Issue/PR templates for doc fixes

How It Works

"Getting started" docs frequently rot, especially in fast-moving projects. This recipe treats

documentation as a testable asset and audits it on a schedule.

Triggers

  • New contributors hit 404s or broken setup steps
  • README instructions don't match current tooling
  • "Docs are outdated" becomes a recurring issue label

Steps

  1. Crawl documentation for broken links and missing anchors.
  2. Execute docs-based setup commands in a clean environment (container/CI).
  3. Detect drift:
  • commands that fail,
  • prerequisites missing,
  • outdated version references.
  1. Open issues/PRs with exact failing steps and proposed fixes.
  2. Add a scheduled docs audit (weekly) and a PR check for docs changes.

Expected Outcome

  • Fewer onboarding failures due to doc rot.
  • Docs become reliable operational tooling.

Example Inputs

  • "Validate our README setup steps weekly."
  • "Find broken links in CONTRIBUTING.md."
  • "Test 'Getting Started' commands in CI."

Tips

  • If docs aren't tested, they *will* drift.
Tags:#documentation#onboarding#build-failures#developer-experience