@kudusov.takhir/ba-toolkit 3.6.0 → 3.8.0

package/skills/sprint/SKILL.md

@@ -22,12 +22,13 @@ Examples:
 
 ## Context loading
 
-0. If `00_principles_*.md` exists, load it — apply language convention (section 1) and ID naming convention (section 2).
+0. If `00_principles_*.md` exists, load it — apply language convention (section 1), ID naming convention (section 2), and any team capacity defaults from section 8 (Project-Specific Notes).
 1. Load `00_estimate_{slug}.md` or check `03_stories_{slug}.md` for inline `**Estimate:**` fields. **Required** — sprint planning cannot proceed without estimates.
-2. Load `03_stories_{slug}.md` — source of story priority (MoSCoW or custom), epic grouping, and acceptance criteria count.
+2. Load `03_stories_{slug}.md` — source of story priority (MoSCoW or custom), persona, business value score, epic grouping, **Depends on** field (per v3.5.0+ template), and acceptance criteria count.
 3. Load `00_risks_{slug}.md` if it exists — use risk scores to elevate priority of stories that mitigate 🔴 Critical or 🟡 High risks.
-4. Load `02_srs_{slug}.md` — to extract any sequencing constraints (dependencies, technical prerequisites).
-5. Load `00_sprint_{slug}.md` if it exists — merge mode: preserve confirmed sprints, re-plan only future ones.
+4. Load `02_srs_{slug}.md` — to extract any sequencing constraints (dependencies, technical prerequisites) beyond the explicit `Depends on` fields in stories.
+5. Load `00_discovery_{slug}.md` if it exists — for early signals about which features matter most to MVP success.
+6. Load `00_sprint_{slug}.md` if it exists — merge mode: preserve confirmed sprints, re-plan only future ones.
 
 ## Environment
 
@@ -35,17 +36,33 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Calibration interview
 
-Ask the following before planning (skip questions already answered in context or via syntax flags):
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended**, render variants in the user's language (rule 11), and wait for an answer.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/sprint` (e.g., `/sprint 2-week sprints, 35 SP velocity, 70% focus factor`), parse it and skip the matching questions.
 
-1. **Sprint length:** How many weeks per sprint? _(default: 2 weeks)_
-2. **Team velocity:** Estimated Story Points per sprint (or T-shirt / person-days equivalent)? _(if not given, estimate from story count: assume 30–40 SP for a 3–5 developer team)_
-3. **Team size:** Number of developers contributing to this project? _(used to sanity-check velocity)_
-4. **Sprint 0:** Does the team need a sprint 0 for setup, architecture, or environment? _(yes/no — if yes, add SP-00 with no user stories)_
-5. **Hard deadline:** Is there a fixed release date or milestone? _(if yes, flag stories that will not fit before the deadline)_
-6. **Parallel tracks:** Are frontend and backend worked on simultaneously, or sequentially? _(affects story ordering within a sprint)_
+Ask the following before planning (skip questions already answered in context or via inline flags):
+
+1. **Sprint length:** How many weeks per sprint? **Recommended:** 2 weeks.
+2. **Theoretical velocity:** Maximum Story Points per sprint at 100% capacity (or T-shirt / person-days equivalent)? *(If not given, estimate from team size: assume 8–10 SP per developer per 2-week sprint at 100% capacity, before focus factor.)*
+3. **Team size:** Number of developers contributing to this project? *(Used to sanity-check velocity.)*
+4. **Focus factor** — what percentage of theoretical capacity is actually available for new feature work? **Recommended: 65%**. Industry baseline accounts for: meetings, code review, mentoring, context-switching. A team that runs at 100% theoretical velocity is a team that's burning out.
+5. **Buffer / slack** — what percentage of capacity is reserved for bugs, support, and unplanned work? **Recommended: 15%**. Without explicit slack the first production incident derails the whole sprint.
+6. **Ceremonies overhead** — planning + review + retro + refinement time per sprint? **Recommended: 1 day per 2-week sprint per developer.**
+7. **Holidays / PTO** — any planned absence during the sprint window that should reduce capacity?
+8. **Sprint 0:** Does the team need a sprint 0 for setup, architecture, or environment? *(Yes / no — if yes, add SP-00 with no user stories.)*
+9. **Hard deadline:** Is there a fixed release date or milestone? *(If yes, flag stories that will not fit before the deadline.)*
+10. **Parallel tracks:** Are frontend and backend worked on simultaneously, or sequentially? *(Affects story ordering within a sprint.)*
 
 If the user types `/sprint` without additional input and prior context is sufficient, apply defaults and state assumptions explicitly in the output.
 
