@kudusov.takhir/ba-toolkit 3.6.0 → 3.8.0

package/skills/references/templates/principles-template.md

@@ -1,6 +1,7 @@
 # Project Principles: [PROJECT_NAME]
 
 **Version:** 1.0
+**Status:** Draft | In Review | Approved
 **Date:** [DATE]
 **Domain:** [DOMAIN]
 **Slug:** [SLUG]
@@ -23,6 +24,11 @@ All artifacts are generated in: [LANGUAGE]
 | API Endpoints | REST path | POST /users |
 | Wireframes | WF-NNN | WF-001 |
 | Validation Scenarios | SC-NNN | SC-001 |
+| Risks | RISK-NN | RISK-01 |
+| Sprints | SP-NN | SP-01 |
+| Implementation Tasks | T-NN-NNN | T-04-007 |
+| Analyse findings | A-NN | A-01 |
+| Brief Goals | G-N | G-1 |
 
 ## 3. Traceability Requirements
 
@@ -46,56 +52,109 @@ Optional links — violations flagged as **MEDIUM**:
 
 ## 4. Definition of Ready
 
-An artifact is ready to `/done` when all of the following are true:
+An artifact is ready to `/done` when all of the following are true. The baseline below mirrors the v3.7.0+ artifact-template field set; project-specific additions go in §8.
 
 ### Functional Requirement (FR)
 - [ ] Description present and unambiguous.
 - [ ] Actor identified (not "the system" or "the user" without role).
 - [ ] Priority assigned (MoSCoW).
 - [ ] Input/Output specified.
+- [ ] **Source** field present (which stakeholder, brief goal G-N, regulatory requirement, or parent FR drove this).
+- [ ] **Verification method** specified (Test / Demo / Inspection / Analysis per IEEE 830 §7).
+- [ ] **Rationale** documented (why this requirement exists, not just what).
+- [ ] FR is grouped under a feature area (`### 3.N` in `02_srs_*.md`).
 
 ### User Story (US)
-- [ ] Role, Action, and Value filled.
-- [ ] Priority assigned.
+- [ ] Persona named (named persona with role and one-line context, not bare job title).
+- [ ] Action and Value filled.
+- [ ] Priority assigned (MoSCoW).
+- [ ] **Business Value Score** assigned (1–5 or H/M/L).
+- [ ] **Size** estimate present (XS / S / M / L / XL or Story Points).
 - [ ] Linked FR reference present.
+- [ ] **Depends on** field set (other story IDs or `—`).
+- [ ] **Definition of Ready** checklist or reference to this principles section.
+- [ ] **INVEST self-check** confirms Independent · Negotiable · Valuable · Estimable · Small · Testable.
 
 ### Use Case (UC)
-- [ ] Actor, Preconditions, Main Flow, and at least one Exceptional Flow present.
-- [ ] Linked US reference present.
+- [ ] **Goal in Context** present (which Brief goal G-N this UC serves).
+- [ ] **Scope** specified (System / Subsystem / Component) and **Level** specified (User-goal / Summary / Subfunction).
+- [ ] Primary Actor and Supporting Actors listed.
+- [ ] **Stakeholders and Interests** table present (Cockburn discipline — at least 2 stakeholders).
+- [ ] Pre-conditions and Trigger present.
+- [ ] Main Success Scenario as a numbered table.
+- [ ] At least one Exception Flow present.
+- [ ] **Success Guarantees** and **Minimal Guarantees** distinguished in post-conditions.
+- [ ] **Source** field present (linked US/FR).
 
 ### Acceptance Criterion (AC)
-- [ ] Given / When / Then all present and specific.
-- [ ] Type specified (positive / negative / boundary).
+- [ ] Given / When / Then all present, specific, and verifiable (no "the system handles correctly").
+- [ ] **Type** specified (Positive / Negative / Boundary / Performance / Security).
+- [ ] **Source** present (which business rule from `02_srs_*.md` drove this AC).
+- [ ] **Verification** method specified (Automated test / Manual test / Observed in production).
 - [ ] Linked US reference present.
