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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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.
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
Local Development - Help any developer get the app running locally in minutes
Understanding the System - Explain in great detail how the app works
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
## 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:
## 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:
## 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 Lifecycle1. 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)
โโโ ...
\`\`\`
## 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 |
| `bin/rails routes` | List all routes |
| `bin/rails test` | Run test suite (Minitest) |
| `bundle exec rspec` | Run test suite (RSpec, if used) |
| `bin/rails assets:precompile` | Compile assets for production |
| `bin/rubocop` | Run Ruby linter |
| `yarn lint` | Run JavaScript/TypeScript linter |
8. Testing
## Testing### Running Tests
\`\`\`bash
# Run all tests (Minitest)
bin/rails test
# Run all tests (RSpec, if used)
bundle exec rspec
# Run specific test file
bin/rails test test/models/user_test.rb
bundle exec rspec spec/models/user_spec.rb
# Run tests matching a pattern
bin/rails test -n /creates_user/
bundle exec rspec -e "creates user"
# Run system tests (browser tests)
bin/rails test:system
# Run with coverage (SimpleCov)
COVERAGE=true bin/rails test
\`\`\`
### Test Structure
\`\`\`
test/ # Minitest structure
โโโ controllers/ # Controller tests
โโโ models/ # Model unit tests
โโโ integration/ # Integration tests
โโโ system/ # System/browser tests
โโโ fixtures/ # Test data
โโโ test_helper.rb # Test configuration
spec/ # RSpec structure (if used)
โโโ models/
โโโ requests/
โโโ system/
โโโ factories/ # FactoryBot factories
โโโ support/
โโโ rails_helper.rb
\`\`\`
### Writing Tests
**Minitest example:**
\`\`\`ruby
require "test_helper"
class UserTest < ActiveSupport::TestCase
test "creates user with valid attributes" do
user = User.new(email: "test@example.com", name: "Test User")
assert user.valid?
end
test "requires email" do
user = User.new(name: "Test User")
assert_not user.valid?
assert_includes user.errors[:email], "can't be blank"
end
end
\`\`\`
**RSpec example:**
\`\`\`ruby
require "rails_helper"
RSpec.describe User, type: :model do
describe "validations" do
it "is valid with valid attributes" do
user = build(:user)
expect(user).to be_valid
end
it "requires an email" do
user = build(:user, email: nil)
expect(user).not_to be_valid
expect(user.errors[:email]).to include("can't be blank")
end
end
end
\`\`\`
### Frontend Testing
For Inertia/React components:
\`\`\`bash
yarn test
\`\`\`
\`\`\`typescript
import { render, screen } from '@testing-library/react'
import { Dashboard } from './Dashboard'
describe('Dashboard', () => {
it('renders user name', () => {
render(<Dashboarduser={{name: 'Josh' }} />)
expect(screen.getByText('Josh')).toBeInTheDocument()
})
})
\`\`\`
9. Deployment
Tailor this to detected platform (look for Dockerfile, fly.toml, render.yaml, kamal/, etc.):
## Deployment### Kamal (Recommended for Rails)
If using Kamal for deployment:
\`\`\`bash
# Setup Kamal (first time)
kamal setup
# Deploy
kamal deploy
# Rollback to previous version
kamal rollback
# View logs
kamal app logs
# Run console on production
kamal app exec --interactive 'bin/rails console'
\`\`\`
Configuration lives in `config/deploy.yml`.
### Docker
Build and run:
\`\`\`bash
# Build image
docker build -t myapp .
# Run with environment variables
docker run -p 3000:3000 \
-e DATABASE_URL=postgresql://... \
-e SECRET_KEY_BASE=... \
-e RAILS_ENV=production \
myapp
\`\`\`
### Heroku
\`\`\`bash
# Create app
heroku create myapp
# Add PostgreSQL
heroku addons:create heroku-postgresql:mini
# Set environment variables
heroku config:set SECRET_KEY_BASE=$(bin/rails secret)
heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)
# Deploy
git push heroku main
# Run migrations
heroku run bin/rails db:migrate
\`\`\`
### Fly.io
\`\`\`bash
# Launch (first time)
fly launch
# Deploy
fly deploy
# Run migrations
fly ssh console -C "bin/rails db:migrate"
# Open console
fly ssh console -C "bin/rails console"
\`\`\`
### Render
If `render.yaml` exists, connect your repo to Render and it will auto-deploy.
Manual setup:
1. Create new Web Service
2. Connect GitHub repository
3. Set build command: `bundle install && bin/rails assets:precompile`4. Set start command: `bin/rails server`5. Add environment variables in dashboard
### Manual/VPS Deployment
\`\`\`bash
# On the server:# Pull latest code
git pull origin main
# Install dependencies
bundle install --deployment
# Compile assets
RAILS_ENV=production bin/rails assets:precompile
# Run migrations
RAILS_ENV=production bin/rails db:migrate
# Restart application server (e.g., Puma via systemd)
sudo systemctl restart myapp
\`\`\`
10. Troubleshooting
## Troubleshooting### Database Connection Issues**Error:**`could not connect to server: Connection refused`**Solution:**1. Verify PostgreSQL is running: `pg_isready` or `docker ps`2. Check `DATABASE_URL` format: `postgresql://USER:PASSWORD@HOST:PORT/DATABASE`3. Ensure database exists: `bin/rails db:create`### Pending Migrations**Error:**`Migrations are pending`**Solution:**
\`\`\`bash
bin/rails db:migrate
\`\`\`
### Asset Compilation Issues**Error:**`The asset "application.css" is not present in the asset pipeline`**Solution:**
\`\`\`bash
# Clear and recompile assets
bin/rails assets:clobber
bin/rails assets:precompile
\`\`\`
### Bundle Install Failures**Error:** Native extension build failures
**Solution:**1. Ensure system dependencies are installed:
\`\`\`bash
# macOS
brew install postgresql libpq
# Ubuntu
sudo apt-get install libpq-dev
\`\`\`
2. Try again: `bundle install`### Credentials Issues**Error:**`ActiveSupport::MessageEncryptor::InvalidMessage`**Solution:**
The master key doesn't match the credentials file. Either:
1. Get the correct `config/master.key` from another team member
2. Or regenerate credentials: `rm config/credentials.yml.enc && bin/rails credentials:edit`### Vite/Inertia Issues**Error:**`Vite Ruby - Build failed`**Solution:**
\`\`\`bash
# Clear Vite cache
rm -rf node_modules/.vite
# Reinstall JS dependencies
rm -rf node_modules && yarn install
\`\`\`
### Solid Queue Issues**Error:** Jobs not processing
**Solution:**
Ensure the queue worker is running:
\`\`\`bash
bin/jobs
# or
bin/rails solid_queue:start
\`\`\`
11. Contributing (Optional)
Include if open source or team project.
12. License (Optional)
Writing Principles
Be Absurdly Thorough - When in doubt, include it. More detail is always better.
Use Code Blocks Liberally - Every command should be copy-pasteable.
Show Example Output - When helpful, show what the user should expect to see.
Explain the Why - Don't just say "run this command," explain what it does.
Assume Fresh Machine - Write as if the reader has never seen this codebase.
Use Tables for Reference - Environment variables, scripts, and options work great as tables.
Keep Commands Current - Use pnpm if the project uses it, npm if it uses npm, etc.
Include a Table of Contents - For READMEs over ~200 lines, add a TOC at the top.
Output Format
Generate a complete README.md file with:
Proper markdown formatting
Code blocks with language hints (bash, typescript, etc.)
Tables where appropriate
Clear section hierarchy
Linked table of contents for long documents
Write the README directly to README.md in the project root.
Limitations
Use this skill only when the task clearly matches the scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
