mathias
c6787e04d7
Second half of #29. The index was hand-maintained and had already drifted once: dream and experiment-spec shipped with no row, their rows lost to a squash-merge after a directory reorg. bin/check-index caught that after the fact; generating removes the class. The curated summary and trigger move into each SKILL.md as `summary:` and `use_when:`, carried over verbatim from the existing table rather than derived from `description:` — description is a paragraph written for model selection, and truncating it would have produced a worse table than the one it replaced. Knowledge now lives once, next to the skill it describes, which is the argument that made a hand-maintained index the wrong shape to begin with. The table is written between markers, so the wiring docs, the relationships tree and the trigger table below it are untouched — those are prose, not data. Rows are alphabetical now; the conceptual grouping the old order carried lives in the relationships tree, which is the better place for it. A fourth column shows each skill's surfaces, which is what makes #29's field visible rather than merely enforced. bin/check-index and its test are deleted: a generated table cannot drift in either direction, so `generate-index --check` subsumes both of its assertions. Verified by mutation — deleting the tdd row turns `task check` red with "SKILLS_INDEX.md is out of date". Closes #29 Bump-Type: minor
4.3 KiB
name, surfaces, summary, use_when, description
| name | surfaces | summary | use_when | description | ||
|---|---|---|---|---|---|---|
| regulatory-risk-assessment |
|
Structured risk register for regulated-industry features | Filing a CAD issue (needs Risk: level); features touching payments, auth, external APIs, user data | Produce a structured regulatory risk assessment / risk-register entry for regulated-industry features (banking, payments, PSD2/PSR, DORA, AML). Use when filing a CAD issue that needs a Risk:LOW/MEDIUM/HIGH level, or designing features touching payments, auth, data storage, or external APIs ("what are the risks?", "compliance gate", "risk register"). |
regulatory-risk-assessment
Produce a structured regulatory risk assessment for a feature, component, or integration — generating a risk register entry that satisfies the audit requirements of regulated-industry clients (banking, finance, insurance, PSD2/PSR, DORA, AML/KYC contexts).
Use when:
- Filing a Gitea issue dispatched via CAD (needs Risk: LOW/MEDIUM/HIGH)
- Designing a feature touching payments, auth, data storage, external APIs
- Preparing a client deliverable in a regulated industry
- "what are the risks?" / "compliance gate" / "risk register" in session
Do not use for: routine refactoring, docs-only changes, internal tooling with no external data or user impact.
What this skill produces
A docs/risk-register.md section with this schema:
R-[DOMAIN]-[NN] — [Short risk title]
| Field | Value |
|---|---|
| Risk | What could go wrong (concrete, specific) |
| Regulatory reference | Which obligation/regulation, if any |
| Likelihood | H / M / L |
| Impact | H / M / L |
| Overall | H / M / L (highest of likelihood x impact) |
| Mitigation | What we are doing about it |
| Validation | Test name or Gitea issue number |
| Status | open / mitigated / accepted |
Risk ID namespace: R-AUTH-NN authentication and authorization R-DATA-NN data storage, retention, privacy R-API-NN external API integration R-PAY-NN payment and financial transactions R-INFRA-NN infrastructure and availability R-AGENT-NN agentic / AI execution R-COMP-NN compliance and regulatory obligation
Mechanics
Step 1 — Scope the assessment
- What external systems does this touch?
- What user data does it read, write, or transmit?
- What happens on silent failure? Loud failure?
- What is the blast radius of a worst-case bug?
- Is a regulation implicated?
Step 2 — Enumerate risks (common examples) Auth/OAuth: token theft, refresh failure, insufficient scope Email/Gmail: misclassification archives HUMAN thread, PII in logs Payment/PAIN.001: wrong amount, duplicate submission, missing field Agentic: irreversible action without approval, prompt injection, spirals Infra: single point of failure, secret in logs
Step 3 — Declare overall risk level Highest individual risk = feature overall level (LOW/MEDIUM/HIGH). This is the Risk: declaration in the CAD agent-ready issue contract.
Step 4 — Write validations Every mitigation needs a validation: - Specific test name (TestXxx) - Gitea issue number - Manual verification step with acceptance criteria Not acceptable: "will test later", "review manually"
Step 5 — Update docs/risk-register.md Append entries. Create if absent:
# Risk Register
All entries follow R-[DOMAIN]-[NN] schema.
See skills/regulatory-risk-assessment/SKILL.md for conventions.
Last updated: [date]
Integration with assessor-loop
For complex regulated-industry features (PSD2/PSR, DORA, AML), route to mathias/assessor-loop for deep obligation decomposition first. Use this skill standalone for internal tooling or general engineering risk.
Integration with CAD
Every CAD-dispatched issue must include: Risk: LOW | MEDIUM | HIGH
CAD pre-flight (agentsquad#29) rejects issues without it. If genuinely no risks: declare LOW and note why.
Example entry
R-DATA-01 — Email misclassification archives a HUMAN thread
| Field | Value |
|---|---|
| Risk | LLM labels a real person's email as NOISE, causing auto-archive |
| Regulatory reference | None (internal) |
| Likelihood | M |
| Impact | H |
| Overall | H |
| Mitigation | Phase 1 read-only; HUMAN class never auto-archived in any phase |
| Validation | TestClassifier_HumanThreadNeverArchived; 1-week Phase 1 review |
| Status | open |