+- [ ] Linked NFR present for performance and security ACs.
 
 ### NFR
-- [ ] Category specified.
+- [ ] **ISO/IEC 25010 characteristic** specified (one of the 8: Functional Suitability / Performance Efficiency / Compatibility / Usability / Reliability / Security / Maintainability / Portability).
 - [ ] Measurable metric present (numeric target, not adjective).
+- [ ] **Acceptance threshold** present separately from the metric.
 - [ ] Verification method specified.
+- [ ] **Source** present.
+- [ ] **Rationale** present.
+- [ ] Linked FR or US present.
 
 ### Data Entity
-- [ ] All attributes have types and constraints.
-- [ ] FK references point to existing entities.
+- [ ] **Source** field present (which FR/US introduced this entity).
+- [ ] **Owner** field present (which team curates this data).
+- [ ] **Sensitivity classification** present (Public / Internal / Confidential / PII / PCI / PHI / Financial).
+- [ ] All attributes have **logical types** (not DBMS-specific) and constraints.
+- [ ] FK references point to existing entities, with cascade rule specified.
+- [ ] **State machine** documented for entities with more than two distinct lifecycle states.
 
 ### API Endpoint
+- [ ] **Source** present (FR-NNN that drove this endpoint).
 - [ ] Request and Response schemas present.
 - [ ] At least one error code documented.
 - [ ] Linked FR/US present.
+- [ ] **Idempotency** marker present (Idempotent / Not idempotent / Idempotent via `Idempotency-Key` header).
+- [ ] **Required scope** specified (or "public" for unauthenticated paths).
+- [ ] **SLO** linked to an NFR.
+- [ ] **Verification** method specified (contract test / consumer-driven contract test / integration test).
 
 ### Wireframe (WF)
-- [ ] All four states present: default, loading, empty, error.
+- [ ] **Source** present (US-NNN this screen serves).
+- [ ] All **8 canonical states** described that apply: Default / Loading / Empty / Loaded / Partial / Success / Error / Disabled.
 - [ ] Navigation links (from / to) specified.
 - [ ] Linked US present.
+- [ ] **Linked AC** present (scenarios this screen verifies).
+- [ ] **Linked NFR** present for performance- and accessibility-sensitive screens.
+
+### Risk
+- [ ] **Probability**, **Impact**, **Velocity** scored (per ISO 31000 + PMBOK 7).
+- [ ] **Treatment strategy** classified (Avoid / Reduce / Transfer / Accept).
+- [ ] **Owner** assigned.
+- [ ] **Review cadence** set.
+
+### Implementation Task (T-NN-NNN, from `/implement-plan`)
+- [ ] At least one `references` id present (FR / US / AC / Entity / Endpoint / WF / SC).
+- [ ] `dependsOn` list points only at task ids that exist in the same plan.
+- [ ] `definitionOfDone` checklist present, with at least one hook tied to a linked AC.
+- [ ] Phase assignment matches the canonical 9-phase ladder.
 
-## 5. NFR Baseline
+## 5. NFR Baseline (ISO/IEC 25010)
 
-The following NFR categories are required regardless of domain:
+NFR categories follow **ISO/IEC 25010:2011** Software Quality Model. The following ISO 25010 characteristics are required for this project regardless of domain — `/nfr` reads this list verbatim and treats it as a mandatory checklist:
 
-- **Security:** authentication method, data encryption at rest and in transit.
-- **Availability:** uptime SLA with a numeric target.
-- **Compliance:** applicable laws and data retention policy.
+- **Security** — confidentiality (encryption at rest and in transit), authentication strength, audit trail.
+- **Reliability** — availability SLA with a numeric target, RTO / RPO for disaster recovery.
+- **Compatibility** — applicable laws and data retention policy *(historically labelled "Compliance" but maps to ISO 25010 Compatibility + Functional Suitability sub-characteristics)*.
 
