@kudusov.takhir/ba-toolkit 3.4.1 → 3.5.0

package/CHANGELOG.md

@@ -11,6 +11,36 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [3.5.0] — 2026-04-09
+
+### Highlights
+
+- **Pilot skill audit pass on `/brief`, `/srs`, `/stories`** — 14 senior-BA findings (6 Critical + 8 High) applied. Three skills now match the rigour a 25-year BA from a top-tier consultancy would expect: `/brief` separates Constraints from Assumptions and forces an explicit Out of Scope section, `/srs` adds Source / Verification / Rationale per FR plus a Brief-Goal → FR traceability matrix, `/stories` makes INVEST a quality gate and adds Persona / Business Value / Dependencies fields.
+
+### Changed
+
+- **`skills/brief/SKILL.md` and `skills/references/templates/brief-template.md`** — six findings applied:
+  - **Section numbering bug fixed** — workflow steps no longer jump from §6 to §8 (renumbered §8 → §7, §9 → §8). Was a sloppiness flag for any reviewer opening the file.
+  - **Out of Scope section is now mandatory** — added §4.2 to the artifact template. A brief is a contract; what is excluded matters as much as what is included. Without this, scope creep starts on the first standup.
+  - **Constraints and Assumptions split into two sections** (§6 and §7 in the new template). They have different change-management implications and BABOK v3 separates them. Constraints carry `Type / Source / Implication`; Assumptions carry `Statement / Owner / Validate by / Risk if false`.
+  - **Required-topics list extended from 7 to 11.** Added the four canonical brief inquiries every senior BA asks: buyer-vs-user separation, decision-making authority (who can sign off, by name and role), regulatory pre-screening (yes/no per regime: GDPR, HIPAA, FDA SaMD, SOC 2, PCI DSS, SOX, KYC/AML, FERPA, COPPA, EU AI Act, accessibility), and explicit failure criteria (asymmetric to success criteria — flushes out red lines).
+  - **Document control metadata added to the template** — `Version`, `Status` (Draft / In Review / Approved / Superseded), and an `Approvals` table at the bottom. A brief is a controlled document and needs to answer "which version did we agree to?" three months in.
+  - **Stakeholder table gains a "Sign-off authority" column** so the brief records not just who is interested but who has veto power.
+- **`skills/srs/SKILL.md` and `skills/references/templates/srs-template.md`** — four findings applied:
+  - **FR template gains three IEEE 830-mandated fields:** `Source` (which stakeholder, brief goal, regulatory requirement, or parent FR drove this requirement — required for traceability), `Verification` (Test / Demo / Inspection / Analysis — without it an FR is a wish, not a contract), `Rationale` (*why* this requirement exists, not just *what* — helps future maintainers know what is safe to push back on).
+  - **New §7 "Traceability — Brief Goal → FR" table.** Forward traceability from `01_brief_<slug>.md` §2 business goals to the FRs that satisfy them. Every Brief goal must have at least one linked FR; uncovered goals are flagged so they cannot silently disappear from the project.
+  - **§3 Functional Requirements is now grouped by feature area** as `### 3.N [Area name]` subsections, each with a reserved FR-ID range (FR-001..099 for area 1, FR-100..199 for area 2, …). New FRs inserted later go into their area's free numbers, not the global tail — IDs stay stable. Was a flat list, which became unreadable for any non-trivial system.
+  - **Required-topics list extended from 6 to 11.** Added the five universal SRS inquiries that downstream skills (`/datadict`, `/nfr`, `/apicontract`) inherit gaps from when they're missing: authentication and authorisation model (SSO / SAML / OIDC / RBAC / ABAC / MFA), data ownership and stewardship, audit and logging requirements, data retention and deletion (GDPR right-to-erasure), reporting needs.
+- **`skills/stories/SKILL.md` and `skills/references/templates/stories-template.md`** — five findings applied:
+  - **SKILL.md inline template removed in favour of a single source of truth at `references/templates/stories-template.md`.** Previously the inline template and the standalone file had drifted apart (the inline version had no `Size:` field and an inline AC reference; the standalone had `Size:` and a file-path AC reference). Two agents reading different parts produced different outputs. The SKILL.md now lists the field set and points at the standalone template; the standalone template is the only place that carries the per-story block layout.
+  - **INVEST is now an explicit quality gate.** The template has an `INVEST self-check:` line per story (Independent · Negotiable · Valuable · Estimable · Small · Testable). The `/validate` command description now requires every story to pass INVEST. The `/split` guidance references INVEST's "Small" / "Independent" criteria and Mike Cohn's nine story-splitting patterns instead of the previous arbitrary "more than 3 scenarios" rule.
+  - **Persona field replaces bare role.** Stories now use `**As** [Maria, ops supervisor at a 50-warehouse 3PL handling 200 returns/week]` instead of `**As an** admin`. Personas carry goals, frustrations, and context that drive UX decisions; bare job titles do not.
+  - **Business Value Score field added** (1–5 or High / Med / Low). Captures relative ranking *within* the same MoSCoW priority tier so a PM can sequence among 30 Must stories instead of treating them as interchangeable.
+  - **Depends on field added** so story-to-story dependencies are visible to `/sprint` and `/implement-plan`. A story that can't start until US-007 is done now says so in the template and won't get planned in the wrong sprint.
+  - **New "FR → Story coverage matrix" sub-table in the Coverage Summary.** Forward traceability from FR to US, with `(uncovered)` flag for any FR missing a linked story. Was previously a manual cross-reference task.
+
+---
+
 ## [3.4.1] — 2026-04-09
 
 ### Fixed
