Risk Register

Risk Register Skill

When creating or updating a risk register, follow this structured process. The goal is to maintain a living document that surfaces project risks early enough to act on them — before they become incidents, missed deadlines, or scope explosions.

IMPORTANT: Always save the output as a markdown file in the project-decisions/ directory at the project root. Create the directory if it doesn't exist.

PRINCIPLE: A good risk register is not a one-time document. It should be reviewed and updated every sprint. Risks change — new ones appear, old ones are mitigated, some become reality.

0. Output Setup

mkdir -p project-decisions

# File naming:
# First time:  project-decisions/YYYY-MM-DD-risk-register.md
# Updates:     Edit the existing file, add to the changelog at the bottom
# If no existing register exists, create a new one
# If one exists, update it

ls project-decisions/*risk-register* 2>/dev/null

1. Risk Discovery

1a. Codebase & Technical Risks

# Complexity hotspots (high complexity = high risk of bugs)
find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" \) ! -path '*/node_modules/*' ! -path '*/dist/*' -exec wc -l {} + 2>/dev/null | sort -rn | head -15

# Files with highest churn (most changes = most fragile)
git log --name-only --since="3 months ago" --format="" -- src/ app/ 2>/dev/null | sort | uniq -c | sort -rn | head -15

# Files with most bug fixes (where problems live)
git log --name-only --since="6 months ago" --grep="fix\|bug\|hotfix" --format="" -- src/ app/ 2>/dev/null | sort | uniq -c | sort -rn | head -10

# Dependency vulnerabilities
npm audit --json 2>/dev/null | head -50
pip audit 2>/dev/null | head -20

# Outdated dependencies
npm outdated 2>/dev/null | head -20
pip list --outdated 2>/dev/null | head -20

# TODO/FIXME/HACK count (unaddressed known issues)
echo "TODO: $(grep -rn 'TODO' --include='*.ts' --include='*.js' --include='*.py' src/ app/ 2>/dev/null | grep -v 'node_modules' | wc -l)"
echo "FIXME: $(grep -rn 'FIXME' --include='*.ts' --include='*.js' --include='*.py' src/ app/ 2>/dev/null | grep -v 'node_modules' | wc -l)"
echo "HACK: $(grep -rn 'HACK' --include='*.ts' --include='*.js' --include='*.py' src/ app/ 2>/dev/null | grep -v 'node_modules' | wc -l)"

# Test coverage gaps (untested code = risk)
find src/ app/ -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" \) ! -name "*.test.*" ! -name "*.spec.*" ! -name "test_*" ! -name "*.d.ts" ! -name "index.*" ! -path '*/node_modules/*' ! -path '*/dist/*' 2>/dev/null | while read f; do
  base=$(basename "$f" | sed 's/\.\(ts\|tsx\|js\|jsx\|py\)$//')
  if ! find . \( -name "${base}.test.*" -o -name "${base}.spec.*" -o -name "test_${base}.*" \) ! -path '*/node_modules/*' 2>/dev/null | grep -q .; then
    echo "UNTESTED: $f"
  fi
done | head -20

# Single points of failure (bus factor)
for f in $(git log --name-only --since="12 months ago" --format="" -- src/ 2>/dev/null | sort -u | head -30); do
  authors=$(git log --format='%aN' --since="12 months ago" -- "$f" 2>/dev/null | sort -u | wc -l)
  if [ "$authors" -eq 1 ]; then
    echo "BUS FACTOR 1: $f ($(git log --format='%aN' -1 -- "$f" 2>/dev/null))"
  fi
done | head -15

# Missing error handling in critical paths
grep -rn "catch\|except\|rescue" --include="*.ts" --include="*.js" --include="*.py" src/ 2>/dev/null | wc -l
grep -rn "async function\|async def\|async (" --include="*.ts" --include="*.js" --include="*.py" src/ 2>/dev/null | wc -l

# Infrastructure configuration
cat docker-compose.yml Dockerfile 2>/dev/null | head -40
cat .github/workflows/*.yml 2>/dev/null | head -40

# Check for health checks and monitoring
grep -rn "health\|readiness\|liveness\|monitor\|sentry\|datadog\|prometheus" --include="*.ts" --include="*.js" --include="*.py" --include="*.yaml" --include="*.yml" . 2>/dev/null | grep -v "node_modules" | head -10

# Check for secrets management
grep -rn "process\.env\|os\.environ\|os\.Getenv" --include="*.ts" --include="*.js" --include="*.py" --include="*.go" src/ app/ 2>/dev/null | grep -v "node_modules\|test\|spec" | wc -l
ls .env .env.local .env.production 2>/dev/null

1b. Project & Delivery Risks

Evaluate from context, PRDs, recent activity:

# Recent velocity (commits per week)
for week in 4 3 2 1 0; do
  start=$(date -d "$((week+1)) weeks ago" +%Y-%m-%d 2>/dev/null || date -v-$((week+1))w +%Y-%m-%d 2>/dev/null)
  end=$(date -d "$week weeks ago" +%Y-%m-%d 2>/dev/null || date -v-${week}w +%Y-%m-%d 2>/dev/null)
  count=$(git log --oneline --after="$start" --before="$end" 2>/dev/null | wc -l)
  echo "Week -$week: $count commits"
done

# PR cycle time (how long PRs stay open)
gh pr list --state merged --limit 10 --json number,title,createdAt,mergedAt 2>/dev/null | head -40

# Open PRs (work in progress)
gh pr list --state open --json number,title,createdAt,author 2>/dev/null | head -20

# Pending issues
gh issue list --state open --limit 20 --json number,title,labels,createdAt 2>/dev/null | head -40

# Recent incidents
ls project-decisions/*incident* 2>/dev/null

# Recent scope changes or decision records
ls project-decisions/ 2>/dev/null | tail -10

# Check for deadline references
grep -rn "deadline\|due date\|launch\|go-live\|ship by\|target date" --include="*.md" . 2>/dev/null | grep -v "node_modules\|\.git" | head -10

2. Risk Categories

Technical Risks

Delivery Risks

Operational Risks

Business Risks

3. Risk Scoring

Likelihood Scale

Impact Scale

Risk Score Matrix

                        IMPACT
                 1     2     3     4     5
            ┌─────┬─────┬─────┬─────┬─────┐
     5      │  5  │ 10  │ 15  │ 20  │ 25  │
            │ 🟡  │ 🟠  │ 🔴  │ 🔴  │ 🔴  │
L    ──────┼─────┼─────┼─────┼─────┼─────┤
I    4      │  4  │  8  │ 12  │ 16  │ 20  │
K           │ 🟢  │ 🟡  │ 🟠  │ 🔴  │ 🔴  │
E    ──────┼─────┼─────┼─────┼─────┼─────┤
L    3      │  3  │  6  │  9  │ 12  │ 15  │
I           │ 🟢  │ 🟡  │ 🟡  │ 🟠  │ 🔴  │
H    ──────┼─────┼─────┼─────┼─────┼─────┤
O    2      │  2  │  4  │  6  │  8  │ 10  │
O           │ 🟢  │ 🟢  │ 🟡  │ 🟡  │ 🟠  │
D    ──────┼─────┼─────┼─────┼─────┼─────┤
     1      │  1  │  2  │  3  │  4  │  5  │
            │ 🟢  │ 🟢  │ 🟢  │ 🟢  │ 🟡  │
            └─────┴─────┴─────┴─────┴─────┘

Score ranges:
🟢 Low (1-4):       Accept — monitor, no immediate action
🟡 Medium (5-9):    Mitigate — plan mitigation, review regularly
🟠 High (10-15):    Act — active mitigation required, escalate
🔴 Critical (16-25): Urgent — immediate action, executive visibility

Risk Score Calculation

Risk Score = Likelihood × Impact

Example:
  Risk: "Key developer leaves before project completion"
  Likelihood: 3 (Possible)
  Impact: 4 (Major — critical knowledge loss, 2+ week delay)
  Score: 3 × 4 = 12 (🟠 High)

4. Risk Response Strategies

For each identified risk, choose a response strategy:

5. Risk Register Entry Format

Each risk should include:

### RISK-[ID]: [Title]

| Field | Value |
|-------|-------|
| **Category** | [Technical / Delivery / Operational / Business] |
| **Subcategory** | [T1-T8 / D1-D5 / O1-O4 / B1-B4] |
| **Description** | [What could happen and why] |
| **Trigger** | [What event or condition would cause this risk to materialize] |
| **Likelihood** | [1-5] [Rare/Unlikely/Possible/Likely/Almost Certain] |
| **Impact** | [1-5] [Negligible/Minor/Moderate/Major/Severe] |
| **Score** | [L × I] [🟢/🟡/🟠/🔴] |
| **Response** | [Avoid / Mitigate / Transfer / Accept / Contingency] |
| **Mitigation** | [Specific actions to reduce likelihood or impact] |
| **Contingency** | [What to do if the risk materializes] |
| **Owner** | [Person responsible for monitoring and acting] |
| **Status** | [Open / Mitigating / Mitigated / Accepted / Realized / Closed] |
| **Due Date** | [When mitigation should be complete] |
| **Evidence** | [Data from codebase scan, metrics, or observations] |
| **Linked Items** | [Related tickets, incidents, decisions] |
| **Last Reviewed** | [Date] |

6. Automated Risk Detection Rules

Auto-Flag as 🔴 Critical

IF any of these are true, auto-flag as critical risk:

- Dependency with known critical CVE (CVSS ≥ 9.0)
- Secrets/credentials committed to git
- Production database has no backup configured
- Zero test coverage on authentication or payment code
- Single point of failure in production architecture
- No rollback strategy for upcoming deployment
- Key person dependency on critical path with no documentation
- Deadline is < 2 weeks and > 30% of scope is incomplete

Auto-Flag as 🟠 High

IF any of these are true, auto-flag as high risk:

- Dependency with known high CVE (CVSS ≥ 7.0)
- Test coverage < 30% on modified files
- Files with > 500 lines and no tests
- Bus factor of 1 on > 5 critical files
- More than 20 unresolved TODOs/FIXMEs in critical paths
- No monitoring/alerting on production service
- Third-party API with no circuit breaker or fallback
- Sprint velocity declining for 3+ consecutive sprints
- PR cycle time > 5 days average

Auto-Flag as 🟡 Medium

IF any of these are true, auto-flag as medium risk:

- Dependencies > 6 months outdated
- No API documentation for public endpoints
- Missing .env.example or setup documentation
- No runbook for common failure scenarios
- Inconsistent error handling patterns
- Code duplication detected across > 3 files

7. Risk Trends

Track how risks change over time:

### Risk Trend: [Risk Title]

| Date | Likelihood | Impact | Score | Change | Notes |
|------|-----------|--------|-------|--------|-------|
| 2026-01-15 | 3 | 4 | 12 🟠 | — | Initial assessment |
| 2026-01-29 | 3 | 4 | 12 🟠 | → | No change, mitigation in progress |
| 2026-02-12 | 2 | 4 | 8 🟡 | ↓ | Tests added, documentation improved |
| 2026-02-19 | 2 | 3 | 6 🟡 | ↓ | Second engineer onboarded to module |

Trend: ↓ Improving

Trend symbols:

↑ Worsening (score increased)
→ Stable (no change)
↓ Improving (score decreased)
⚡ Realized (risk became an actual issue)
✅ Closed (risk eliminated or accepted and documented)

8. Review Cadence

Recommended review schedule:

| Review Type | Frequency | Who | Focus |
|------------|-----------|-----|-------|
| Quick scan | Every sprint | TPM | New risks, status updates, score changes |
| Full review | Monthly | TPM + Tech Lead | All risks, trends, mitigation effectiveness |
| Deep dive | Quarterly | Full team | Architecture risks, strategic risks, historical trends |
| Ad-hoc | As needed | TPM | After incidents, major scope changes, team changes |

Output Document Template

Save to project-decisions/YYYY-MM-DD-risk-register.md:

# Project Risk Register

**Project:** [Project Name]
**Last Updated:** YYYY-MM-DD
**Updated By:** [Name]
**Next Review:** YYYY-MM-DD
**Overall Risk Level:** [🟢 Low / 🟡 Medium / 🟠 High / 🔴 Critical]

---

## Risk Summary

| Severity | Count | Trend |
|----------|-------|-------|
| 🔴 Critical | X | [↑/→/↓] |
| 🟠 High | X | [↑/→/↓] |
| 🟡 Medium | X | [↑/→/↓] |
| 🟢 Low | X | [↑/→/↓] |
| **Total Open** | **X** | |
| Mitigated this period | X | |
| New this period | X | |
| Realized (became issues) | X | |

---

## Risk Heat Map

                    IMPACT
             1     2     3     4     5
        ┌─────┬─────┬─────┬─────┬─────┐
 5      │     │     │     │ R03 │     │

L ──────┼─────┼─────┼─────┼─────┼─────┤ I 4 │ │ │ R07 │ R01 │ │ K ──────┼─────┼─────┼─────┼─────┼─────┤ E 3 │ │ R09 │ R04 │ R02 │ │ L ──────┼─────┼─────┼─────┼─────┼─────┤ I 2 │ R10 │ R08 │ R06 │ │ │ H ──────┼─────┼─────┼─────┼─────┼─────┤ O 1 │ │ R11 │ R05 │ │ │ O └─────┴─────┴─────┴─────┴─────┘ D

---

## Top Risks Requiring Action

| Rank | ID | Risk | Score | Owner | Status | Due |
|------|----|------|-------|-------|--------|-----|
| 1 | R01 | [Title] | 16 🔴 | [Name] | [Status] | [Date] |
| 2 | R02 | [Title] | 12 🟠 | [Name] | [Status] | [Date] |
| 3 | R03 | [Title] | 20 🔴 | [Name] | [Status] | [Date] |

---

## Full Risk Register

### 🔴 Critical Risks

#### RISK-001: [Title]

| Field | Value |
|-------|-------|
| **Category** | [Category] |
| **Description** | [What could happen] |
| **Trigger** | [What would cause this] |
| **Likelihood** | [X] — [Level] |
| **Impact** | [X] — [Level] |
| **Score** | [XX] 🔴 |
| **Response** | [Strategy] |
| **Mitigation** | [Actions] |
| **Contingency** | [Plan B] |
| **Owner** | [Name] |
| **Status** | [Status] |
| **Due Date** | [Date] |
| **Evidence** | [Codebase findings] |
| **Last Reviewed** | [Date] |

**Trend:**
| Date | L | I | Score | Change | Notes |
|------|---|---|-------|--------|-------|
| [Date] | X | X | XX | — | [Notes] |

---

[Repeat for each risk...]

---

### 🟠 High Risks

[Same format...]

### 🟡 Medium Risks

[Same format...]

### 🟢 Low Risks

[Same format...]

---

## Realized Risks (became actual issues)

| ID | Risk | Realized Date | Impact | Incident Link |
|----|------|--------------|--------|--------------|
| R05 | [Title] | YYYY-MM-DD | [Actual impact] | [Link to incident report] |

---

## Closed Risks

| ID | Risk | Closed Date | Reason |
|----|------|------------|--------|
| R12 | [Title] | YYYY-MM-DD | [Mitigated / Accepted / No longer relevant] |

---

## Risk Metrics

| Metric | Current | Previous | Trend |
|--------|---------|----------|-------|
| Total open risks | X | X | [↑/→/↓] |
| Average risk score | X.X | X.X | [↑/→/↓] |
| Critical + High risks | X | X | [↑/→/↓] |
| Risks mitigated this period | X | X | |
| Risks realized this period | X | X | |
| Mean time to mitigate | X days | X days | [↑/→/↓] |
| Overdue mitigations | X | X | [↑/→/↓] |

---

## Upcoming Mitigation Actions

| Risk ID | Action | Owner | Due | Status |
|---------|--------|-------|-----|--------|
| R01 | [Specific action] | [Name] | [Date] | ⬜ TODO |
| R02 | [Specific action] | [Name] | [Date] | 🔄 In Progress |
| R03 | [Specific action] | [Name] | [Date] | ⬜ TODO |

---

## Review Log

| Date | Type | Reviewer | Changes Made |
|------|------|----------|-------------|
| YYYY-MM-DD | Initial creation | [Name] | Created register with X risks |
| YYYY-MM-DD | Sprint review | [Name] | Updated R01, added R15, closed R05 |
| YYYY-MM-DD | Monthly review | [Name] | Full review, re-scored 3 risks |

After saving, update the project-decisions index:

echo "# Project Decisions\n" > project-decisions/README.md
echo "| Date | Decision | Type | Status |" >> project-decisions/README.md
echo "|------|----------|------|--------|" >> project-decisions/README.md

for f in project-decisions/2*.md; do
  date=$(basename "$f" | cut -d'-' -f1-3)
  title=$(head -1 "$f" | sed 's/^# //')
  type="Other"
  echo "$f" | grep -q "risk-register" && type="Risk Register"
  echo "$f" | grep -q "build-vs-buy" && type="Build vs Buy"
  echo "$f" | grep -q "incident" && type="Incident Report"
  echo "$f" | grep -q "scope" && type="Scope Check"
  echo "$f" | grep -q "impact" && type="Impact Analysis"
  echo "$f" | grep -q "tech-debt" && type="Tech Debt Report"
  echo "$f" | grep -q "pentest" && type="Pentest Report"
  echo "$f" | grep -qv "risk-register\|build-vs-buy\|incident\|scope\|impact\|tech-debt\|pentest" && type="Tech Decision"
  status=$(grep "^**Status:\|^**Overall Risk Level:\|^**Last Updated:" "$f" | head -1 | sed 's/.*: //' | sed 's/\*//g')
  echo "| $date | [$title](./$(basename $f)) | $type | $status |" >> project-decisions/README.md
