I let an AI agent write a README for a real repo — here's what it produced

Description and use

A pipeline that extracts deterministic facts from a repo, feeds them to an LLM, and verifies the output ensures a fully accurate README without hallucinations.

Problem

Small open‑source projects often have README files that no longer match the code, leading to confusion and misuse. The goal was to generate a README that accurately reflects the repository’s flags, environment variables, and license, without hallucinating unsupported features.

Outcome

The pipeline produced a fully accurate README for the ped CLI tool, with zero invented flags or env vars. Verification ensured factual correctness, and the only issue was an inherited mistake from the original README, which was manually corrected.

Workflow

• 1. Fetch repository files via HTTP.
• 2. Extract deterministic facts from pyproject.toml, argparse calls, os.environ lookups, and LICENSE.
• 3. Feed extracted facts and source files to an LLM to generate a README.
• 4. Verify the README against extracted facts, rejecting any invented flags or env vars.

Evidence

Zero invented flags, zero invented environment variables. Not because the model is trustworthy — because anything it invented would have been caught and the whole deliverable rejected.

Source

The Bash tab-completion section came out as: python -m ped.install_completion > /usr/local/etc/bash_completion.d

Source