-[ADDITIONAL_NFR_CATEGORIES]
+[ADDITIONAL_NFR_CATEGORIES — list other ISO 25010 characteristics that are mandatory for this project, e.g.:
+- **Performance Efficiency** — required if the project has user-facing latency or throughput targets.
+- **Usability** — required if WCAG 2.1 AA accessibility is mandated.
+- **Maintainability** — required if the project must hand off to a different team post-launch.
+- **Portability** — required if multi-cloud or vendor-neutral hosting is a constraint.
+]
 
 ## 6. Quality Gates
 
@@ -113,6 +172,50 @@ For `/analyze` findings:
 - `flat` (default) — all artifacts saved directly in the output directory.
 - `subfolder` — all artifacts saved under `{output_dir}/[SLUG]/`.
 
-## 8. Project-Specific Notes
+## 8. Testing Strategy
+
+**Strategy:** TDD | Tests-after | Integration-only | Manual-only | None
+
+| Strategy | Means | When `/implement-plan` task templates embed "Tests to write first" |
+|----------|-------|--------------------------------------------------------------------|
+| TDD | Tests written before implementation; red → green → refactor | Yes — every task with linked AC gets a "Tests to write first" sub-block |
+| Tests-after | Implementation first, tests immediately after | No — task DoD just lists the AC scenarios that must pass |
+| Integration-only | No unit tests; integration tests at the API or UI layer | No — integration test harness is set up in Phase 1 |
+| Manual-only | Tests are manual QA scripts run before release | No — task DoD references manual scenario IDs from `/scenarios` |
+| None | Prototype / spike — no automated tests at all | No — explicit `// no test` marker on every task |
+
+`/implement-plan` reads this section to decide whether to embed test specifications in each task. Default is **TDD** for production-grade systems.
+
+## 9. Code Review and Branching
+
+**Branching model:** trunk-based | GitHub flow | GitFlow | other
+**Required reviewers per PR:** [N]
+**Merge gate:** [CI green + N reviews / CODEOWNERS approval / specific reviewer]
+
+## 10. Stakeholder Decision Authority
+
+Who can approve a change to these principles, and to which sections.
+
+| Section | Decision authority | Notes |
+|---------|--------------------|-------|
+| §1 Language | [Role] | |
+| §2 ID Conventions | [Role] | |
+| §3 Traceability | [Role] | |
+| §4 Definition of Ready | [Role] | |
+| §5 NFR Baseline | [Role] | |
+| §6 Quality Gates | [Role] | |
+| §7 Output Structure | [Role] | |
+| §8 Testing Strategy | [Role] | |
+| §9 Branching | [Role] | |
+
+## 11. Project-Specific Notes
 
 [ADDITIONAL_CONVENTIONS]
+
+---
+
+## Approvals
+
+| Name | Role | Approval Date | Notes |
+|------|------|---------------|-------|
+| [name] | [role] | [YYYY-MM-DD] | [optional notes] |

package/skills/references/templates/research-template.md

@@ -1,57 +1,81 @@
 # Technology Research & Architecture Decisions: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
+**ADR format:** Michael Nygard format extended with Drivers and Alternatives Considered
 **References:** `02_srs_[SLUG].md`, `06_nfr_[SLUG].md`, `07_datadict_[SLUG].md`
 
+> The output of this research is the **primary tech-stack source** for `/implement-plan` (added in v3.4.0). The Tech Stack table at the bottom is read by `/implement-plan` to populate its header without re-asking the calibration interview.
+
 ---
 
 ## Architecture Decision Records (ADRs)
 
 ### ADR-001: [Decision Title]
 
-**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-[NNN]
-**Date:** [DATE]
+| Field | Value |
+|-------|-------|
+| **Status** | Proposed / Accepted / Deprecated / Superseded by ADR-[NNN] |
+| **Proposal date** | [YYYY-MM-DD] |
+| **Decision date** | [YYYY-MM-DD when the decision was locked in] |
+| **Decision owner** | [Name + role] |
+
+**Drivers:** *(what forced this decision — reference specific FRs, NFRs, regulatory constraints, cost or time pressure)*
+- NFR-[NNN] — [why this NFR forces the decision]
+- FR-[NNN] — [why this FR forces the decision]
+- [Regulatory / cost / time-to-market constraint]
 
 **Context:**
