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.

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 the deployment target and any relevant commands.
7. Services — external services the app depends on (email provider, object storage, background jobs, etc.).
8. Documentation — if a docs/ directory exists, mention it and list key documents (PRD, domain model, etc.).

Step 7: Present and write

CHECKPOINT: Present the generated README to the user for review.

Write the file to README.md at the project root. Do not commit — let the user review and commit when ready.

---

Important

• This skill inspects and reports. It does not refactor code, change configuration, or install dependencies.
• Prose and subjective descriptions are the human's domain. The command handles mechanical, verifiable facts.
• The command is framework-aware but not framework-specific. The scan in Step 1 covers Rails, Node, Python, Go, Rust, and Hugo projects. For unrecognized stacks, fall back to checking common files (Makefile, Dockerfile, docker-compose.yml, README.md).
• When in doubt about whether something belongs in the README, include it in the findings report and let the user decide.
• If the project has a CLAUDE.md, read it for additional context about conventions, but do not document CLAUDE.md itself in the README (it is tooling-specific, not project documentation).

Lifecycle Context

This is a living-document maintenance command (→ See spec-driven-development.md §5 "Document Lifecycle"). The README is never frozen — it evolves with the code.

Suggested cadence: Run after phase boundaries, after /update-deps, or whenever the project feels like it has accumulated untracked changes. A good rule of thumb: if you'd be embarrassed for a new contributor to read the README, it's time.