diff --git a/SKILLS_INDEX.md b/SKILLS_INDEX.md index 34ac5da..9268d08 100644 --- a/SKILLS_INDEX.md +++ b/SKILLS_INDEX.md @@ -23,6 +23,8 @@ This index lists all available engineering skills. Load the full SKILL.md on dem | `session-retrospective` | Surface non-obvious learnings from a session log | After a coding session ends, before context is lost | | `trainer` | Two-phase brain curation (score candidates, write past quality gate) | Periodic brain pruning and curation | | `grill-me` | Structured plan interrogation — Quick Poke, Full Grill, Pre-mortem | Stress-testing a plan before committing; end of Diamond 1; before promoting to pre-prod | +| `telos-load` | Load TELOS intention substrate at session start | Starting any koala session; before architectural decisions; CAD pipeline entry | +| `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 | ## Wiring into tools @@ -89,3 +91,5 @@ grill-me ──→ planning (after plan is sharpened) | "Grill me / stress-test this / is this ready?" | `grill-me` | | "End of Diamond 1 — should we build this?" | `grill-me` (Full Grill) | | "About to promote to pre-prod" | `grill-me` (Pre-mortem) | +| "What are the risks?" / "compliance gate" / "risk register" | `regulatory-risk-assessment` | +| "Start of session" / "load TELOS" / "what are we optimizing toward?" | `telos-load` | diff --git a/regulatory-risk-assessment/SKILL.md b/regulatory-risk-assessment/SKILL.md new file mode 100644 index 0000000..aed9820 --- /dev/null +++ b/regulatory-risk-assessment/SKILL.md @@ -0,0 +1,105 @@ +# 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 + 1. What external systems does this touch? + 2. What user data does it read, write, or transmit? + 3. What happens on silent failure? Loud failure? + 4. What is the blast radius of a worst-case bug? + 5. 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 | diff --git a/telos-load/SKILL.md b/telos-load/SKILL.md new file mode 100644 index 0000000..06f29bc --- /dev/null +++ b/telos-load/SKILL.md @@ -0,0 +1,76 @@ +# telos-load + +Load TELOS — the intention substrate — into a session so every decision +can be traced back to a goal, and every goal to a problem. + +**Use when:** starting any session on koala (Claude Code, Crush, +Antigravity), or whenever a session needs to know what we are optimizing +toward. If you find yourself making architectural decisions without knowing +the active goals, load TELOS first. + +**Do not skip:** a session without TELOS context is flying blind. It may +produce technically correct output that is strategically wrong. + +## What TELOS is + +TELOS is a wing in brain (wiki/telos/decisions/) containing 9 files: +PROBLEMS, MISSION, GOALS, CHALLENGES, PROJECTS, STRATEGIES, BELIEFS, +WRONG, STATUS. Together they answer: what are we working against, what +are we trying to build, and how do we approach the work? + +Full aggregate: wiki/telos/decisions/principal-telos.md + +## Loading TELOS by harness + +### Claude Code (per-project CLAUDE.md) + +Add to the project CLAUDE.md or ~/.claude/CLAUDE.md: + + ## Intention context (TELOS) + At session start, call brain_context with wing=telos and limit=8. + Fallback if brain MCP unavailable: + wiki/telos/decisions/principal-telos.md in the brain repo. + +The global ~/.claude/CLAUDE.md was wired on koala on 2026-06-16. + +### Crush + +Location on koala: ~/.config/crush/CRUSH.md (auto-loaded via +global_context_paths). Add: + + ## Intention context (TELOS) + At session start: query brain MCP with wing=telos, limit=8. + If brain MCP unavailable: read wiki/telos/decisions/principal-telos.md + +### Antigravity + +Add @brain_context wing=telos directive at top of system instructions. + +### Fallback — no brain MCP + + cat ~/dev/AI/brain/wiki/telos/decisions/principal-telos.md + +Or @-import in CLAUDE.md: + @~/dev/AI/brain/wiki/telos/decisions/principal-telos.md + +## Verification + + brain_query wing=telos limit=3 + → Expected: PROBLEMS, MISSION, GOALS returned + + brain_answer "what am I currently optimizing toward?" + → Expected: non-empty, telos-sourced + → If empty: use brain_query wing=telos (known fallback, brain#11 fixed) + +## When TELOS is stale + +Update STATUS.md via: + brain_write wing=telos hall=decisions filename=STATUS + +## Relationship to CAD + +TELOS is the intention layer in the CAD pipeline. Every Gitea issue +created in a CAD session should trace to a TELOS GOAL. Every GOAL +traces to a PROBLEM. + +Traceability chain: PROBLEM → GOAL → SPEC → TICKET → IMPL → TEST