Readme Refresh

README Refresh

Audit and update the project README, or bootstrap one if it doesn't exist. The README is a living document — it evolves with the code and should always reflect the current state of the project.

Command Options

• --bootstrap: Force bootstrap mode even if a README exists (useful to start fresh)

Your task

Step 0: Detect mode

• If README.md exists at the project root and --bootstrap was not passed: enter Refresh mode (Step 1).
• If README.md does not exist or --bootstrap was passed: enter Bootstrap mode (Step 5).

Refresh Mode

Step 1: Scan the project

Gather facts from the codebase. Do not rely on the README's current claims — verify independently.

Tech stack and versions:

• Ruby version: .ruby-version, Gemfile.lock (RUBY VERSION section), .tool-versions
• Rails version: Gemfile.lock (search for rails ()
• Node version: .node-version, .nvmrc, .tool-versions, package.json (engines)
• Database: config/database.yml, Gemfile.lock (pg, mysql2, sqlite3)
• Key framework gems/packages: Devise, Turbo, Stimulus, Tailwind, Solid Queue, etc. — scan Gemfile or package.json for notable dependencies

Services and infrastructure:

• Hosting: fly.toml (Fly.io), netlify.toml, Procfile, render.yaml, app.json (Heroku), Dockerfile, docker-compose.yml
• Storage: look for Active Storage config, S3/Tigris credentials in config/storage.yml
• Email: config/environments/production.rb (SMTP settings, action_mailer config), initializers for Postmark/SendGrid/etc.
• Background jobs: config/application.rb or initializers (Solid Queue, Sidekiq, etc.)
• Search: Elasticsearch, Meilisearch, etc.

Available commands:

• bin/ directory: list executable scripts (bin/rails, bin/dev, bin/ci, bin/setup, etc.)
• Procfile.dev or Procfile: processes defined for local development
• Makefile or Taskfile: custom task definitions
• package.json scripts section

Configuration requirements:

• .env.example or .env.template: expected environment variables
• config/credentials.yml.enc or config/master.key: credentials setup
• config/database.yml: database setup requirements

CI/CD:

• .github/workflows/: GitHub Actions workflows
• .circleci/, .travis.yml, Jenkinsfile: other CI configs

Step 2: Compare against the README

Read the current README.md and compare each claim against the facts gathered in Step 1. Build a findings report with three categories:

1. Outdated — the README states something that is no longer accurate (e.g., "Rails 7.1" when Gemfile.lock shows Rails 8.0, or mentions a service that has been removed).
2. Missing — something exists in the project that the README doesn't mention and reasonably should (e.g., a bin/dev script for local development, a background job processor, a CI workflow).
3. Stale references — commands, URLs, or setup steps that no longer work or point to things that don't exist.

Do not flag:

• Prose descriptions of what the app does (subjective — leave to the human).
• Stylistic preferences (heading structure, badge choices, etc.).
• Items that are genuinely optional to document.

Step 3: Present findings

CHECKPOINT: Present the findings report to the user. Format:

README Refresh — Findings
==========================

Outdated (N items):
  ✗ Ruby version: README says 3.3.0, project uses 4.0.1
  ✗ Rails version: README says 7.1, Gemfile.lock shows 8.0.1
  ✗ References Redis for caching, but project uses Solid Cache

Missing (N items):
  + bin/dev script not documented (starts Procfile.dev with foreman)
  + Postmark configured for transactional email — not mentioned
  + GitHub Actions CI workflow exists — not documented

Stale references (N items):
  ⚠ Setup step 3 references `rake db:seed` — project uses `bin/rails db:seed`
  ⚠ Link to API docs points to a 404

No issues found: (list any sections that are current and accurate)

Ask: "Want me to apply the mechanical fixes? I'll update versions, add missing sections, and remove stale references. I won't rewrite prose descriptions."

Step 4: Apply fixes

For each confirmed finding:

• Outdated versions/facts: Update to the verified value from Step 1.
• Missing sections: Add a concise section with the verified information. Match the existing README's style and heading level conventions.
• Stale references: Fix or remove. If a command changed, update it. If a link is dead and no replacement is obvious, comment it out with a note.

After applying changes:

• Show a diff summary of what was changed.
• Do not commit automatically — let the user review and commit when ready (or offer to commit it for them).

Bootstrap Mode

Step 5: Scan the project

Run the same scan as Step 1 to gather project facts.