-[What situation or requirement forces us to make this decision? Reference specific NFRs or FRs.]
+[What situation requires us to make this decision now. Background a future maintainer would need to understand the decision.]
 
-**Options Considered:**
+**Alternatives Considered:**
 
-| Option | Pros | Cons |
-|--------|------|------|
-| [Option A] | [pros] | [cons] |
-| [Option B] | [pros] | [cons] |
+| Option | Pros | Cons | Disqualifying factor |
+|--------|------|------|----------------------|
+| [Option A] | [pros] | [cons] | — |
+| [Option B] | [pros] | [cons] | [why ruled out] |
+| [Option C] | [pros] | [cons] | [why ruled out] |
 
-**Decision:** [Option A / B / other], because [rationale].
+**Decision:** [Option A / B / other], because [rationale anchored in the Drivers above].
 
 **Consequences:**
-- [Positive consequence]
-- [Trade-off or risk]
 
-**References:** NFR-[NNN], FR-[NNN]
+- **Positive:** [what becomes easier]
+- **Negative:** [trade-off or risk]
+- **Neutral:** [side effect that is neither good nor bad but worth noting]
 
 ---
 
 ### ADR-002: [Decision Title]
 
-**Status:** Proposed | Accepted
-**Date:** [DATE]
+| Field | Value |
+|-------|-------|
+| **Status** | [status] |
+| **Proposal date** | [date] |
+| **Decision date** | [date] |
+| **Decision owner** | [Name + role] |
 
-**Context:** [Context for this decision.]
+**Drivers:**
+- [driver]
 
-**Options Considered:**
+**Context:** [Context.]
 
-| Option | Pros | Cons |
-|--------|------|------|
-| [Option A] | [pros] | [cons] |
-| [Option B] | [pros] | [cons] |
+**Alternatives Considered:**
+
+| Option | Pros | Cons | Disqualifying factor |
+|--------|------|------|----------------------|
+| [Option A] | [pros] | [cons] | — |
+| [Option B] | [pros] | [cons] | [why ruled out] |
 
 **Decision:** [Chosen option and rationale.]
 
 **Consequences:**
-- [Consequence]
+
+- **Positive:** [consequence]
+- **Negative:** [consequence]
 
 <!-- Repeat ADR block for each major architectural decision. -->
 
@@ -95,5 +119,33 @@
 ## Open Questions
 
 | # | Question | Owner | Target Date |
-|---|---------|-------|-------------|
+|---|----------|-------|-------------|
 | 1 | [Unresolved technical question] | [Role] | [Date] |
+
+---
+
+## Tech Stack Summary *(consumed by `/implement-plan`)*
+
+This table is the primary tech-stack source for `/implement-plan`. Every row should have a concrete value (or `[TBD: <slot>]` if the decision is genuinely deferred). `/implement-plan` skips its own calibration interview when this table is complete.
+
+| Layer | Choice | Source ADR |
+|-------|--------|------------|
+| Frontend | [framework + language + build tool] | ADR-[NNN] |
+| Backend | [framework + language + runtime] | ADR-[NNN] |
+| Database | [engine + version + hosting] | ADR-[NNN] |
+| Hosting / deployment | [cloud + region + container model] | ADR-[NNN] |
+| Auth / identity | [in-house / SSO / managed service] | ADR-[NNN] |
+| Observability | [logs + metrics + traces platform] | ADR-[NNN] |
+| Mandatory integrations | [list from §Integration Map] | — |
+
+---
+
+## NFR → ADR Traceability
+
+Forward traceability from each Non-functional Requirement in `06_nfr_[SLUG].md` to the ADR(s) that satisfy it. NFRs without a linked ADR are flagged — every Must-priority NFR should drive at least one architectural decision.
+
+| NFR ID | ISO 25010 Characteristic | Linked ADRs | Coverage Status |
+|--------|--------------------------|-------------|-----------------|
+| NFR-001 | Performance Efficiency | ADR-002, ADR-005 | ✓ |
+| NFR-003 | Reliability | ADR-004 | ✓ |
+| NFR-005 | Security | (uncovered) | ✗ |