done

Adaptation Rules

• Always save to file — every risk register gets persisted in project-decisions/
• Scan the codebase — don't guess at technical risks, find them with grep, git log, npm audit
• Be specific — "authService.ts has 0% test coverage and handles password hashing" not "some code is untested"
• Include evidence — every technical risk should reference actual files, metrics, or scan results
• Score consistently — use the same likelihood and impact scales every time
• Track trends — show whether each risk is improving, stable, or worsening
• Update, don't recreate — if a risk register already exists, update it rather than starting from scratch
• Link to other documents — connect realized risks to incident reports, mitigations to tech decisions
• Assign owners — unowned risks don't get mitigated
• Flag overdue mitigations — a mitigation plan that's past due is itself a risk
• Scale to project — small project gets 5-10 risks, large project gets 20-30
• Distinguish symptoms from risks — "slow API" is a symptom, "no caching strategy for growing dataset" is the risk

Summary

End every risk register with:

1. Overall risk level — 🟢/🟡/🟠/🔴 based on highest open risk
2. Risk count — total open, by severity
3. Top 3 risks — requiring immediate attention
4. New risks — added since last review
5. Trend — overall trajectory (improving / stable / worsening)
6. Overdue actions — mitigations past their due date
7. Next review date — when this should be updated
8. File saved — confirm the document location