Skills
skills/aakash-dhar/claude-skills/risk-register

risk-register

SKILL.md

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

ID Risk Category What to Look For
T1 Architecture Single points of failure, monolith pain points, scaling bottlenecks, circular dependencies
T2 Code Quality High complexity files, low test coverage, excessive tech debt, code smells
T3 Dependencies Vulnerable packages, outdated major versions, unmaintained libraries, license issues
T4 Security Exposed secrets, injection vulnerabilities, auth gaps, data exposure
T5 Performance Slow queries, memory leaks, missing caching, N+1 problems
T6 Data Missing backups, no migration rollback, data integrity gaps, missing validation
T7 Infrastructure No redundancy, manual deployments, missing monitoring, no auto-scaling
T8 Integration Flaky third-party APIs, missing circuit breakers, undocumented API contracts

Delivery Risks

ID Risk Category What to Look For
D1 Timeline Unrealistic deadlines, scope creep, incomplete requirements, blocked tasks
D2 Resources Team capacity constraints, key person dependency, skill gaps, competing priorities
D3 Scope Vague requirements, missing acceptance criteria, unbounded features, no MVP definition
D4 Dependencies Cross-team blockers, external vendor timelines, design deliverables, stakeholder approvals
D5 Communication Unclear ownership, missing documentation, no stakeholder alignment, siloed knowledge

Operational Risks

ID Risk Category What to Look For
O1 Availability No SLA defined, missing health checks, no incident response plan, no runbooks
O2 Disaster Recovery No backup strategy, untested recovery, missing failover, no RTO/RPO targets
O3 Compliance GDPR gaps, missing audit logging, data retention policy unclear, security certifications pending
O4 Support No on-call rotation, missing runbooks, no escalation path, knowledge silos

Business Risks

ID Risk Category What to Look For
B1 Market Competitive pressure, changing requirements, pivoting product direction
B2 Vendor Vendor lock-in, pricing changes, vendor stability, contract expiry
B3 Revenue Payment system reliability, billing accuracy, churn risk from outages
B4 Reputation Data breach risk, public-facing outage risk, user trust

3. Risk Scoring

Likelihood Scale

Score Level Definition Probability
1 Rare Could happen but very unlikely in the next 3 months < 10%
2 Unlikely Possible but not expected 10-30%
3 Possible Could go either way 30-60%
4 Likely More likely than not 60-85%
5 Almost Certain Will very likely happen > 85%

Impact Scale

Score Level Definition Examples
1 Negligible Minor inconvenience, no user impact Cosmetic bug, minor delay
2 Minor Small user impact, easy to fix Edge case bug, 1-2 day delay
3 Moderate Noticeable impact, workaround exists Feature degraded, 1 week delay
4 Major Significant impact, hard to work around Core feature broken, 2+ week delay, partial data loss
5 Severe Critical failure, no workaround Full outage, data breach, project cancelled, regulatory fine

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:

Strategy When to Use Example
Avoid Eliminate the risk entirely by changing approach Don't use the unproven technology; use the established one instead
Mitigate Reduce likelihood or impact Add tests, create documentation, build redundancy
Transfer Shift risk to a third party Use managed service instead of self-hosting; buy insurance
Accept Risk is low enough or unavoidable Known minor UI bug that doesn't affect core functionality
Contingency Prepare a plan B if the risk materializes Rollback plan, backup vendor, alternative approach ready

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
Weekly Installs
3
Repository
aakash-dhar/cla…e-skills
First Seen
7 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
opencode3
gemini-cli3
antigravity3
claude-code3
github-copilot3
codex3