--- 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: ```text 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: ``. 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. | Project Stage | README Refresh Focus | | ------------- | ----------------------------------------------------------------------------- | | Greenfield | Bootstrap mode. Generate initial README as setup docs solidify. | | MVP complete | Full refresh. The README likely drifted during rapid development. | | Mature | Light periodic refresh. Versions and dependencies are the main drift vectors. | **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.