+**Net velocity formula:**
+
+```
+Net velocity = Theoretical velocity × Focus factor × (1 − Buffer fraction) − Ceremonies cost
+```
+
+Example: 50 SP theoretical × 0.65 focus × (1 − 0.15) buffer − 5 SP ceremonies = **22.6 SP net velocity**. The skill assigns stories against **net velocity**, not theoretical. Senior scrum masters never schedule against the theoretical number — that's how teams overcommit and miss sprints.
+
 ## Planning algorithm
 
 ### Step 1 — Priority ordering
@@ -54,16 +71,17 @@ Sort stories for assignment using this precedence:
 
 1. **Must** stories first (MoSCoW: Must > Should > Could > Won't).
 2. Within the same priority tier, elevate stories that mitigate 🔴 Critical or 🟡 High risks (from `00_risks_{slug}.md`).
-3. Within the same priority and risk tier, order by dependencies: stories that are prerequisite to others go first.
-4. Within the same tier with no dependencies, order by estimate ascending (smaller stories first — reduces WIP).
+3. Within the same priority and risk tier, sort by **Business Value Score** (per v3.5.0+ stories template) — higher value first.
+4. Within the same priority, risk, and value tier, order by dependencies: stories that are prerequisite to others go first. **Read the `Depends on` field per v3.5.0+ stories template** for explicit story-to-story dependencies, plus any sequencing constraints from `02_srs_*.md`.
+5. Within the same tier with no dependencies, order by estimate ascending (smaller stories first — reduces WIP).
 
 ### Step 2 — Sprint assignment
 
-Fill sprints greedily from the ordered list:
+Fill sprints greedily from the ordered list against **net velocity** (not theoretical):
 
-- Assign stories to the current sprint until adding the next story would exceed velocity.
-- If a story alone exceeds velocity, flag it for splitting: `⚠️ US-NNN (N SP) exceeds sprint capacity — consider /split US-NNN`.
-- If a story has an explicit prerequisite not yet assigned, defer it to the sprint after its prerequisite completes.
+- Assign stories to the current sprint until adding the next story would exceed net velocity.
+- If a story alone exceeds net velocity, flag it for splitting: `⚠️ US-NNN (N SP) exceeds sprint capacity — consider /split US-NNN`.
+- If a story has an explicit `Depends on` not yet assigned, defer it to the sprint after its prerequisite completes.
 - When a hard deadline is provided, mark the sprint that contains it and flag any Must stories not scheduled before it as 🚨 **At risk**.
 
 ### Step 3 — Sprint goal derivation
@@ -74,78 +92,7 @@ For each sprint, derive a one-sentence goal that describes the primary user-faci
 
 ## Generation
 
-Save `00_sprint_{slug}.md` to the output directory.
-
-```markdown
-# Sprint Plan: {PROJECT_NAME}
-
-**Domain:** {DOMAIN}
-**Date:** {DATE}
-**Slug:** {SLUG}
-**Sprint length:** {N} weeks
-**Team velocity:** {N} SP per sprint
-**Sources:** {list of artifacts used}
-
----
-
-## Summary
-
-| Sprint | Goal | Stories | Points | Capacity |
-|--------|------|:-------:|:------:|:--------:|
-| SP-00  | Setup and environment | — | — | — |
-| SP-01  | [Goal] | N | N SP | N% |
-| SP-02  | [Goal] | N | N SP | N% |
-| **Total** | | **N** | **N SP** | |
-
-**Planned:** N stories / N SP across N sprints
-**Unplanned backlog:** N stories / N SP (scope exceeds capacity or marked Won't)
-
----
-
-## Sprint Details
-
-### SP-01 — [Sprint Goal]
-
-**Duration:** Week 1–2
-**Capacity:** {N} SP
-
-| US | Title | Epic | Priority | Risk | Estimate |
-|----|-------|------|---------|------|---------|
-| US-001 | [Title] | E-01 | Must | RISK-02 ↑ | 5 SP |
-| US-002 | [Title] | E-01 | Must | — | 3 SP |
-| US-005 | [Title] | E-02 | Should | — | 8 SP |
-
-**Sprint total:** N SP / {velocity} SP capacity (N%)
-
-**Definition of Done for this sprint:**
-- [ ] All stories pass their Acceptance Criteria.
-- [ ] API endpoints for this sprint are integrated and tested.
-- [ ] No 🔴 Critical open items in `/analyze` for completed stories.
-
----
-
-### SP-02 — [Sprint Goal]
-
-...
-
----
-
-## Unplanned Backlog
-
-Stories not assigned to any sprint (capacity exceeded, low priority, or deferred):
-
-| US | Title | Epic | Priority | Estimate | Reason |
-|----|-------|------|---------|---------|--------|
-| US-018 | [Title] | E-04 | Could | 3 SP | Capacity exceeded |
-| US-022 | [Title] | E-05 | Won't | 8 SP | Out of MVP scope |
-
----
-
-## Assumptions
-
-- Sprint velocity: {N} SP based on {source: user input / estimate from team size}.
-- {Any other assumption made during planning.}
-```
+Save `00_sprint_{slug}.md` to the output directory. The full layout lives at `references/templates/sprint-template.md` and is the single source of truth — including the per-story Persona column (per v3.5.0+ stories template), the net-velocity header, and the sprint-level Definition of Done.
 
 Sprint IDs are sequential (SP-00, SP-01, SP-02, …). SP-00 is reserved for setup/architecture sprint if requested.
 

package/skills/trace/SKILL.md

@@ -10,57 +10,40 @@ Cross-cutting command of the BA Toolkit pipeline. Available after `/stories` is
 
 ## Context loading
 
-0. If `00_principles_*.md` exists in the output directory, load it. Use its traceability requirements (section 3) to determine which links are CRITICAL, HIGH, or MEDIUM severity when flagging gaps.
-1. Read all pipeline artifacts from the output directory. Minimum required: `02_srs_*.md` and `03_stories_*.md`.
-2. Determine which artifacts are available and adapt matrix columns accordingly.
+0. If `00_principles_*.md` exists in the output directory, load it. Use its traceability requirements (section 3) to determine which links are CRITICAL, HIGH, or MEDIUM severity when flagging gaps. The principles file is the source of truth for severity thresholds — `/trace` does not invent its own.
+1. Read all pipeline artifacts from the output directory. Minimum required: `02_srs_*.md` and `03_stories_*.md`. Auto-consume any of: `00_discovery_*.md`, `00_principles_*.md`, `04_usecases_*.md`, `05_ac_*.md`, `06_nfr_*.md`, `07_datadict_*.md`, `07a_research_*.md`, `08_apicontract_*.md`, `09_wireframes_*.md`, `10_scenarios_*.md`, `11_handoff_*.md`, `12_implplan_*.md`.
+2. Determine which artifacts are available and adapt matrix columns accordingly. The implementation plan (`12_implplan_*.md`) introduces a new traceability column: FR → Task (T-NN-NNN), so the chain is now `FR → US → UC → AC → NFR → Entity → ADR → API → WF → SC → Task`.
 3. Domain reference not needed for this skill — all information comes from the artifacts.
 
 ## Environment
 
 Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory for the current platform. If the file is unavailable, apply the default rule: if `/mnt/user-data/outputs/` exists and is writable, save there (Claude.ai); otherwise save to the current working directory.
 
-## Generation
-
-No interview needed. Information is extracted from existing artifacts automatically.
-
-**File:** `00_trace_{slug}.md`
-
-```markdown
-# Traceability Matrix: {Name}
+## Calibration interview
 
-**Date:** {date}
-**Artifacts:** {list of found pipeline files}
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended**, render variants in the user's language (rule 11), and wait for an answer.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/trace` (e.g., `/trace forward only, focus on FR→US`), parse it as the focus hint and skip the matching questions.
 
-## Matrix
+If the user invokes `/trace` with no inline hint, ask the following short calibration interview (skip any question already answered by inline context or by `00_principles_*.md`):
 
-| FR | US | UC | AC | NFR | Data Entity | API Endpoint | Wireframe |
-|----|----|----|----|----|-------------|-------------|-----------|
-| FR-001 | US-001, US-002 | UC-001 | AC-001-01 | NFR-003 | User, Bet | POST /bets | WF-005 |
+1. **Direction** — forward (FR → downstream), reverse (downstream → FR), or bidirectional (both)? **Recommended:** bidirectional, because senior BA practice always produces both directions.
+2. **Scope** — full pipeline, or focus on a specific artifact pair (e.g., FR → API only)?
+3. **Severity-thresholds source** — use the thresholds from `00_principles_*.md` §3 if it exists, or apply the defaults (Must FR with no US = CRITICAL, Should FR with no US = HIGH, Could FR with no US = MEDIUM, Won't FR uncovered = LOW)?
 
-## Coverage Statistics
-
-| Artifact | Total | Covered | Uncovered | Coverage % |
-|----------|-------|---------|-----------|------------|
-
-## Uncovered Elements
+## Generation
 
-### FR without linked US
-### US without linked UC
-### US without AC
-### FR without NFR coverage
-### Data entities without FR/US link
-### API endpoints without FR/US link
-### Wireframes without US link
+**File:** `00_trace_{slug}.md`
 
-## Recommendations
-Specific actions to close coverage gaps.
-```
+The full per-axis matrix layout lives at `references/templates/trace-template.md` and is the single source of truth. The artifact carries: a Forward Traceability matrix (FR → all downstream artifacts), a Reverse Traceability matrix (US, UC, AC, NFR, Entity, API, WF, SC, Task → FR), Coverage Gaps grouped by severity (Critical / High / Medium / Low per the principles thresholds), Coverage Statistics per artifact pair, and Recommended Actions sorted by severity.
 
 **Rules:**
 - Columns include only artifact types that have been created. Missing columns marked with `—`.
-- Links extracted from "Linked FR/US" fields in each artifact.
-- Inconsistency (link present in one artifact but missing in another) is flagged.
-- Coverage: an element is covered if it has at least one link in the next matrix column.
+- **Both forward and reverse traceability are produced by default.** Forward catches "what does this requirement become?", reverse catches "why does this artifact exist?" — a senior BA needs both directions to validate provenance.
+- Links extracted from `Linked FR`, `Source`, and `Linked US` fields in each artifact (per the v3.5.0+ provenance template fields).
+- Inconsistency (link present in one artifact but missing in another) is flagged as a separate finding.
+- **Severity is read from `00_principles_*.md` §3** if present; otherwise default thresholds apply (Must = CRITICAL on uncovered, Should = HIGH, Could = MEDIUM, Won't = LOW).
+- Coverage: an element is covered if it has at least one link in the relevant downstream column. Orphaned elements in any direction are flagged at their stated severity.
 
 ## Iterative refinement