package/skills/references/templates/risk-template.md

@@ -1,188 +1,89 @@
-# Risk Register: {PROJECT_NAME}
+# Risk Register: [PROJECT_NAME]
 
-**Domain:** {DOMAIN}
-**Date:** {DATE}
-**Slug:** {SLUG}
-**Sources:** {list of artifacts scanned}
+**Version:** 0.1
+**Status:** Draft
+**Domain:** [DOMAIN]
+**Date:** [DATE]
+**Slug:** [SLUG]
+**Risk tolerance:** Low / Medium / High
+**Standard:** ISO 31000 + PMI PMBOK 7
+**Sources:** [list of artifact files scanned]
 
 ---
 
 ## Summary
 
 | Priority | Count |
-|---------|-------|
-| 🔴 Critical | 1 |
-| 🟡 High | 2 |
-| 🟢 Medium | 3 |
-| ⚪ Low | 1 |
-| **Total** | **7** |
+|----------|-------|
+| 🔴 Critical | [N] |
+| 🟡 High | [N] |
+| 🟢 Medium | [N] |
+| ⚪ Low | [N] |
+| **Total** | **[N]** |
 
 ---
 
 ## Risk Register
 
-| ID | Title | Category | Probability | Impact | Score | Priority | Status |
-|----|-------|----------|:-----------:|:------:|:-----:|---------|--------|
-| RISK-01 | Third-party data source rate limits unclear | External | 4 | 5 | 20 | 🔴 Critical | Open |
-| RISK-02 | GDPR data-processing agreement unsigned | Compliance | 3 | 4 | 12 | 🟡 High | Open |
-| RISK-03 | Columnar query performance under concurrent load unproven | Technical | 3 | 3 | 9 | 🟡 High | Open |
-| RISK-04 | Scope creep from stakeholder wish list | Business | 3 | 2 | 6 | 🟢 Medium | Open |
-| RISK-05 | OIDC / SSO library breaking changes | External | 2 | 3 | 6 | 🟢 Medium | Open |
-| RISK-06 | Data model changes after /datadict | Technical | 2 | 3 | 6 | 🟢 Medium | Open |
-| RISK-07 | Development team unfamiliar with analytics domain | Business | 2 | 1 | 2 | ⚪ Low | Open |
+| ID | Title | Category | P | I | Score | V | Priority | Treatment | Owner | Review | Status |
+|----|-------|----------|:-:|:-:|:-----:|:-:|----------|-----------|-------|--------|--------|
+| RISK-01 | [Short title] | Technical / Business / Compliance / External | 4 | 5 | 20 | Days | 🔴 Critical | Reduce | [Owner] | Monthly | Open |
+| RISK-02 | [Short title] | [Category] | [1–5] | [1–5] | [P×I] | [Velocity] | [Priority] | [Avoid / Reduce / Transfer / Accept] | [Owner] | [Cadence] | Open / In Progress / Closed |
 
----
-
-## Risk Details
-
-### RISK-01 — Third-party data source rate limits unclear
-
-**Category:** External
-**Probability:** 4 / 5 — Likely
-**Impact:** 5 / 5 — Critical
-**Score:** 20 🔴 Critical
-**Status:** Open
-**Source:** `07a_research_{slug}.md`
-
-**Description:**
-The product depends on timely event delivery from third-party integrations (Segment and warehouse connectors). The published rate limits do not guarantee sustained throughput at the projected MVP event volume. If a critical integration is rate-limited or breaks its contract, dashboards will show stale or incomplete data and user trust erodes quickly.
-
-**Mitigation:**
-Run a sustained-throughput test against each integration in sprint 0. Negotiate higher quotas with the providers before launch. Add per-source ingestion lag as a monitored NFR metric with an alert threshold.
-
-**Contingency:**
-Enable an ingestion backpressure queue and surface a workspace-level banner when a source is lagging more than 5 minutes behind real-time. Prioritise critical event streams over low-value ones until the lag recovers.
-
-**Owner:** Tech Lead
+> Columns: P = Probability (1–5), I = Impact (1–5), Score = P × I, V = Velocity (Years / Months / Weeks / Days / Immediate). Treatment: Avoid / Reduce / Transfer / Accept. Review: Monthly / Quarterly / Ad hoc.
 
 ---
 
