Fact-check documentation

Codebase Research & Fact Checking

Write only what the code, configuration, tests, command output and accepted decisions actually prove. Never invent endpoints, commands, configuration keys, defaults or product capabilities, and never repeat an older document's claim without checking the source that runs today.

1. Establish the existing documentation map first

• Inspect the repository's documentation layout before drafting or editing: root README.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md, package-level READMEs, docs/, ADR directories, OpenAPI specs and inline module comments.
• Identify which document owns which subject so you update the canonical file instead of creating a parallel, competing explanation.
• Note the language, formatting, heading structure and link style the project already uses.

2. Verify every claim against the primary source in the repo

• Commands and scripts: check package.json scripts (in the root and each workspace), Makefile, composer.json, CLI entry points and CI workflows (.github/workflows/*). Record the exact working directory and required prerequisites.
• Configuration and environment variables: find where the variable or setting is actually parsed in code, its type, its fallback/default value, and when it takes effect (build time, startup, per request). Cross-check .env.example against the reader in code.
• Endpoints, routes and payloads: read the route registration, middleware/guards, request schema/validator, handler and response serializer. Check status codes and error shapes from the error handler and tests.
• Data model and state transitions: check migrations, schema definitions, models and domain services for column names, constraints, allowed states and side effects.
• Background jobs, queues and schedules: check job classes/handlers, retry/backoff settings, idempotency guards, timeout configuration and failure handling.
• Tests as executable evidence: read unit, integration and e2e tests to confirm edge cases, expected inputs, error responses and invariants.

3. Separate present truth, planned work and history

• Keep three distinct buckets while researching:
  1. Current behavior: what the code on the current branch actually executes.
  2. Planned or proposed behavior: specs, open RFCs, unimplemented roadmap items or feature-flagged stubs. Label them explicitly as planned; never present them as working features.
  3. Historical context: superseded ADRs, legacy migration notes or deprecated paths. Mark why they existed and what replaced them.
• When existing documentation and the code disagree, the code shows what runs. Surface the discrepancy clearly. Document the observed behavior, but never enshrine a known bug as an intended requirement.

4. Handle unknowns honestly

• Keep a clear distinction between verified facts, unverified assumptions (for example, an external service behavior you cannot run locally), and open questions that need an architect or product decision.
• Never resolve a business or architectural contradiction by guessing in prose; record the contradiction and cite both sides with file paths.

Before you finish

• Existing documentation structure and canonical files mapped before creating or editing.
• Every command, path, config key, default, route and type checked against the code.
• Current behavior, planned changes and historical decisions clearly separated.
• Code-vs-doc mismatches identified without turning bugs into requirements.
• Any unverified claim or external dependency explicitly marked.