Risk Register
For changes that touch sensitive areas (authentication, data, migrations, infrastructure), document the risks explicitly. This is what senior developers do naturally - making it explicit ensures nothing is overlooked.
When to Use
Use this skill when your change involves:
- Authentication/Authorization - Login, sessions, permissions, tokens
- User Data - PII, passwords, payment info, user content
- Data Migrations - Schema changes, data transformations, backfills
- External Integrations - Third-party APIs, webhooks, OAuth
- Infrastructure - Deployment, scaling, configuration changes
- Breaking Changes - API changes, behavioral changes, deprecations
Quick Start
/risk-register
Or specify the change:
/risk-register "Adding password reset functionality"
The Risk Register Template
For each risky change, complete this register:
# Risk Register: [Feature/Change Name]
## Summary
Brief description of what's changing and why it's sensitive.
## Top 3 Risks
### Risk 1: [Name]
**Likelihood:** Low / Medium / High
**Impact:** Low / Medium / High / Critical
**Description:**
What could go wrong?
**Mitigation:**
How are we preventing this?
**Detection:**
How would we know if this happened?
**Response:**
What do we do if it happens?
---
### Risk 2: [Name]
...
### Risk 3: [Name]
...
## Testing Strategy
### Pre-deployment
- [ ] Unit tests cover the change
- [ ] Integration tests for critical paths
- [ ] Manual testing of edge cases
- [ ] Security review completed
### Post-deployment
- [ ] Smoke test in production
- [ ] Monitor error rates
- [ ] Watch for anomalies in [specific metrics]
- [ ] Verify [specific functionality] works
## Monitoring & Alerting
What should we watch after deployment?
| Metric | Normal Range | Alert Threshold | Response |
|--------|--------------|-----------------|----------|
| Login failure rate | < 5% | > 10% | Check auth service |
| API error rate | < 1% | > 5% | Investigate errors |
| ... | ... | ... | ... |
## Rollback Strategy
### Can we rollback?
Yes / Partial / No (explain why)
### Rollback steps
1. [Step 1]
2. [Step 2]
3. [Step 3]
### Rollback time estimate
[X minutes/hours]
### Data implications
What happens to data created after deployment if we rollback?
## Approval
- [ ] Engineer reviewed risks
- [ ] Security reviewed (if auth/data)
- [ ] Stakeholder aware of risks
Risk Categories
Authentication Risks
| Risk | Impact | Common Mitigations | |------|--------|-------------------| | Session hijacking | Critical | Secure cookies, HTTPS, token rotation | | Credential stuffing | High | Rate limiting, MFA, breach detection | | Token leakage | Critical | Short expiry, secure storage, no logging | | Privilege escalation | Critical | Strict authz checks, principle of least privilege | | Account takeover | Critical | Email verification, suspicious activity alerts |
Data Risks
| Risk | Impact | Common Mitigations | |------|--------|-------------------| | Data loss | Critical | Backups, soft deletes, transaction safety | | Data corruption | Critical | Validation, constraints, idempotency | | Data leakage | Critical | Access controls, encryption, audit logs | | Privacy violation | High | PII handling, consent, data minimization | | Compliance breach | High | Audit trails, retention policies |
Migration Risks
| Risk | Impact | Common Mitigations | |------|--------|-------------------| | Failed migration | High | Dry runs, backups, reversible migrations | | Data inconsistency | High | Validation checks, reconciliation | | Downtime | Medium | Rolling deploys, feature flags | | Performance degradation | Medium | Index analysis, query optimization |
Example Risk Register
# Risk Register: Password Reset Feature
## Summary
Adding password reset via email. Touches auth system, sends emails with tokens,
allows password changes without current password.
## Top 3 Risks
### Risk 1: Token Theft/Replay
**Likelihood:** Medium
**Impact:** Critical
**Description:**
Reset tokens could be intercepted or reused to take over accounts.
**Mitigation:**
- Tokens expire in 1 hour
- Single use (invalidated after use)
- Tokens are cryptographically random (32 bytes)
- HTTPS only
**Detection:**
- Alert on multiple reset attempts for same user
- Log all password resets with IP
**Response:**
- Invalidate all tokens for affected user
- Force password change
- Notify user of suspicious activity
---
### Risk 2: Email Enumeration
**Likelihood:** High
**Impact:** Medium
**Description:**
Attackers could use the reset form to discover which emails have accounts.
**Mitigation:**
- Same response for valid/invalid emails
- Rate limiting on reset endpoint
- CAPTCHA after 3 attempts
**Detection:**
- Monitor for high volume of reset requests
- Alert on requests from same IP for many emails
**Response:**
- Block IP temporarily
- Enable additional rate limiting
---
### Risk 3: Token Logged/Exposed
**Likelihood:** Low
**Impact:** Critical
**Description:**
Reset token appears in logs, error messages, or URLs shared externally.
**Mitigation:**
- Token in POST body, not URL
- Logging excludes token field
- Error messages are generic
**Detection:**
- Grep logs for token patterns
- Review error handling
**Response:**
- Purge affected logs
- Rotate any exposed tokens
- Notify affected users
## Testing Strategy
### Pre-deployment
- [x] Unit tests for token generation, validation, expiry
- [x] Integration test for full reset flow
- [x] Test expired token rejection
- [x] Test reused token rejection
- [x] Security review of token handling
### Post-deployment
- [ ] Smoke test: Complete reset flow in production
- [ ] Monitor email delivery rate
- [ ] Watch for spike in reset requests
## Monitoring & Alerting
| Metric | Normal | Alert | Response |
|--------|--------|-------|----------|
| Reset requests/hour | < 100 | > 500 | Check for abuse |
| Reset completion rate | > 80% | < 50% | Check email delivery |
| Failed reset attempts | < 10% | > 30% | Check token generation |
## Rollback Strategy
### Can we rollback?
Yes - feature flag controls access to reset endpoint.
### Rollback steps
1. Disable `PASSWORD_RESET_ENABLED` feature flag
2. Invalidate all outstanding reset tokens
3. Communicate to support team
### Rollback time estimate
~5 minutes (feature flag toggle)
### Data implications
Outstanding reset tokens will be invalidated. Users mid-reset will need to retry.
Integration with Wiggum
When wiggum detects changes to auth, data, or migrations, it should prompt:
This change touches [auth/data/migrations].
Should we create a risk register? (y/n)
If yes, use this skill to document risks before proceeding.
Remember
- Be specific - "data loss" is too vague; "orphaned records if parent deleted" is actionable
- Be honest - If you can't roll back, say so
- Think like an attacker - What would you try if you wanted to break this?
- Think like ops - How would you know something is wrong at 3am?
The goal isn't to prevent all risks - it's to know what the risks are and have a plan.