-### RISK-02 — GDPR data-processing agreement unsigned
-
-**Category:** Compliance
-**Probability:** 3 / 5 — Possible
-**Impact:** 4 / 5 — Major
-**Score:** 12 🟡 High
-**Status:** Open
-**Source:** `01_brief_{slug}.md`
-
-**Description:**
-The product collects first-party user-behavioural events from EU workspaces. The Brief listed the GDPR data-processing agreement (DPA) with the selected cloud provider as an assumption. If the DPA is delayed or blocked by legal review, the EU launch date will slip regardless of development readiness.
-
-**Mitigation:**
-Engage legal counsel early to track DPA status. Decouple development milestones from the legal timeline so that technical readiness does not block on paperwork. Draft the workspace-level privacy controls (PII redaction, data residency) independently of the final DPA text.
-
-**Contingency:**
-Launch in non-EU regions first (US, CA, APAC) while the EU DPA is pending. Gate EU workspace signups behind a feature flag tied to DPA status.
-
-**Owner:** Product Manager
-
----
-
-### RISK-03 — Columnar query performance under concurrent load unproven
-
-**Category:** Technical
-**Probability:** 3 / 5 — Possible
-**Impact:** 3 / 5 — Moderate
-**Score:** 9 🟡 High
-**Status:** Open
-**Source:** `07a_research_{slug}.md`
-
-**Description:**
-The ADR for the analytics query layer chose ClickHouse as the primary store. This setup has not been load-tested for the projected 200 concurrent dashboard viewers reading against a 10 M-event dataset. If query throughput assumptions are wrong, dashboards will exceed the 500 ms p95 NFR target and degrade UX.
-
-**Mitigation:**
-Run a load-test spike in the first development sprint against the reference dataset. Define a caching fallback (5-minute materialised query cache) if raw query throughput does not meet targets.
-
-**Contingency:**
-Enable the query cache globally and mark cached dashboards with a "last refreshed" timestamp. Communicate the change as a phased rollout feature.
-
-**Owner:** Tech Lead
-
----
-
-### RISK-04 — Scope creep from stakeholder wish list
-
-**Category:** Business
-**Probability:** 3 / 5 — Possible
-**Impact:** 2 / 5 — Minor
-**Score:** 6 🟢 Medium
-**Status:** Open
-**Source:** `01_brief_{slug}.md`
-
-**Description:**
-Several features were marked out of scope during the Brief interview but stakeholders indicated they "might be needed later." Without a change control process, these may be re-introduced mid-development, inflating the MVP scope.
-
-**Mitigation:**
-Establish a formal change request process referenced in the Handoff document. All scope additions must go through `/stories` and be re-estimated.
-
-**Contingency:**
-Freeze scope at the start of each sprint. Defer any mid-sprint scope additions to the next sprint backlog.
-
-**Owner:** Product Manager
-
----
-
-### RISK-05 — OIDC / SSO library breaking changes
-
-**Category:** External
-**Probability:** 2 / 5 — Unlikely
-**Impact:** 3 / 5 — Moderate
-**Score:** 6 🟢 Medium
-**Status:** Open
-**Source:** `07a_research_{slug}.md`
-
-**Description:**
-The product uses a third-party OIDC / SAML library for workspace SSO. Similar libraries have released breaking changes in previous majors without long deprecation windows. If the library releases a breaking change after development, sign-up and SSO flows may require rework.
-
-**Mitigation:**
-Pin the library version used in development. Monitor the library changelog and security advisories. Abstract SSO calls behind a thin adapter layer so a future swap to a different provider is isolated to one module.
-
-**Contingency:**
-Allocate a 3-day buffer in the release plan for library compatibility fixes.
-
-**Owner:** Frontend Lead
-
----
-
-### RISK-06 — Data model changes after /datadict
+## Risk Details
 
