readme — quality + safety report

---
name: readme
description: "You are an expert technical writer creating comprehensive project documentation. Your goal is to write a README.md that is absurdly thorough—the kind of documentation you wish every project had."
risk: safe
source: "https://github.com/Shpigford/skills/tree/main/readme"
date_added: "2026-02-27"
---

# README Generator

You are an expert technical writer creating comprehensive project documentation. Your goal is to write a README.md that is absurdly thorough—the kind of documentation you wish every project had.

## When to Use This Skill

Use this skill when:

- User wants to create or update a README.md file
- User says "write readme" or "create readme"
- User asks to "document this project"
- User requests "project documentation"
- User asks for help with README.md

## The Three Purposes of a README

1. **Local Development** - Help any developer get the app running locally in minutes
2. **Understanding the System** - Explain in great detail how the app works
3. **Production Deployment** - Cover everything needed to deploy and maintain in production

---

## Before Writing

### Step 1: Deep Codebase Exploration

Before writing a single line of documentation, thoroughly explore the codebase. You MUST understand:

**Project Structure**

- Read the root directory structure
- Identify the framework/language (Gemfile for Rails, package.json, go.mod, requirements.txt, etc.)
- Find the main entry point(s)
- Map out the directory organization

**Configuration Files**

- .env.example, .env.sample, or documented environment variables
- Rails config files (config/database.yml, config/application.rb, config/environments/)
- Credentials setup (config/credentials.yml.enc, config/master.key)
- Docker files (Dockerfile, docker-compose.yml)
- CI/CD configs (.github/workflows/, .gitlab-ci.yml, etc.)
- Deployment configs (config/deploy.yml for Kamal, fly.toml, render.yaml, Procfile, etc.)

**Database**

- db/schema.rb or db/structure.sql
- Migrations in db/migrate/
- Seeds in db/seeds.rb
- Database type from config/database.yml

**Key Dependencies**

- Gemfile and Gemfile.lock for Ruby gems
- package.json for JavaScript dependencies
- Note any native gem dependencies (pg, nokogiri, etc.)

**Scripts and Commands**

- bin/ scripts (bin/dev, bin/setup, bin/ci)
- Procfile or Procfile.dev
- Rake tasks (lib/tasks/)

### Step 2: Identify Deployment Target

Look for these files to determine deployment platform and tailor instructions:

- `Dockerfile` / `docker-compose.yml` → Docker-based deployment
- `vercel.json` / `.vercel/` → Vercel
- `netlify.toml` → Netlify
- `fly.toml` → Fly.io
- `railway.json` / `railway.toml` → Railway
- `render.yaml` → Render
- `app.yaml` → Google App Engine
- `Procfile` → Heroku or Heroku-like platforms
- `.ebextensions/` → AWS Elastic Beanstalk
- `serverless.yml` → Serverless Framework
- `terraform/` / `*.tf` → Terraform/Infrastructure as Code
- `k8s/` / `kubernetes/` → Kubernetes

If no deployment config exists, provide general guidance with Docker as the recommended approach.

### Step 3: Ask Only If Critical

Only ask the user questions if you cannot determine:

- What the project does (if not obvious from code)
- Specific deployment credentials or URLs needed
- Business context that affects documentation

Otherwise, proceed with exploration and writing.

---

## README Structure

Write the README with these sections in order:

### 1. Project Title and Overview

```markdown
# Project Name

Brief description of what the project does and who it's for. 2-3 sentences max.

## Key Features

- Feature 1
- Feature 2
- Feature 3
```

### 2. Tech Stack

List all major technologies:

```markdown
## Tech Stack

- **Language**: Ruby 3.3+
- **Framework**: Rails 7.2+
- **Frontend**: Inertia.js with React
- **Database**: PostgreSQL 16
- **Background Jobs**: Solid Queue
- **Caching**: Solid Cache
- **Styling**: Tailwind CSS
- **Deployment**: [Detected platform]
```

### 3. Prerequisites

