cwinvestments 📋 SOP Builder: Documenting standard operating procedure...
Generates a structured Standard Operating Procedure with numbered steps, prerequisites, decision points, verification checkpoints, rollback steps, and time estimates.
Activation
When this skill activates, output:
📋 SOP Builder, Identifying process and building procedure...
Then execute the protocol below.
| Context | Status |
|---|---|
| User says "create SOP" or "write SOP" or "document process" | ACTIVE |
| User says "runbook" or "playbook" or "process documentation" | ACTIVE |
| Creating step-by-step instructions for a repeatable workflow | ACTIVE |
| Writing a one-time guide or tutorial | DORMANT |
| Discussing process improvement at a high level | DORMANT |
Anti-patterns
| Trap | Reality Check |
|---|---|
| "The steps are obvious" | What's obvious to you is opaque to a new team member at 2 AM. Write every step. |
| "Just follow the README" | READMEs explain concepts. SOPs give exact actions in exact order. Different purpose. |
| "We'll remember the edge cases" | You won't. Decision points and rollback steps are the whole point of an SOP. |
| "This process never changes" | Every process changes. Version numbers and last-updated dates prevent stale docs from causing outages. |
| "Anyone can figure out if it worked" | Explicit verification checkpoints ("you should see X") catch failures before they cascade. |
Protocol
Step 1: Identify the Process
If the user hasn't specified the process, ask:
What process should this SOP document? For example:
- Deploying to production
- Onboarding a new developer
- Handling a customer bug report
- Running a database migration
- Publishing a release
- Setting up a new project
Then gather:
- Process name: clear, specific title
- Audience: who will follow this SOP? (developer, ops, new hire, non-technical)
- Trigger: what event kicks off this process? (PR merged, customer request, scheduled)
- Frequency: how often is this run? (daily, weekly, per release, ad-hoc)
- Critical?: does failure cause downtime, data loss, or revenue impact?
Step 2: Define Prerequisites
List everything needed before starting:
## Prerequisites
### Required Access
| System | Access Level | How to Request |
|--------|-------------|---------------|
| GitHub | Write access to repo | Ask team lead in #dev-access |
| Railway | Deploy permissions | Railway dashboard → Team → Invite |
| Supabase | Database admin | Supabase dashboard → Settings → Team |
| AWS S3 | Read/write to production bucket | IT ticket #aws-access |
### Required Tools
| Tool | Version | Install Command |
|------|---------|----------------|
| Node.js | 20+ | `nvm install 20` |
| Railway CLI | Latest | `npm install -g @railway/cli` |
| Git | 2.40+ | Pre-installed on most systems |
### Required Knowledge
- Familiarity with [relevant concept]
- Completed [training/onboarding step]
- Access to [documentation/wiki link]
### Before You Begin
- [ ] Verify you have all required access (test each login)
- [ ] Pull latest code from main branch
- [ ] Notify team in [channel] that you're starting this process
- [ ] Block [estimated time] on your calendar
Rules:
- Every tool, login, and permission is listed: no assumptions
- Include "how to get access" for each system (not just "you need access")
- Include a pre-flight checklist the operator runs before step 1
Step 3: Write Numbered Steps
Each step follows a strict format:
## Procedure
### Step 1: [Action verb] [specific thing]
**Time estimate:** ~5 minutes
**Can fail:** Yes
**Action:**
1. Navigate to [specific location]
2. Run the following command:
```bash
npm run build
- Wait for the build to complete (typically 1-3 minutes)
Verification:
- Build output shows "Build successful" with zero errors
-
dist/directory contains updated files - File count is similar to previous build (sanity check)
If it fails:
- Build error with dependency issue → Run
npm ciand retry - Build error with TypeScript type error → Fix the type error, commit, and restart from Step 1
- Build times out (> 10 minutes) → Check for infinite loops in recent changes
**Step writing rules:**
- Start every step title with an **action verb** (Run, Open, Navigate, Verify, Configure)
- No vague steps ("set up the environment"), every action is copy-pasteable or clickable
- Include the **exact command**, **exact URL**, or **exact menu path**
- Mark whether each step **can fail**: if yes, it needs verification and failure handling
- Time estimates help the operator know if something is taking too long
### Step 4: Add Decision Points
For steps with branching logic, use clear if/then formatting:
```markdown
### Step 4: Check migration status
**Time estimate:** ~2 minutes
**Can fail:** Yes
**Action:**
1. Run: `supabase migration list`
2. Review the output
**Decision point:**
| Situation | Action |
|-----------|--------|
| All migrations show `applied` | Continue to Step 5 |
| One migration shows `pending` | Run `supabase db push` then re-check |
| Migration shows `failed` | Stop. Go to Rollback Procedure below |
| Connection refused error | Verify VPN is connected, retry in 30 seconds |
| Unknown error | Screenshot the error, post in #dev-help, wait for response |
**Do NOT continue to Step 5 until all migrations show `applied`.**
Decision point rules:
- Every
can fail: Yesstep gets a decision table - Cover the 3-5 most common failure modes (not just happy path)
- Include "unknown error" row, operators need to know what to do when nothing matches
- Use bold warnings for steps where continuing on failure causes cascading damage
Step 5: Add Verification Checkpoints
Major milestones get dedicated verification steps:
### Checkpoint A: Pre-deployment verification
**Time estimate:** ~3 minutes
Before proceeding to deployment, verify ALL of the following:
| Check | How to Verify | Expected Result |
|-------|--------------|-----------------|
| Build passes | `npm run build` exits cleanly | Exit code 0, no errors |
| Tests pass | `npm test` exits cleanly | All tests green |
| Env vars set | Railway dashboard → Variables | All vars from .env.example present |
| Database ready | `supabase status` | Database is running, migrations applied |
| Branch is clean | `git status` | No uncommitted changes |
**All checks must pass.** If any check fails, resolve it before continuing.
Do not skip checks "because it worked last time."
Checkpoint rules:
- Place checkpoints before irreversible actions (deployment, data migration, public release)
- Every check has a specific command or action to run and an expected result
- Emphasize that ALL checks must pass: no skipping
Step 6: Include Rollback Steps
For any step that modifies state (deployment, data changes, config updates):
## Rollback Procedure
Use this procedure if deployment fails or causes issues in production.
### Rollback Step 1: Revert deployment
**Time estimate:** ~2 minutes
1. Open Railway dashboard → Deployments
2. Find the last successful deployment (green checkmark)
3. Click the three-dot menu → "Rollback to this deploy"
4. Wait for rollback to complete (typically 30-60 seconds)
**Verification:**
- [ ] Railway shows the previous deployment as active
- [ ] Health check endpoint returns 200: `curl https://[app].up.railway.app/health`
- [ ] Users can access the application
### Rollback Step 2: Revert database migration (if applicable)
**Time estimate:** ~5 minutes
1. Run the rollback migration:
```bash
supabase db execute --file supabase/migrations/[number]_rollback.sql
- Verify the schema matches the previous state
WARNING: Database rollbacks may cause data loss if the forward migration added columns that received data. Assess the risk before proceeding.
Rollback Step 3: Notify team
- Post in #incidents: "Rolled back [deployment name]. Investigating [brief issue]."
- Update status page if customer-facing
- Create incident ticket for post-mortem
**Rollback rules:**
- Every deployment/migration step needs a corresponding rollback
- Rollback steps are just as detailed as forward steps
- Include data loss warnings where applicable
- Always end rollback with team notification
### Step 7: Add Time Estimates
Summarize the total time at the top of the document:
```markdown
## Time Summary
| Phase | Estimated Time |
|-------|---------------|
| Prerequisites check | 5 minutes |
| Steps 1-3 (preparation) | 15 minutes |
| Steps 4-6 (execution) | 20 minutes |
| Steps 7-8 (verification) | 10 minutes |
| **Total (happy path)** | **~50 minutes** |
| **Total (with 1 failure + rollback)** | **~75 minutes** |
**Schedule buffer:** Block 1.5x the happy path time on your calendar.
Time estimate rules:
- Include happy path total AND failure path total
- Recommend 1.5x calendar buffer
- Individual step estimates help operators identify if a step is taking too long
Step 8: Assemble Final Document
Output the complete SOP:
# SOP: [Process Name]
| Field | Value |
|-------|-------|
| **Version** | 1.0 |
| **Last updated** | YYYY-MM-DD |
| **Author** | [Name] |
| **Audience** | [Who follows this SOP] |
| **Trigger** | [When to run this process] |
| **Frequency** | [How often] |
| **Estimated time** | [Happy path total] |
| **Critical** | [Yes/No: does failure cause downtime?] |
---
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Procedure](#procedure)
- Step 1: [title]
- Step 2: [title]
- ...
- Checkpoint A: [title]
- Step N: [title]
3. [Rollback Procedure](#rollback-procedure)
4. [Time Summary](#time-summary)
5. [Change Log](#change-log)
---
[Prerequisites section]
[Procedure section with steps, decision points, checkpoints]
[Rollback Procedure section]
[Time Summary section]
---
## Change Log
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | YYYY-MM-DD | [Name] | Initial version |
Output summary:
📋 SOP Builder: Complete
Process: [name]
Audience: [who]
Steps: [count] steps, [count] decision points, [count] checkpoints
Rollback: [count] rollback steps
Estimated time: [happy path] / [with failure]
Document: [word count] words
Next steps:
1. Review steps with someone who runs this process
2. Do a dry run following the SOP exactly
3. Store in team wiki/docs and link from relevant README
4. Schedule quarterly review to keep it current
Level History
- Lv.1: Base: Process identification, prerequisites with access/tools, numbered steps with action verbs, decision point tables, verification checkpoints, rollback procedures, time estimates, versioned final document with change log. (Origin: MemStack Pro v3.2, Mar 2026)