-**Category:** Technical
-**Probability:** 2 / 5 — Unlikely
-**Impact:** 3 / 5 — Moderate
-**Score:** 6 🟢 Medium
-**Status:** Open
-**Source:** `07_datadict_{slug}.md`
+### RISK-01 — [Short title]
+
+| Field | Value |
+|-------|-------|
+| **Category** | Technical / Business / Compliance / External |
+| **Probability** | [1–5] — [Very unlikely / Unlikely / Possible / Likely / Very likely] |
+| **Impact** | [1–5] — [Negligible / Minor / Moderate / Major / Critical] |
+| **Score** | [P × I] [🔴/🟡/🟢/⚪ priority] |
+| **Velocity** | [Years / Months / Weeks / Days / Immediate] — [reaction-time implication] |
+| **Treatment strategy** | Avoid / Reduce / Transfer / Accept |
+| **Status** | Open / In Progress / Closed |
+| **Source** | [artifact file + section] |
+| **Owner** | [Single accountable role — e.g. Tech Lead, Product Manager, Compliance Officer] |
+| **Review cadence** | Monthly / Quarterly / Ad hoc |
 
 **Description:**
-The Data Dictionary was finalised before the API Contract was fully detailed. Late-stage entity or field changes discovered during API design may require cascading updates across the SRS, Stories, and AC artifacts.
+[Full description of the risk and the conditions under which it materialises. State the condition and the consequence — "If X happens, then Y will occur."]
 
-**Mitigation:**
-Run `/trace` after `/apicontract` to detect any new cross-artifact inconsistencies. Address CRITICAL gaps before handoff.
+**Mitigation:** *(actions taken before the risk materialises — Reduce strategy)*
+[Steps to lower the probability or impact. Required for all Reduce-strategy risks. Optional for Avoid (mitigation = the avoidance action itself), Transfer (mitigation = the transfer mechanism), and Accept (mitigation = N/A by definition).]
 
-**Contingency:**
-Use `/revise` on affected artifacts to propagate changes. Document the delta in the Handoff open items list.
-
-**Owner:** Business Analyst
+**Contingency:** *(actions taken after the risk materialises despite mitigation)*
+[Steps to take if the risk fires anyway. Required for High and Critical risks regardless of treatment strategy.]
 
 ---
 
-### RISK-07 — Development team unfamiliar with analytics domain
-
-**Category:** Business
-**Probability:** 2 / 5 — Unlikely
-**Impact:** 1 / 5 — Negligible
-**Score:** 2 ⚪ Low
-**Status:** Open
-**Source:** `01_brief_{slug}.md`
+### RISK-02 — [Short title]
+
+| Field | Value |
+|-------|-------|
+| **Category** | [Category] |
+| **Probability** | [1–5] |
+| **Impact** | [1–5] |
+| **Score** | [P × I] |
+| **Velocity** | [Velocity] |
+| **Treatment strategy** | [Strategy] |
+| **Status** | Open |
+| **Source** | [artifact + section] |
+| **Owner** | [Owner] |
+| **Review cadence** | [Cadence] |
 
 **Description:**
-The engineering team has limited prior experience with columnar analytics storage. Domain-specific concepts (event schemas, funnel aggregation, cohort joins) may be misunderstood during implementation, leading to query correctness bugs on edge cases.
+[Description.]
 
 **Mitigation:**
-Include a domain onboarding session as part of sprint 0. Reference the SaaS domain glossary in the Handoff document.
+[Mitigation steps.]
 
 **Contingency:**
-Schedule a BA review checkpoint after the first feature is implemented end-to-end.
+[Contingency steps.]
 
-**Owner:** Product Manager
+<!-- Repeat RISK block for each risk. Numbering: RISK-01, RISK-02, ... -->