@windyroad/risk-scorer 0.2.0

package/skills/wr:risk-policy/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: wr:risk-policy
+description: Create or update the project's RISK-POLICY.md per ISO 31000 and the risk-scorer agent. Examines the project to derive business-specific impact levels.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+---
+
+# Risk Policy Generator
+
+Create or update `RISK-POLICY.md` per ISO 31000, tailored to this project's business context. The risk-scorer agent reads this file to score pipeline actions (commit, push, release).
+
+## What belongs in RISK-POLICY.md (single source of truth)
+
+- **Risk appetite** -- the residual risk threshold for pipeline actions
+- **Impact levels** -- business consequences of failure, specific to this product and its users
+- **Likelihood levels** -- descriptions of how likely a risk is to materialise
+- **Risk matrix** -- Impact × Likelihood score table and label bands (Low/Medium/High/Critical)
+- **Last reviewed date** -- when the policy was last reviewed or updated
+
+The risk-scorer agent, problem management skill, and any other process that needs to assess risk severity reads these definitions from RISK-POLICY.md.
+
+## What does NOT belong in RISK-POLICY.md (lives in the risk-scorer agent)
+
+- Assessment rules, back-pressure, control discovery (scoring mechanics)
+
+## Steps
+
+### 1. Read the risk-scorer agent contract
+
+Read `.claude/agents/risk-scorer-pipeline.md` to understand what the scorer expects from `RISK-POLICY.md`. Extract:
+
+- What fields the agent reads from the policy (look for "Read `RISK-POLICY.md`" in "Your Role")
+- The impact level labels used in the agent's risk matrix (look for the "Product Reference Table")
+- The label bands and their score ranges (look for "Label Bands")
+- The gate threshold the agent uses (look for "risk appetite" references)
+
+Use this contract to guide drafting. Do not hardcode assumptions about the number of levels, their labels, or the appetite threshold -- derive them from the agent definition.
+
+### 2. Discover project context
+
+Examine the project to understand what it does and who uses it. Adapt to the project type -- do not assume any particular framework or language.
+
+**Find the project manifest** (first match wins):
+- `package.json` (Node/JS/TS)
+- `pyproject.toml` or `setup.py` (Python)
+- `go.mod` (Go)
+- `Cargo.toml` (Rust)
+- `Gemfile` (Ruby)
+- `pom.xml` or `build.gradle` (Java/Kotlin)
+
+**Find the project description**:
+- `README.md` or `README.*`
+- The `description` field in the manifest
+- A homepage or docs index
+
+**Discover user-facing features** by scanning for:
+- Route/endpoint definitions (scan for directories named `routes/`, `pages/`, `api/`, `handlers/`, `controllers/`, or grep for route decorators/annotations)
+- UI entry points (`.html`, `.svelte`, `.tsx`, `.jsx`, `.vue`, `.astro` files)
+- CLI commands or public API surface
+
+**Discover infrastructure**:
+- Deployment config (`Dockerfile`, `docker-compose.*`, `fly.toml`, `app.yaml`, `serverless.yml`, `*.tf`, cloud config)
+- CI/CD workflows (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`)
+- Database or storage config
+
+Build a mental model of: what does this product do, who are its users, and what would hurt them?
+
+**Check repository visibility**:
+- Run `gh repo view --json isPrivate` or check for other visibility indicators
+- If the repository is **public**, confidential business metrics (revenue, user counts, pricing, traffic volumes) must not appear in any committed file. Note this for step 5 — the policy must include a "Confidential Information" section and information disclosure must be covered in the impact levels.
+
+### 3. Check for existing policy
+
+If `RISK-POLICY.md` already exists, read it. Identify:
+
+- Whether impact levels still reflect the current product (features may have been added/removed)
+- Whether the risk appetite is still appropriate
+- Whether the last reviewed date is stale (> 2 weeks)
+
+### 4. Check for recent incidents
+
+If `docs/problems/` exists, scan for open or known-error problems (files ending in `.open.md` or `.known-error.md`). For each:
+
+- Read the problem to understand its business impact
+- Consider whether the impact levels adequately cover this kind of failure
+- Flag any gap (e.g., a problem caused data corruption but the impact levels don't mention data integrity)
+
+If recent incidents suggest the impact levels need updating, note this for step 6 (user confirmation). ISO 31000 requires risk criteria to be reviewed after incidents, not just on a schedule.
+
+### 5. Draft impact levels, likelihood levels, and risk matrix
+
+**Impact levels** must describe **business consequences** (ISO 31000 context establishment), not categories of files changed. Each level answers: "What happens to users/business if this goes wrong?"
+
+Use 5 levels (Negligible to Severe). Tailor descriptions to this specific product:
+
+- **Negligible**: No user impact at all
+- **Minor**: No user impact; only developer/build affected
+- **Moderate**: Deployment/publishing disrupted; users can't get updates. For public repositories: confidential business metrics (revenue, user counts, pricing, traffic volumes) committed to the repository — an information disclosure requiring immediate remediation but not affecting service availability.
+- **Significant**: User-facing features degraded or inaccessible
+- **Severe**: Data integrity, trust, or availability destroyed
+
+Reference specific product features, user workflows, and infrastructure by name. Generic descriptions like "application logic affected" are wrong -- say what breaks and for whom.
+
+**Likelihood levels** describe how likely a risk is to materialise. Use 5 levels (Rare to Almost certain). These are universal — not product-specific:
+
+- **Rare (1)**: Requires specific, unusual conditions. Extensive test coverage or architectural safeguards make occurrence very unlikely.
+- **Unlikely (2)**: Could happen but controls (tests, CI gates, review hooks) significantly reduce probability.
+- **Possible (3)**: Moderate complexity or limited test coverage. Could happen under normal conditions.
+- **Likely (4)**: High complexity, many code paths, or limited controls. Expected to occur without intervention.
+- **Almost certain (5)**: Known gap, no controls in place, or previously observed failure mode.
+
+**Risk matrix**: Include the Impact × Likelihood multiplication table (5×5 = scores 1-25) and the label bands:
+
+| Score Range | Label |
+|-------------|-------|
+| 1-4 | Low |
+| 5-9 | Medium |
+| 10-14 | High |
+| 15-25 | Critical |
+
+The risk matrix is used by both the **risk-scorer agent** (pipeline risk assessment) and the **problem management process** (problem severity via `/problem` skill).
+
+### 6. Confirm with the user
+
+You MUST use the AskUserQuestion tool (not plain text output) to collect user confirmation. Do not proceed to step 7 until you have received answers via AskUserQuestion.
+
+Call AskUserQuestion with a single message that presents:
+
+1. The drafted impact levels (as a table) and asks whether they accurately reflect what matters most
+2. The risk appetite threshold -- present the label bands from the agent contract (step 1) and recommend a threshold based on project maturity. Ask the user to confirm or adjust. A prototype with no real users may tolerate higher risk than a production system with paying users or compliance requirements
+3. Whether any business context is missing (e.g., compliance requirements, SLAs, user base size)
+
+### 7. Validate draft with risk-scorer agent
+
+Before writing the policy file, invoke the risk-scorer agent to validate the draft. This is the gate -- the enforce hook will only allow writes to RISK-POLICY.md after the scorer returns PASS.
+
+Run the risk-scorer agent (subagent_type: "risk-scorer") with this prompt:
+
+> Review this draft risk policy for ISO 31000 compliance. Validate it.
+>
+> [paste the full draft policy content here]
+
+The risk-scorer will check:
+- Impact levels describe business consequences (not file categories)
+- Impact labels match the risk matrix (Negligible, Minor, Moderate, Significant, Severe)
+- Risk appetite defines a numeric threshold
+- Business context is present
+- Last reviewed date is present
+
+It ends its output with `RISK_VERDICT: PASS` or `RISK_VERDICT: FAIL`. The PostToolUse hook reads this from the agent output and sets the edit marker on PASS.
+
+- **If PASS**: proceed to step 8 (write)
+- **If FAIL**: fix the issues the scorer identified, then re-run this step
+
+### 8. Write RISK-POLICY.md
+
+Write the policy using the structure derived from the agent contract (step 1). The output must include:
+
+- The ISO 31000 header and "Last reviewed" date (today's date)
+- Business context section
+- **Confidential Information section** (for public repositories): stating that business metrics must not appear in committed files, with examples of what is confidential and guidance to use generic descriptions instead
+- The risk appetite threshold confirmed by the user in step 6
+- The impact levels with project-specific descriptions from step 5
+- The likelihood levels (universal 1-5 scale)
+- The risk matrix (Impact × Likelihood table) and label bands
+- A note that both the risk-scorer agent and problem management process reference this policy
+
+## Updating an existing policy
+
+When updating rather than creating:
+
+- Preserve the existing risk appetite unless the user wants to change it
+- Compare current impact levels against the current state of the project
+- Flag levels that reference features or infrastructure that no longer exist
+- Flag new features or infrastructure not covered by existing levels
+- Update the "Last reviewed" date to today
+- Show the user a diff of what changed
+
+$ARGUMENTS