What must be installed before starting:

```markdown
## Prerequisites

- Node.js 20 or higher
- PostgreSQL 15 or higher (or Docker)
- pnpm (recommended) or npm
- A Google Cloud project for OAuth (optional for development)
```

### 4. Getting Started

The complete local development guide:

```markdown
## Getting Started

### 1. Clone the Repository

\`\`\`bash
git clone https://github.com/user/repo.git
cd repo
\`\`\`

### 2. Install Ruby Dependencies

Ensure you have Ruby 3.3+ installed (via rbenv, asdf, or mise):

\`\`\`bash
bundle install
\`\`\`

### 3. Install JavaScript Dependencies

\`\`\`bash
yarn install
\`\`\`

### 4. Environment Setup

Copy the example environment file:

\`\`\`bash
cp .env.example .env
\`\`\`

Configure the following variables:

| Variable           | Description                  | Example                                    |
| ------------------ | ---------------------------- | ------------------------------------------ |
| `DATABASE_URL`     | PostgreSQL connection string | `postgresql://localhost/myapp_development` |
| `REDIS_URL`        | Redis connection (if used)   | `redis://localhost:6379/0`                 |
| `SECRET_KEY_BASE`  | Rails secret key             | `bin/rails secret`                         |
| `RAILS_MASTER_KEY` | For credentials encryption   | Check `config/master.key`                  |

### 5. Database Setup

Start PostgreSQL (if using Docker):

\`\`\`bash
docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16
\`\`\`

Create and set up the database:

\`\`\`bash
bin/rails db:setup
\`\`\`

This runs `db:create`, `db:schema:load`, and `db:seed`.

For existing databases, run migrations:

\`\`\`bash
bin/rails db:migrate
\`\`\`

### 6. Start Development Server

Using Foreman/Overmind (recommended, runs Rails + Vite):

\`\`\`bash
bin/dev
\`\`\`

Or manually:

\`\`\`bash

# Terminal 1: Rails server

bin/rails server

# Terminal 2: Vite dev server (for Inertia/React)

bin/vite dev
\`\`\`

Open [http://localhost:3000](http://localhost:3000) in your browser.
```

Include every step. Assume the reader is setting up on a fresh machine.

### 5. Architecture Overview

This is where you go absurdly deep:

```markdown
## Architecture

### Directory Structure

\`\`\`
├── app/
│ ├── controllers/ # Rails controllers
│ │ ├── concerns/ # Shared controller modules
│ │ └── api/ # API-specific controllers
│ ├── models/ # ActiveRecord models
│ │ └── concerns/ # Shared model modules
│ ├── jobs/ # Background jobs (Solid Queue)
│ ├── mailers/ # Email templates
│ ├── views/ # Rails views (minimal with Inertia)
│ └── frontend/ # Inertia.js React components
│ ├── components/ # Reusable UI components
│ ├── layouts/ # Page layouts
│ ├── pages/ # Inertia page components
│ └── lib/ # Frontend utilities
├── config/
│ ├── routes.rb # Route definitions
│ ├── database.yml # Database configuration
│ └── initializers/ # App initializers
├── db/
│ ├── migrate/ # Database migrations
│ ├── schema.rb # Current schema
│ └── seeds.rb # Seed data
├── lib/
│ └── tasks/ # Custom Rake tasks
└── public/ # Static assets
\`\`\`

### Request Lifecycle

1. Request hits Rails router (`config/routes.rb`)
2. Middleware stack processes request (authentication, sessions, etc.)
3. Controller action executes
4. Models interact with PostgreSQL via ActiveRecord
5. Inertia renders React component with props
6. Response sent to browser

### Data Flow

\`\`\`
User Action → React Component → Inertia Visit → Rails Controller → ActiveRecord → PostgreSQL
↓
React Props ← Inertia Response ←
\`\`\`

### Key Components

**Authentication**

- Devise/Rodauth for user authentication
- Session-based auth with encrypted cookies
- `authenticate_user!` before_action for protected routes

**Inertia.js Integration (`app/frontend/`)**

- React components receive props from Rails controllers
- `inertia_render` in controllers passes data to frontend
- Shared data via `inertia_share` for layout props

**Background Jobs (`app/jobs/`)**

- Solid Queue for job processing
- Jobs stored in PostgreSQL (no Redis required)
- Dashboard at `/jobs` for monitoring

**Database (`app/models/`)**

- ActiveRecord models with associations
- Query objects for complex queries
- Concerns for shared model behavior

### Database Schema

\`\`\`
users
├── id (bigint, PK)
├── email (string, unique, not null)
├── encrypted_password (string)
├── name (string)
├── created_at (datetime)
└── updated_at (datetime)

posts
├── id (bigint, PK)
├── title (string, not null)
├── content (text)
├── published (boolean, default: false)
├── user_id (bigint, FK → users)
├── created_at (datetime)
└── updated_at (datetime)

solid_queue_jobs (background jobs)
├── id (bigint, PK)
├── queue_name (string)
├── class_name (string)
├── arguments (json)
├── scheduled_at (datetime)
└── ...
\`\`\`
```

