Processes documented in wikis get forgotten. Steps.md captures your development workflows, deployment procedures, and operational checklists in versioned markdown that lives alongside your code and stays current through pull request review.
Structure your SOPs with clear steps, decision points, and verification checks. AI assistants can guide team members through complex procedures, catch missed steps, and suggest improvements based on documented outcomes.
Well-documented processes do not just ensure consistency - they become the foundation for automation. Every workflow captured in structured markdown is a workflow that can eventually run itself.
Transform tribal knowledge into executable workflows with structured markdown that ensures consistency and enables continuous improvement.
Use explicit numbered steps, not paragraphs of description. Each step should be a single action that can be verified as done or not done. Numbered steps are unambiguous and AI assistants can track progress through them.
When a workflow branches based on conditions, make the decision criteria explicit. "If tests pass, proceed to step 5. If tests fail, go to step 8." Decision points without clear criteria lead to inconsistent execution.
After critical steps, include a verification command or expected output. "Run npm test - expect all green. If any failures, stop and investigate before proceeding." Verification prevents cascading errors.
Every deployment workflow needs a rollback section. Document exact rollback steps, how to verify rollback success, and when to escalate. The time to write rollback docs is before you need them, not during an incident.
Note expected time for long-running steps - "Build takes approximately 3 minutes" or "DNS propagation requires 15-30 minutes." Time estimates help operators distinguish normal delays from stuck processes.
Tag each step with who executes it - developer, tech lead, DevOps, QA. Multi-person workflows fail when handoff points are unclear. Explicit role assignment prevents steps from falling through the cracks.
When you modify a workflow, add a change note with date and reason. Process evolution history helps teams understand why steps were added or removed and prevents regression to problematic older patterns.
Mark steps that could be automated with a tag or annotation. Well-documented manual steps are the easiest to automate because the logic is already explicit. Automation is documentation's natural endpoint.
When people skip steps or work around a documented process, the problem is rarely laziness - it is usually that the documentation is unclear, outdated, or missing critical context. Instead of enforcing compliance, improve the documentation. Add the missing context, clarify the ambiguous steps, and remove the unnecessary ones. The best processes are the ones that people follow naturally because the steps are clear, the reasoning is documented, and the value is obvious.
# Steps.md - Process and Workflow Documentation
<!-- Step-by-step procedures for deployment, incidents, releases, and operations -->
<!-- Runbook-style documentation that anyone on the team can follow under pressure -->
<!-- Last updated: YYYY-MM-DD -->
## Deployment Checklist
### Pre-Deployment (Before Merging to Main)
**Developer responsibilities** - complete before requesting deployment approval:
- [ ] **Code review approved** - at least 1 approval from a code owner
- [ ] **All CI checks pass** - lint, type-check, unit tests, integration tests, build
- [ ] **Manual testing completed** - tested the feature locally against acceptance criteria
- [ ] **Database migration tested** - ran migration on a copy of staging data, verified rollback works
- [ ] **Environment variables documented** - any new env vars added to `.env.example` and deployment docs
- [ ] **Feature flag configured** - new features behind a flag for gradual rollout (if applicable)
- [ ] **Monitoring updated** - dashboards and alerts cover the new functionality
- [ ] **Documentation updated** - API docs, README, runbook, or user-facing docs as needed
- [ ] **Changelog entry added** - description of changes for the release notes
- [ ] **Rollback plan written** - specific steps to undo this change if something goes wrong
### Deployment Execution
**Deployer responsibilities** - the person who triggers the production deployment:
1. **Announce deployment** in #deploys: "Starting deployment of [PR #/feature name]. ETA: 15 minutes."
2. **Merge PR to main** - squash merge, verify the commit lands on main
3. **Monitor CI/CD pipeline** - watch GitHub Actions for build and deploy stages
4. **Verify staging deployment** (if applicable):
- Run smoke tests against staging: `npm run test:smoke -- --env staging`
- Spot-check the feature manually in the staging environment
- Verify no new errors in Datadog/Sentry for staging
5. **Promote to production** (manual gate or auto-deploy depending on config)
6. **Monitor production** for 15 minutes after deployment:
- Watch error rates in Datadog (should stay below 0.1%)
- Check latency percentiles (p50, p95 should not increase by more than 10%)
- Verify the deployed feature works with a manual check
- Monitor the #incidents channel for user reports
7. **Announce completion** in #deploys: "Deployment complete. [PR #/feature name] is live."
### Post-Deployment Verification
- [ ] Feature accessible in production
- [ ] Error rates stable (compare to pre-deployment baseline)
- [ ] Performance metrics within acceptable range
- [ ] Feature flag toggled for initial rollout group (if applicable)
- [ ] No user-facing error reports in first 30 minutes
### Rollback Procedure
If something goes wrong after deployment:
```bash
# Step 1: Revert the commit on main
git revert [commit-hash] --no-edit
git push origin main
# Step 2: CI/CD auto-deploys the revert (monitor pipeline)
# Step 3: If database migration was involved:
npm run db:migrate:rollback
# Verify application works with the previous schema
# Step 4: Announce in #deploys and #incidents:
# "Rolled back [feature]. Investigating. No user action needed."
# Step 5: Create a post-mortem ticket if the issue affected users
```
**Decision framework for rollback**: Roll back immediately if any of these are true:
- Error rate > 1% (normal baseline is < 0.1%)
- P95 latency > 2x normal
- Any user-facing data integrity issue
- Security vulnerability discovered
- Payment processing affected
## Incident Response
### Severity Levels
| Level | Description | Response Time | Examples |
|-------|-------------|---------------|---------|
| P0 - Critical | Service down, data loss, security breach | 15 minutes | Full outage, payment processing broken, data leak |
| P1 - High | Major feature broken, significant user impact | 30 minutes | Dashboard not loading, authentication failing, search broken |
| P2 - Medium | Feature degraded, workaround available | 4 hours | Slow queries, intermittent errors, export failing |
| P3 - Low | Minor issue, minimal user impact | Next business day | UI glitch, non-critical error in logs, cosmetic bug |
### Incident Response Steps
#### Step 1: Detect and Alert (0-5 minutes)
- Automated alert fires (Datadog, Sentry, PagerDuty) OR user report received
- On-call engineer acknowledges the alert
- Create incident channel: #incident-YYYY-MM-DD-brief-description
#### Step 2: Assess Severity (5-10 minutes)
```
Questions to answer:
1. How many users are affected? (all / subset / single)
2. Is data being lost or corrupted? (yes / no / unknown)
3. Is there a workaround? (yes / no)
4. Is this a security issue? (yes / no)
5. What changed recently? (deployment / config change / external)
```
Assign severity level based on answers. Escalate P0/P1 to engineering lead.
#### Step 3: Investigate (10-30 minutes)
```bash
# Check recent deployments
git log --oneline -10
# Check application logs
# Datadog: Filter by service, time range, error level
# Check infrastructure
# AWS Console: EC2/ECS health, RDS metrics, Redis metrics
# Check external dependencies
# Status pages: Stripe, Auth0, AWS, Cloudflare
```
#### Step 4: Mitigate (As Soon as Root Cause Identified)
- **If caused by recent deployment**: Roll back immediately (see rollback procedure above)
- **If caused by external service**: Enable fallback mode, notify affected users
- **If caused by data issue**: Stop the bleeding first (disable writes if needed), then fix
- **If cause is unknown**: Add more logging, monitor closely, prepare to escalate
#### Step 5: Resolve and Verify (Once Fix is Applied)
- Verify error rates return to normal
- Confirm affected users can use the feature
- Update incident channel with resolution
- Stand down from incident response
#### Step 6: Post-Mortem (Within 48 Hours)
```markdown
# Post-Mortem: [Incident Title]
Date: YYYY-MM-DD
Duration: [Start time] - [End time] ([X] minutes)
Severity: [P0-P3]
Authored by: [On-call engineer]
## Summary
[1-2 sentence description of what happened]
## Impact
- Users affected: [number or percentage]
- Duration: [X minutes/hours]
- Revenue impact: [if applicable]
## Timeline
- [HH:MM] Alert fired / user report received
- [HH:MM] On-call acknowledged
- [HH:MM] Root cause identified
- [HH:MM] Fix deployed
- [HH:MM] Verified resolution
## Root Cause
[Detailed technical explanation]
## What Went Well
- [Thing that helped]
## What Could Be Improved
- [Thing that slowed us down]
## Action Items
- [ ] [Preventive action] - Owner: [Name] - Due: [Date]
- [ ] [Monitoring improvement] - Owner: [Name] - Due: [Date]
- [ ] [Process improvement] - Owner: [Name] - Due: [Date]
```
## Feature Development Workflow
### From Idea to Production
```
1. Product Brief (PM) -> Word.md / product requirements
2. Technical Design (Engineer) -> Spider.md / SPEC + PSEUDOCODE
3. Estimation (Team) -> Story points in sprint planning
4. Implementation (Engineer) -> Feature branch + PR
5. Code Review (Team) -> PR review + approval
6. QA Testing (QA/Engineer) -> Staging deployment + test plan
7. Deployment (Engineer) -> Production deployment (this doc)
8. Monitoring (Team) -> 48-hour watch period
9. Retrospective (Team) -> Lessons learned
```
### Sprint Ceremonies
| Ceremony | When | Duration | Purpose |
|----------|------|----------|---------|
| Sprint Planning | Monday 10 AM | 1 hour | Select and estimate work for the sprint |
| Daily Standup | Daily 10 AM | 15 min | Sync on progress and blockers |
| Mid-Sprint Check | Wednesday 2 PM | 30 min | Course-correct if behind schedule |
| Sprint Review | Friday 3 PM (every 2 weeks) | 30 min | Demo completed work to stakeholders |
| Retrospective | Friday 3:30 PM (every 2 weeks) | 30 min | Process improvement |
## Release Process
### Semantic Versioning
```
MAJOR.MINOR.PATCH
MAJOR: Breaking API changes, major UI redesign, database incompatibility
MINOR: New features, non-breaking API additions
PATCH: Bug fixes, performance improvements, documentation updates
Examples:
2.0.0 - Redesigned dashboard, new GraphQL API (breaking)
1.5.0 - Added team billing feature
1.4.3 - Fixed timezone bug in event timestamps
```
### Release Steps
1. **Create release branch**: `git checkout -b release/v1.5.0`
2. **Update version**: Bump version in `package.json`
3. **Update changelog**: Add release notes to `CHANGELOG.md`
4. **Final testing**: Run full test suite on release branch
5. **Create PR**: Release branch -> main
6. **Get approval**: Release manager + 1 engineer approve
7. **Merge and tag**: Merge PR, create git tag `v1.5.0`
8. **Deploy**: Tag triggers production deployment via CI/CD
9. **Announce**: Post release notes in #releases and email stakeholders
10. **Monitor**: Watch production metrics for 24 hours
### Hotfix Process
For urgent production fixes that cannot wait for the next release:
```bash
# 1. Branch from main (not from develop/staging)
git checkout main
git pull origin main
git checkout -b hotfix/v1.4.4-fix-payment-webhook
# 2. Make the minimal fix (smallest possible change)
# 3. Add a test that covers the bug
# 4. Create PR with [HOTFIX] prefix in the title
# 5. Fast-track review (1 approval, can be from any engineer)
# 6. Merge to main AND cherry-pick to develop/staging
# 7. Deploy immediately
# 8. Write post-mortem if it was a P0/P1 incident
```
## Code Review Steps
### Author Checklist (Before Requesting Review)
- [ ] PR title follows commit convention: `feat/fix/refactor: description`
- [ ] PR description explains WHAT changed and WHY
- [ ] Self-reviewed the diff - no debug code, no commented-out blocks
- [ ] Tests added or updated for the change
- [ ] No unrelated changes included (keep PRs focused)
- [ ] Screenshots included for UI changes
- [ ] Breaking changes documented in PR description
### Reviewer Workflow
1. **Read the PR description first** - understand the goal before reading code
2. **Check the test plan** - are the right scenarios covered?
3. **Review the diff file by file** - start with the most important files
4. **Leave comments with prefixes** - nit/suggestion/concern/blocker/praise
5. **Approve or request changes** - do not leave reviews in "comment only" state
6. **Respond within 4 hours** - unblocking teammates is a priority
### Review Turnaround Expectations
| PR Size | Expected Review Time |
|---------|---------------------|
| Small (<50 lines) | Same day |
| Medium (50-200 lines) | Within 4 hours |
| Large (200-500 lines) | Within 1 business day |
| XL (500+ lines) | Schedule a walkthrough first |
## On-Call Procedures
### On-Call Rotation
- **Rotation**: Weekly, Monday 9 AM to Monday 9 AM
- **Schedule**: [Link to PagerDuty/OpsGenie schedule]
- **Handoff**: Outgoing on-call briefs incoming on any ongoing issues
- **Escalation**: If on-call cannot resolve within 30 minutes, escalate to engineering lead
### On-Call Responsibilities
1. **Respond to alerts** within the SLA for each severity level
2. **Triage user reports** in #support and #incidents channels
3. **Keep stakeholders updated** during active incidents (every 30 minutes for P0/P1)
4. **Write post-mortems** for any P0/P1 incidents during your shift
5. **Hand off cleanly** - document any ongoing issues for the next on-call
### On-Call Toolkit
```bash
# Quick health check
curl https://api.yourapp.com/health
# Should return: {"status": "ok", "version": "1.5.0"}
# Check application logs (last 30 minutes)
# Datadog: [link to saved search]
# Check database health
# RDS Console: [link to dashboard]
# Check deployment status
# ArgoCD: [link to dashboard]
# Emergency contact list
# Engineering Lead: [phone]
# VP Engineering: [phone] (P0 only)
# AWS Support: [case portal link]
```
## Database Migration Procedures
### Standard Migration
```bash
# 1. Create the migration
pnpm db:migrate:create --name add_team_billing_tables
# 2. Write the migration SQL (up and down)
# Edit the generated file in prisma/migrations/
# 3. Test locally
pnpm db:migrate # Apply
pnpm db:migrate:rollback # Rollback
pnpm db:migrate # Re-apply to verify both directions work
# 4. Test on staging data copy
pg_dump staging_db > staging_copy.sql
psql test_db < staging_copy.sql
pnpm db:migrate # Apply migration to staging data copy
# Verify data integrity
# 5. Include in PR - migration runs automatically during deployment
```
### High-Risk Migration (Large Tables, Schema Changes)
For migrations that affect tables with 1M+ rows or change column types:
1. **Schedule maintenance window** - notify users 48 hours in advance
2. **Take a full backup** before running the migration
3. **Run migration on a staging copy** first and measure execution time
4. **Use online schema change tools** if migration takes > 5 minutes
5. **Monitor during execution** - watch lock waits, replication lag, disk I/O
6. **Verify application compatibility** - the app must work with both old and new schema during rollout
7. **Keep rollback script ready** - tested and verified before the migration window
## Process Improvement
### Retrospective Template
```markdown
# Sprint [X] Retrospective
Date: YYYY-MM-DD
Facilitator: [Name]
Attendees: [Names]
## What Went Well
- [Item 1]
- [Item 2]
## What Could Be Improved
- [Item 1]
- [Item 2]
## Action Items (max 3 per retro)
- [ ] [Specific, actionable item] - Owner: [Name] - Due: [Date]
- [ ] [Specific, actionable item] - Owner: [Name] - Due: [Date]
## Follow-up on Previous Action Items
- [x] [Completed item from last retro]
- [ ] [Still in progress - update on status]
```
### Continuous Improvement Metrics
Track these monthly to measure process health:
| Metric | Target | How to Measure |
|--------|--------|---------------|
| Deployment frequency | 5+/week | Count merges to main |
| Lead time for changes | < 3 days | PR open to production |
| Change failure rate | < 5% | Rollbacks / total deployments |
| Mean time to recovery | < 30 min | Incident start to resolution |
| PR review turnaround | < 4 hours | Time from review request to first review |
Workflows documented in wikis get forgotten. Steps.md captures your development processes, SOPs, and checklists in versioned markdown. AI assistants can guide team members through complex procedures. Process knowledge becomes executable context that scales.
Every deployment, incident response, and code review follows patterns. Steps.md documents these patterns as structured workflows. Your AI assistant helps enforce consistency and catch missing steps. Process improvement becomes continuous and data-driven.
Well-documented processes can be automated. Steps.md provides the structured documentation that makes workflows programmable. From feature development to production deployment, your procedures become AI-readable instructions. Manual processes evolve into automated pipelines.
"Elite teams don't just have processes - they have processes documented as executable context. Steps.md helps you capture workflows in markdown, making them accessible to both humans and AI assistants who can guide execution and suggest improvements."
Built by process engineers who believe great workflows deserve great documentation.
We are committed to helping teams recognize that processes documented in wikis get ignored. Development workflows, deployment procedures, and incident response playbooks belong in .md files - versioned, tested, and improved. When process knowledge lives as markdown, AI assistants can guide execution, catch missing steps, and suggest optimizations. Process documentation becomes process automation.
Our vision is that every team has their critical workflows captured as executable markdown. From feature planning to production deployment, your SOPs become AI-readable instructions that ensure consistency and enable continuous improvement. Well-documented processes don't just scale - they evolve intelligently.
LLMs parse markdown better than any other format. Fewer tokens, cleaner structure, better results.
Context evolves with code. Git tracks changes, PRs enable review, history preserves decisions.
No special tools needed. Plain text that works everywhere. Documentation humans actually read.
Struggling with process documentation? Want to make your workflows AI-friendly? Let's talk about systematic improvement.