@@ -511,7 +541,8 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.4.1...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.5.0...HEAD
+[3.5.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.4.1...v3.5.0
 [3.4.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.4.0...v3.4.1
 [3.4.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.2.0...v3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "AI-powered Business Analyst pipeline — 24 skills from concept discovery to a sequenced implementation plan an AI coding agent can execute, with one-command Notion + Confluence publish. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf.",
   "keywords": [
     "business-analyst",

package/skills/brief/SKILL.md

@@ -48,10 +48,14 @@ Cover 3–7 topics per round, 2–4 rounds. Do not generate the artifact until s
 1. Product type — what exactly is being built?
 2. Business goal — what problem does the product solve?
 3. Target audience and geography.
-4. Key stakeholders — who is interested, who makes decisions?
-5. Known constraints — deadlines, budget, regulatory requirements, mandatory integrations.
-6. Competitive products or references.
-7. Success criteria — specific metrics or qualitative goals.
+4. **Buyer vs. user separation** — who pays for the product vs. who uses it day-to-day? In B2B SaaS, EdTech, healthcare and many other domains these are different people with different priorities. If they coincide, record "buyer = user".
+5. Key stakeholders — who is interested, who makes decisions?
+6. **Decision-making authority** — who can sign off on the brief now, and who can sign off on changes later? Capture by name and role, not just by team.
+7. **Regulatory pre-screening** — which of the following regimes apply: GDPR / UK GDPR, HIPAA, FDA SaMD, SOC 2, PCI DSS, SOX, KYC / AML, FERPA / COPPA, EU AI Act, accessibility (Section 508 / WCAG / EN 301 549)? Single yes/no per regime — gates the rest of the pipeline.
+8. Known constraints — deadlines, budget, technology mandates, mandatory integrations.
+9. Reference products and analogues — products in this space the user admires (and why), products that failed (and why). Anchors the project to real-world references and surfaces unstated requirements.
+10. Success criteria — specific metrics or qualitative goals.
+11. **Failure criteria** — what would make us call this project a failure? Asymmetric to success criteria; flushes out red lines that "what's success" never reveals.
 
 If a domain reference is loaded, supplement general questions with domain-specific ones. Formulate questions concretely, with example answers in parentheses.
 
@@ -62,17 +66,37 @@ If a domain reference is loaded, supplement general questions with domain-specif
 ```markdown
 # Project Brief: {Project Name}
 
+**Version:** 0.1
+**Status:** Draft | In Review | Approved | Superseded
 **Domain:** {saas | fintech | ecommerce | healthcare | logistics | on-demand | social-media | real-estate | igaming | edtech | govtech | ai-ml | custom:{name}}
 **Date:** {date}
+**Slug:** {slug}
 
 ## 1. Project Summary
 ## 2. Business Goals and Success Metrics
 ## 3. Target Audience
+   ### 3.1 Buyer
+   ### 3.2 User (if different from Buyer)
 ## 4. High-Level Functionality Overview
-## 5. Stakeholders and Roles
-## 6. Constraints and Assumptions
-## 7. Risks
-## 8. Glossary
+   ### 4.1 In Scope
+   ### 4.2 Out of Scope
+## 5. Stakeholders and Decision-Making Authority
+## 6. Constraints
+## 7. Assumptions
+## 8. Risks
+## 9. Success and Failure Criteria
+   ### 9.1 Success Criteria
+   ### 9.2 Failure Criteria
+## 10. Reference Products and Analogues
+## 11. Glossary
+
+---
+
+## Approvals
+
+| Name | Role | Approval Date | Notes |
+|------|------|---------------|-------|
+| {name} | {role} | {date} | {notes} |
 ```
 
 ### 6. AGENTS.md update
@@ -83,7 +107,7 @@ If a domain reference is loaded, supplement general questions with domain-specif
 
 If you find no `AGENTS.md` at all (neither in cwd nor up the tree), warn the user that the project was likely set up before v3.1 and tell them to run `ba-toolkit init --name "..." --slug {slug}` to scaffold the per-project `AGENTS.md`. Do not create one yourself with arbitrary structure.
 
-### 8. Iterative refinement
+### 7. Iterative refinement
 
 - `/revise [section]` — rewrite a section.
 - `/expand [section]` — add detail.
@@ -91,7 +115,7 @@ If you find no `AGENTS.md` at all (neither in cwd nor up the tree), warn the use
 - `/validate` — check completeness and consistency.
 - `/done` — finalize and update `AGENTS.md`. Next step: `/srs`.
 
-### 9. Closing message
+### 8. Closing message
 
 After saving the artifact, present the following summary to the user (see `references/closing-message.md` for format):
 

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

@@ -1,5 +1,7 @@
 # Project Brief: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
@@ -11,41 +13,99 @@
 ## 2. Business Goals and Success Metrics
 
 | # | Goal | Success Metric |
-|---|------|---------------|
+|---|------|----------------|
 | 1 | [goal] | [measurable metric] |
 
 ## 3. Target Audience
 
+### 3.1 Buyer
+
+[Who pays for the product. Decision criteria, budget cycle, procurement constraints.]
+
+| Segment | Description | Geography |
+|---------|-------------|-----------|
+| [segment] | [description] | [region] |
+
+### 3.2 User (if different from Buyer)
+
+[Who actually uses the product day to day. Skip this section if buyer = user.]
+
 | Segment | Description | Geography |
 |---------|-------------|-----------|
 | [segment] | [description] | [region] |
 
 ## 4. High-Level Functionality Overview
 
-[2–4 paragraphs or bullet list of the main functional areas. No technical detail — what the system does, not how.]
+### 4.1 In Scope
+
+[2–4 paragraphs or bullet list of the main functional areas that ARE part of the first release. No technical detail — what the system does, not how.]
+
+### 4.2 Out of Scope
+
+[Explicit list of capabilities that are NOT in scope for this brief. A brief is a contract — what is excluded matters as much as what is included. Use this section to head off scope creep on day one.]
+
+- [out-of-scope item with one-line reason]
+
+## 5. Stakeholders and Decision-Making Authority
+
+| Role | Responsibility | Interest | Sign-off authority |
+|------|----------------|----------|--------------------|
+| [role] | [what they do] | [what they care about] | Yes / No / Veto only |
 
-## 5. Stakeholders and Roles
+## 6. Constraints
 
-| Role | Responsibility | Interest |
-|------|---------------|---------|
-| [role] | [what they do] | [what they care about] |
+Imposed facts that cannot be changed during the project. Each constraint has a source (regulatory, contractual, technical, organisational) and an implication.
 
-## 6. Constraints and Assumptions
+| # | Constraint | Type | Source | Implication |
+|---|------------|------|--------|-------------|
+| 1 | [constraint] | Regulatory / Contractual / Technical / Organisational | [source] | [what this forces or forbids] |
 
-**Constraints:**
-- [constraint]
+## 7. Assumptions
 
-**Assumptions:**
-- [assumption]
+Beliefs we have made about the world that may turn out wrong. Each assumption has an owner and a validation date — if invalidated, the assumption becomes a risk and the owner must escalate.
 
-## 7. Risks
+| # | Assumption | Owner | Validate by | Risk if false |
+|---|------------|-------|-------------|---------------|
+| 1 | [assumption] | [name / role] | [date] | [what breaks if this turns out false] |
+
+## 8. Risks
 
 | # | Risk | Probability | Impact | Mitigation |
-|---|------|-------------|--------|-----------|
-| 1 | [risk] | High/Med/Low | High/Med/Low | [mitigation] |
+|---|------|-------------|--------|------------|
+| 1 | [risk] | High / Med / Low | High / Med / Low | [mitigation] |
+
+## 9. Success and Failure Criteria
+
+### 9.1 Success Criteria
+
+[Specific, measurable conditions that, if met, mean the project succeeded. Reference business goals from §2 where applicable.]
+
+- [criterion]
+
+### 9.2 Failure Criteria
+
+[Specific conditions that, if met, mean the project should be paused or cancelled. Asymmetric to success criteria — these are red lines, not "less than success".]
 
-## 8. Glossary
+- [criterion]
+
+## 10. Reference Products and Analogues
+
+| Product | What it does well | What it does badly / misses | Relevance |
+|---------|-------------------|-----------------------------|-----------|
+| [name] | [one line] | [one line] | [why it matters to this project] |
+
+## 11. Glossary
+
+The project's source-of-truth glossary. Propagated to all subsequent artifacts (`/srs`, `/stories`, `/glossary`). Add a term here once and reuse the same definition everywhere downstream.
 
 | Term | Definition |
-|------|-----------|
+|------|------------|
 | [term] | [definition] |
+
+---
+
+## Approvals
+
+| Name | Role | Approval Date | Notes |
+|------|------|---------------|-------|
+| [name] | [role] | [YYYY-MM-DD] | [optional notes] |

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

@@ -1,9 +1,11 @@
 # Software Requirements Specification (SRS): [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
-**Reference:** [01_brief_SLUG.md]
+**Reference:** `01_brief_[SLUG].md`
 
 ## 1. Introduction
 
@@ -18,7 +20,7 @@
 ### 1.3 Definitions and Abbreviations
 
 | Term | Definition |
-|------|-----------|
+|------|------------|
 | [term] | [definition] |
 
 ### 1.4 Document References
@@ -34,7 +36,7 @@
 ### 2.2 User Roles
 
 | Role | Description | Permissions |
-|------|-------------|------------|
+|------|-------------|-------------|
 | [role] | [description] | [what they can do] |
 
 ### 2.3 Constraints
@@ -47,16 +49,37 @@
 
 ## 3. Functional Requirements
 
-### FR-001: [Title]
+> **Grouping rule:** FRs are grouped by feature area as `### 3.N [Area name]` subsections. Each area gets a reserved numeric range (FR-001..099 for area 1, FR-100..199 for area 2, …). New FRs inserted later go into their area's free numbers, not the global tail — IDs stay stable.
+
+### 3.1 [Feature Area Name]
+
+#### FR-001: [Title]
 
 - **Description:** [What the system must do.]
 - **Actor:** [Role that triggers or benefits from this requirement.]
 - **Input:** [What data or event initiates this.]
 - **Output / Result:** [What the system produces or changes.]
 - **Business Rules:** [Formulas, limits, conditions.]
+- **Source:** [Stakeholder name, Brief goal G-N, regulatory requirement, or parent FR-NNN. Required for traceability.]
+- **Verification:** Test | Demo | Inspection | Analysis
+- **Rationale:** [Why this requirement exists. Not what — why. Helps future maintainers know what is safe to push back on.]
 - **Priority:** Must | Should | Could | Won't
 
-<!-- Repeat for each FR. Numbering: FR-001, FR-002, ... -->
+<!-- Repeat #### FR block for each requirement in this area. Numbering: FR-001, FR-002, ... within the area's reserved range. -->
+
+### 3.2 [Next Feature Area Name]
+
+#### FR-100: [Title]
+
+- **Description:** ...
+- **Actor:** ...
+- **Input:** ...
+- **Output / Result:** ...
+- **Business Rules:** ...
+- **Source:** ...
+- **Verification:** Test | Demo | Inspection | Analysis
+- **Rationale:** ...
+- **Priority:** Must | Should | Could | Won't
 
 ## 4. Interface Requirements
 
@@ -83,8 +106,18 @@ _(Detailed in `/nfr` artifact — `06_nfr_[SLUG].md`)_
 ## 6. Priority Matrix (MoSCoW)
 
 | Priority | FR Count | FR IDs |
-|----------|---------|--------|
-| Must | [n] | FR-001, FR-002, … |
-| Should | [n] | … |
-| Could | [n] | … |
-| Won't | [n] | … |
+|----------|----------|--------|
+| Must     | [n]      | FR-001, FR-002, … |
+| Should   | [n]      | … |
+| Could    | [n]      | … |
+| Won't    | [n]      | … |
+
+## 7. Traceability — Brief Goal → FR
+
+Forward traceability from the Project Brief's business goals to the FRs that satisfy them. Every Brief goal listed in `01_brief_[SLUG].md` §2 must have at least one linked FR; uncovered goals are flagged here as `(uncovered)` so they cannot silently disappear from the project.
+
+| Goal ID | Goal Description (from `01_brief_[SLUG].md` §2) | Linked FRs |
+|---------|--------------------------------------------------|------------|
+| G1      | [goal text] | FR-001, FR-007, FR-014 |
+| G2      | [goal text] | FR-003 |
+| G3      | [goal text] | (uncovered) |

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

@@ -8,7 +8,7 @@
 ## Epic Index
 
 | # | Epic | User Stories |
-|---|------|-------------|
+|---|------|--------------|
 | E-01 | [Epic name] | US-001 – US-00N |
 
 ---
@@ -19,28 +19,38 @@
 
 ### US-001: [Story title]
 
-**As a** [role],
+**As** [Persona — named persona with role and one-line context, e.g. "Maria, ops supervisor at a 50-warehouse 3PL handling 200 returns/week"],
 **I want to** [action],
 **so that** [benefit].
 
+**Persona:** [name + role + context]
 **Acceptance Criteria:** → `05_ac_[SLUG].md` → US-001
 **FR Reference:** FR-[NNN]
 **Priority:** Must | Should | Could | Won't
+**Business Value Score:** 1–5  *(captures relative ranking within the same MoSCoW tier)*
 **Size:** XS | S | M | L | XL
+**Depends on:** US-[NNN], US-[NNN]  *(or `—` if independent)*
+**Definition of Ready:** [checklist or "see `00_principles_[SLUG].md` §4 / §6"]
+**INVEST self-check:** Independent ✓ · Negotiable ✓ · Valuable ✓ · Estimable ✓ · Small ✓ · Testable ✓
 **Notes:** [Edge cases, out-of-scope clarifications.]
 
 ---
 
 ### US-002: [Story title]
 
-**As a** [role],
+**As** [Persona],
 **I want to** [action],
 **so that** [benefit].
 
+**Persona:** [name + role + context]
 **Acceptance Criteria:** → `05_ac_[SLUG].md` → US-002
 **FR Reference:** FR-[NNN]
 **Priority:** Must | Should | Could | Won't
+**Business Value Score:** 1–5
 **Size:** XS | S | M | L | XL
+**Depends on:** —
+**Definition of Ready:** [checklist or reference]
+**INVEST self-check:** Independent ✓ · Negotiable ✓ · Valuable ✓ · Estimable ✓ · Small ✓ · Testable ✓
 **Notes:** [Edge cases, out-of-scope clarifications.]
 
 <!-- Repeat US block for each story. Numbering: US-001, US-002, ... -->
@@ -49,12 +59,24 @@
 
 ## Coverage Summary
 
+### By priority
+
 | Priority | Story Count | Story IDs |
-|----------|------------|-----------|
+|----------|-------------|-----------|
 | Must     | [n] | US-001, … |
 | Should   | [n] | … |
 | Could    | [n] | … |
 | Won't    | [n] | … |
 
+### FR → Story coverage matrix
+
+Forward traceability from each Functional Requirement in `02_srs_[SLUG].md` to the User Stories that implement it. Every Must-priority FR must have at least one Must-priority story; uncovered FRs are flagged here as `(uncovered)`.
+
+| FR ID | FR Title (from SRS) | Linked Stories | Coverage Status |
+|-------|---------------------|----------------|-----------------|
+| FR-001 | [title] | US-001, US-007 | ✓ |
+| FR-002 | [title] | US-003 | ✓ |
+| FR-003 | [title] | (uncovered) | ✗ |
+
 **Total stories:** [N]
 **Total epics:** [N]

package/skills/srs/SKILL.md

@@ -31,11 +31,16 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 **Required topics:**
 1. User roles — which roles interact with the system?
-2. External integrations — which systems require connection?
-3. Multi-language and multi-currency support — if applicable.
-4. Regulatory requirements — which standards and laws apply?
-5. Prioritization method — MoSCoW (Must, Should, Could, Won't) or other.
-6. Key business rules — limits, thresholds, calculation formulas.
+2. **Authentication and authorisation model** — how do users authenticate (password / SSO / SAML / OIDC / passwordless)? RBAC or ABAC? Preset roles or custom? Multi-factor for which roles?
+3. External integrations — which systems require connection?
+4. Multi-language and multi-currency support — if applicable.
+5. Regulatory requirements — which standards and laws apply?
+6. **Data ownership and stewardship** — who owns each data class? Who can read it? Who can correct it? Who is liable if it leaks?
+7. **Audit and logging** — which events must be logged for SOC 2 / SOX / regulatory audit? What is the log retention period?
+8. **Data retention and deletion** — how long is each data class retained? What is the deletion policy under GDPR right-to-erasure (and equivalent local laws)?
+9. **Reporting needs** — which reports must the system produce, for whom, on what cadence, in what format?
+10. Prioritization method — MoSCoW (Must, Should, Could, Won't) or other.
+11. Key business rules — limits, thresholds, calculation formulas.
 
 Supplement with domain-specific questions and typical functional areas from the reference.
 
@@ -46,6 +51,13 @@ Supplement with domain-specific questions and typical functional areas from the
 ```markdown
 # Software Requirements Specification (SRS): {Name}
 
+**Version:** 0.1
+**Status:** Draft | In Review | Approved
+**Domain:** {domain}
+**Date:** {date}
+**Slug:** {slug}
+**Reference:** 01_brief_{slug}.md
+
 ## 1. Introduction
 ### 1.1 Purpose
 ### 1.2 Scope
@@ -59,12 +71,20 @@ Supplement with domain-specific questions and typical functional areas from the
 ### 2.4 Assumptions and Dependencies
 
 ## 3. Functional Requirements
-### FR-{NNN}: {Title}
-- **Description:** ...
-- **Actor:** ...
-- **Input:** ...
-- **Output / Result:** ...
-- **Business Rules:** ...
+
+**Grouping rule:** FRs are grouped by feature area as `### 3.N [Area name]` subsections (e.g. `### 3.1 Authentication`, `### 3.2 Catalog`, `### 3.3 Checkout`). Each area gets a reserved numeric range (FR-001..099 for area 1, FR-100..199 for area 2, FR-200..299 for area 3, …). New FRs added later go into their area's free numbers, not the global tail — IDs stay stable.
+
+### 3.1 [Feature area]
+
+#### FR-{NNN}: {Title}
+- **Description:** [What the system must do.]
+- **Actor:** [Role that triggers or benefits from this requirement.]
+- **Input:** [What data or event initiates this.]
+- **Output / Result:** [What the system produces or changes.]
+- **Business Rules:** [Formulas, limits, conditions.]
+- **Source:** [Which stakeholder, brief goal, regulatory requirement, or parent FR-NNN drove this requirement. Required for traceability.]
+- **Verification:** Test | Demo | Inspection | Analysis
+- **Rationale:** [Why this requirement exists. Not what — why. Helps future maintainers know what is safe to push back on.]
 - **Priority:** Must | Should | Could | Won't
 
 ## 4. Interface Requirements
@@ -76,9 +96,25 @@ Supplement with domain-specific questions and typical functional areas from the
 _(detailed in /nfr artifact)_
 
 ## 6. Priority Matrix (MoSCoW)
+
+| Priority | FR Count | FR IDs |
+|----------|----------|--------|
+| Must     | [n]      | …      |
+| Should   | [n]      | …      |
+| Could    | [n]      | …      |
+| Won't    | [n]      | …      |
+
+## 7. Traceability — Brief Goal → FR
+
+Forward traceability from the Project Brief's business goals to the FRs that satisfy them. Every Brief goal must have at least one linked FR; uncovered goals are flagged.
+
+| Goal ID | Goal Description (from 01_brief) | Linked FRs |
+|---------|----------------------------------|------------|
+| G1      | [goal from brief §2]             | FR-001, FR-007, FR-014 |
+| G2      | [goal from brief §2]             | FR-003 |
 ```
 
-FR numbering: sequential, three-digit (FR-001, FR-002, ...).
+FR numbering: sequential within each feature area, three-digit, with reserved ranges per area (FR-001..099 for area 1, FR-100..199 for area 2, …). New FRs inserted later use the next free number in their area's range, not the global tail — IDs stay stable.
 
 ## AGENTS.md update
 

package/skills/stories/SKILL.md

@@ -40,27 +40,26 @@ Supplement with domain-specific questions and typical epics from the reference.
 
 **File:** `03_stories_{slug}.md`
 
-```markdown
-# User Stories: {Name}
-
-## Epic: {Epic Name}
-Brief description and business value.
-
-### US-{NNN}: {Short Description}
-- **Role:** {role from SRS}
-- **Action:** {what they want to do}
-- **Value:** {why, business outcome}
-- **Priority:** {Must | Should | Could | Won't}
-- **Linked FR:** FR-{NNN}
-- **Acceptance Criteria:** _(filled at /ac stage)_
-- **Notes:** {edge cases, additional context}
-```
+The full template lives at `references/templates/stories-template.md` and is the single source of truth for the per-story field set. The fields are:
+
+- **Persona** — named persona with role and one-line context (e.g. "Maria, ops supervisor at a 50-warehouse 3PL handling 200 returns/week"). Personas, not bare job titles.
+- **Action** — the atomic capability the persona wants.
+- **Value** — the business outcome the persona gets.
+- **Business Value Score** — 1–5 (or High / Med / Low). Captures relative ranking *within* the same MoSCoW priority tier so PMs can sequence inside a tier.
+- **Priority** — MoSCoW (Must | Should | Could | Won't).
+- **Size** — XS | S | M | L | XL.
+- **Linked FR** — FR-NNN (cross-reference to `02_srs_{slug}.md`).
+- **Depends on** — US-NNN list of stories that must complete before this one can start, or `—` if independent. Critical for sprint planning.
+- **Acceptance Criteria** — `→ 05_ac_{slug}.md → US-NNN` (detailed in `/ac`).
+- **Definition of Ready** — checklist or "see `00_principles_{slug}.md`".
+- **INVEST self-check** — one line confirming the story passes Independent / Negotiable / Valuable / Estimable / Small / Testable.
+- **Notes** — edge cases, out-of-scope clarifications.
 
 **Rules:**
 - Sequential numbering: US-001, US-002, ...
-- One story = one atomic action by one role.
+- One story = one atomic action by one persona.
 - All Must-priority FR from SRS must have at least one US.
-- Story covering > 3 scenarios — suggest `/split`.
+- **INVEST is the quality gate.** A story that fails any of the six INVEST criteria must be revised or split. `/split` should be used when a story violates **Small** or **Independent**, or when it matches one of Mike Cohn's nine story-splitting patterns (workflow steps, business-rule variations, happy / unhappy paths, data variations, simple-vs-complex, deferred performance, CRUD operations, input options, or break-out a spike).
 
 ## Iterative refinement
 
@@ -68,7 +67,7 @@ Brief description and business value.
 - `/expand [US-NNN]` — add detail.
 - `/split [US-NNN]` — split into smaller stories.
 - `/clarify [focus]` — targeted ambiguity pass.
-- `/validate` — all FR covered; no orphan stories; numbering correct; roles consistent.
+- `/validate` — all FR covered; no orphan stories; numbering correct; personas consistent; **every story passes the INVEST checklist** (Independent, Negotiable, Valuable, Estimable, Small, Testable).
 - `/done` — finalize. Next step: `/usecases`.
 
 ## Closing message