README outdated for 6 months

In most L1 organizations, the README is a time capsule. It accurately describes the project as it existed when someone last had the motivation to update it - often at the project's initial creation, or just before a major release that happened months ago. Since then, the setup instructions have drifted from reality, the architecture diagram shows services that have been renamed or removed, and the "getting started" section references a configuration step that's no longer required.

README rot is not unique to L1 - it exists at every level of maturity. What makes it an L1 characteristic is that the organization has no system for detecting or fixing it. There's no process that ties code changes to documentation updates. No one owns the README. No CI check verifies that the setup instructions still work. When the README is wrong, developers discover it the hard way: a new team member spends two hours debugging a setup problem that the README describes incorrectly.

For AI agents, stale documentation is a double problem. First, agents that are given the README as context will internalize its outdated information - leading to suggestions based on an architecture that no longer exists. Second, a stale README signals that the organization hasn't invested in machine-readable knowledge generally. If the README is six months out of date, the CLAUDE.md file probably doesn't exist, the ADRs haven't been written, and the agent is operating in an information desert.

The README is the canary in the coal mine for an organization's context engineering health. When it's current and accurate, it's usually a sign that other documentation practices are healthy too.

Documentation rot is a debt that compounds at the worst time. When documentation is most needed - during incidents, during onboarding, when AI agents are trying to understand the system - stale docs don't just fail to help, they actively mislead.

• Onboarding velocity drops - new developers lose hours or days to setup instructions that no longer work
• AI agents produce wrong suggestions - agents given outdated docs as context will generate code based on the old architecture
• Trust in documentation erodes - once developers discover that docs are often wrong, they stop consulting them entirely, which accelerates rot
• Incident response is slower - runbooks and architecture docs that are stale increase mean time to recovery during incidents
• Context engineering at L2+ is blocked - you can't build a CLAUDE.md on a foundation of stale documentation; you'd be encoding outdated information

The specific problem of README staleness matters because the README is the most visible and highest-traffic documentation asset in a repository. If the highest-traffic document is stale, the rest of the documentation infrastructure is almost certainly worse.

1. Audit the current state - Run through your own README's setup instructions on a clean environment or fresh container. Note every step that fails, is ambiguous, or references something that has changed. This is your documentation debt inventory.
2. Fix the setup instructions first - The highest-value section of any README is the "how to run this project" section. Fix it now, verify it works, and commit. This is the minimal viable documentation investment.
3. Add a documentation staleness date - Add a line at the top of your README: Last verified: [DATE]. This creates accountability and makes staleness visible.
4. Create a documentation update checklist - Add "update README if architecture changed" to your pull request template. This is a lightweight process change that catches high-impact changes before they cause staleness.
5. Separate evergreen from temporal content - Architecture overviews age slowly; setup instructions age quickly. Structure your documentation so that temporal content (versions, commands, configuration) is clearly separated from evergreen content (design decisions, architectural rationale).
6. Use the audit findings to seed a CLAUDE.md - The gap between what your README says and what the system actually is - once you've identified it - is valuable context. The decisions made since the README was last updated belong in CLAUDE.md.

Treating the README as a one-time artifact. Repositories are living systems; their documentation should be too. A README that accurately described the system at launch will diverge from reality within weeks if there's no process to keep it current. Treat documentation updates as part of every significant change, not as a separate documentation effort.

Writing for the original team, not for newcomers. READMEs are often written by the people who built the system, who have deep context and can't see what they're omitting. The best test of a README is to have someone unfamiliar with the project follow it. If they succeed, it's good. If they need help, you have documentation debt.

Confusing code comments with documentation. Code comments explain what the code does; README-level documentation explains why the system exists, how its pieces fit together, and how to operate it. These are different things. A well-commented codebase with a stale README is still a codebase with a stale README.

Fixing the symptom without addressing the cause. Updating the README once is not enough. The reason it went stale is that the team has no process for keeping it current. The fix is a process change - PR template checklist, quarterly audit, documentation owner - not a one-time update.