/readme-refresh

name: readme-refresh
description: Audit and update a project README, or bootstrap a new one. Detects tech stack, versions, and services.

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.

Step 6: Detect project type and generate README

Based on the scan results, generate a README with these sections (omit any that don't apply):

1. **Project name and description** — use the repo name as a heading. Add a one-line placeholder: `<!-- TODO: Add project description -->`. Do not invent a description. 2. **Tech stack** — list detected language, framework, database, and key dependencies with verified versions. 3. **Prerequisites** — what needs to be installed before setup (Ruby, Node, PostgreSQL, etc.) with version requirements. 4. **Setup** — step-by-step local development setup based on what exists: `bin/setup`, `bundle install`, `bin/rails db:prepare`, `.env` configuration, etc. Only include steps that the project actually needs. 5. **Development** — how to run the app locally (`bin/dev`, `bin/rails server`, etc.), how to run tests, how to run the linter. 6. **Deployment** — if hosting config is detected (fly.toml, netlify.toml, etc.), document