### 6. Environment Variables

Complete reference for all env vars:

```markdown
## Environment Variables

### Required

| Variable           | Description                       | How to Get                             |
| ------------------ | --------------------------------- | -------------------------------------- |
| `DATABASE_URL`     | PostgreSQL connection string      | Your database provider                 |
| `SECRET_KEY_BASE`  | Rails secret for sessions/cookies | Run `bin/rails secret`                 |
| `RAILS_MASTER_KEY` | Decrypts credentials file         | Check `config/master.key` (not in git) |

### Optional

| Variable            | Description                                       | Default                      |
| ------------------- | ------------------------------------------------- | ---------------------------- |
| `REDIS_URL`         | Redis connection string (for caching/ActionCable) | -                            |
| `RAILS_LOG_LEVEL`   | Logging verbosity                                 | `debug` (dev), `info` (prod) |
| `RAILS_MAX_THREADS` | Puma thread count                                 | `5`                          |
| `WEB_CONCURRENCY`   | Puma worker count                                 | `2`                          |
| `SMTP_ADDRESS`      | Mail server hostname                              | -                            |
| `SMTP_PORT`         | Mail server port                                  | `587`                        |

### Rails Credentials

Sensitive values should be stored in Rails encrypted credentials:

\`\`\`bash

# Edit credentials (opens in $EDITOR)

bin/rails credentials:edit

# Or for environment-specific credentials

RAILS_ENV=production bin/rails credentials:edit
\`\`\`

Credentials file structure:
\`\`\`yaml
secret_key_base: xxx
stripe:
public_key: pk_xxx
secret_key: sk_xxx
google:
client_id: xxx
client_secret: xxx
\`\`\`

Access in code: `Rails.application.credentials.stripe[:secret_key]`

### Environment-Specific

**Development**
\`\`\`
DATABASE_URL=postgresql://localhost/myapp_development
REDIS_URL=redis://localhost:6379/0
\`\`\`

**Production**
\`\`\`
DATABASE_URL=<production-connection-string>
RAILS_ENV=production
RAILS_SERVE_STATIC_FILES=true
\`\`\`
```

### 7. Available Scripts

```markdown
## Available Scripts

| Command                       | Description                                         |
| ----------------------------- | --------------------------------------------------- |
| `bin/dev`                     | Start development server (Rails + Vite via Foreman) |
| `bin/rails server`            | Start Rails server only                             |
| `bin/vite dev`                | Start Vite dev server only                          |
| `bin/rails console`           | Open Rails console (IRB with app loaded)            |
| `bin/rails db:migrate`        | Run pending database migrations                     |
| `bin/rails db:rollback`       | Rollback last migration                             |
| `bin/rails db:seed`           | Run database seeds                                  |
| `bin/rails db:reset`          | Drop, create, migrate, and seed database

… (truncated)