@sandrinio/vbounce 1.4.0 → 1.5.0

package/skills/improve/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: improve
+description: "Use when the V-Bounce OS framework needs to evolve based on accumulated agent feedback. Activates after sprint retros, when recurring friction patterns emerge, or when the user explicitly asks to improve the framework. Reads Process Feedback from sprint reports, identifies patterns, proposes specific changes to templates, skills, brain files, scripts, and agent configs, and applies approved changes. This is the system's self-improvement loop."
+---
+
+# Framework Self-Improvement
+
+## Purpose
+
+V-Bounce OS is not static. Every sprint generates friction signals from agents who work within the framework daily. This skill closes the feedback loop: it reads what agents struggled with, identifies patterns, and proposes targeted improvements to the framework itself.
+
+**Core principle:** No framework change happens without human approval. The system suggests — the human decides.
+
+## When to Use
+
+- After every 2-3 sprints (recommended cadence)
+- When the same Process Feedback appears across multiple sprint reports
+- When the user explicitly asks to improve templates, skills, or process
+- When a sprint's Framework Self-Assessment reveals Blocker-severity findings
+- When LESSONS.md contains 3+ entries pointing to the same process gap
+
+## Trigger
+
+`/improve` OR when the Team Lead identifies recurring framework friction during Sprint Consolidation.
+
+## Announcement
+
+When using this skill, state: "Using improve skill to evaluate and propose framework changes."
+
+## Input Sources
+
+The improve skill reads from multiple signals, in priority order:
+
+### 1. Sprint Report §5 — Framework Self-Assessment (Primary)
+The structured retro tables are the richest source. Each row has:
+- Finding (what went wrong)
+- Source Agent (who experienced it)
+- Severity (Friction vs Blocker)
+- Suggested Fix (agent's proposal)
+
+### 2. LESSONS.md — Recurring Patterns
+Lessons that point to *process* problems rather than *code* problems:
+- "Always check X before Y" → the template should enforce this ordering
+- "Agent kept missing Z" → the handoff report is missing a field
+- Lessons that keep getting re-flagged sprint after sprint
+
+### 3. Sprint Execution Metrics
+Quantitative signals from Sprint Report §3:
+- High bounce ratios → story templates may need better acceptance criteria guidance
+- High correction tax → handoffs may be losing critical context
+- Escalation patterns → complexity labels may need recalibration
+
+### 4. Agent Process Feedback (Raw)
+If sprint reports aren't available, read individual agent reports from `.bounce/archive/` and extract `## Process Feedback` sections directly.
+
+## The Improvement Process
+
+### Step 1: Gather Signals
+```
+1. Read the last 2-3 Sprint Reports (§5 Framework Self-Assessment)
+2. Read LESSONS.md — filter for process-related entries
+3. Read Sprint Execution Metrics — flag anomalies
+4. If no sprint reports exist yet, read raw agent reports from .bounce/archive/
+```
+
+### Step 2: Pattern Detection
+Group findings by framework area:
+
+| Area | What to Look For | Files Affected |
+|------|-----------------|----------------|
+| **Templates** | Missing fields, unused sections, ambiguous instructions | `templates/*.md` |
+| **Agent Handoffs** | Missing report fields, redundant data, unclear formats | `brains/claude-agents/*.md` |
+| **RAG Pipeline** | Irrelevant results, missing context, stale embeddings | `scripts/vbounce_index.mjs`, `scripts/vbounce_ask.mjs`, `scripts/pre_bounce_sync.sh` |
+| **Skills** | Unclear instructions, missing steps, outdated references | `skills/*/SKILL.md`, `skills/*/references/*` |
+| **Process Flow** | Unnecessary steps, wrong ordering, missing gates | `skills/agent-team/SKILL.md`, `skills/doc-manager/SKILL.md` |
+| **Tooling** | Script failures, validation gaps, missing automation | `scripts/*`, `bin/*` |
+| **Brain Files** | Stale rules, missing rules, inconsistencies across brains | `brains/CLAUDE.md`, `brains/GEMINI.md`, `brains/AGENTS.md`, `brains/cursor-rules/*.mdc` |
+
+Deduplicate: if 3 agents report the same issue, that's 1 finding with 3 votes — not 3 findings.
+
+### Step 3: Prioritize
+Rank findings by impact:
+
+1. **Blockers reported by 2+ agents** — fix immediately
+2. **Friction reported by 2+ agents** — fix in this improvement pass
+3. **Blockers reported once** — fix if the root cause is clear
+4. **Friction reported once** — note for next improvement pass (may be a one-off)
+
+### Step 4: Propose Changes
+For each finding, write a concrete proposal:
+
+```markdown
+### Proposal {N}: {Short title}
+
+**Finding:** {What went wrong — from the retro}
+**Pattern:** {How many times / sprints this appeared}
+**Root Cause:** {Why the framework allowed this to happen}
+**Affected Files:**
+- `{file_path}` — {what changes}
+
+**Proposed Change:**
+{Describe the specific edit. Include before/after for template changes.
+For skill changes, describe the new instruction or step.
+For script changes, describe the new behavior.}
+
+**Risk:** {Low / Medium — what could break if this change is wrong}
+**Reversibility:** {Easy — revert the edit / Medium — downstream docs may need updating}
+```
+
+### Step 5: Present to Human
+Present ALL proposals as a numbered list. The human can:
+- **Approve** — apply the change
+- **Reject** — skip it (optionally explain why)
+- **Modify** — adjust the proposal before applying
+- **Defer** — save for the next improvement pass
+
+**Never apply changes without explicit approval.** The human owns the framework.
+
+### Step 6: Apply Approved Changes
+For each approved proposal:
+1. Edit the affected file(s)
+2. If brain files are affected, ensure ALL brain surfaces stay in sync (CLAUDE.md, GEMINI.md, AGENTS.md, cursor-rules/)
+3. Log the change in `brains/CHANGELOG.md`
+4. If skills were modified, update skill descriptions in all brain files that reference them
+
+### Step 7: Validate
+After all changes are applied:
+1. Run `./scripts/pre_bounce_sync.sh` to update RAG embeddings with the new framework content
+2. Verify no cross-references are broken (template paths, skill names, report field names)
+3. Confirm brain file consistency — all 4 surfaces should describe the same process
+
+## Improvement Scope
+
+### What CAN Be Improved
+
+| Target | Examples |
+|--------|---------|
+| **Templates** | Add/remove/rename sections, improve instructions, add examples, fix ambiguity |
+| **Agent Report Formats** | Add/remove YAML fields, add report sections, improve handoff clarity |
+| **Skills** | Update instructions, add/remove steps, improve reference docs, add new skills |
+| **Brain Files** | Update rules, add missing rules, improve consistency, update skill references |
+| **Scripts** | Fix bugs, add validation checks, improve error messages, add new automation |
+| **Process Flow** | Reorder steps, add/remove gates, adjust thresholds (bounce limits, complexity labels) |
+| **RAG Pipeline** | Adjust indexing scope, improve chunking, add new document types to index |
+
+### What CANNOT Be Changed Without Escalation
+- **Adding a new agent role** — requires human design decision + new brain config
+- **Changing the V-Bounce state machine** — core process change, needs explicit human approval beyond normal improvement flow
+- **Removing a gate** (QA, Architect) — safety-critical, must be a deliberate human decision
+- **Changing git branching strategy** — affects all developers and CI/CD
+
+## Output
+
+The improve skill does not produce a standalone report file. Its output is:
+1. The list of proposals presented to the human (inline during the conversation)
+2. The applied changes to framework files
+3. The `brains/CHANGELOG.md` entries documenting what changed and why
+
+## Tracking Improvement Velocity
+
+Over time, the Sprint Report §5 Framework Self-Assessment tables should shrink. If the same findings keep appearing after improvement passes, the fix didn't work — re-examine the root cause.
+
+The Team Lead should note in the Sprint Report whether the previous improvement pass resolved the issues it targeted:
+- "Improvement pass from S-03 resolved the Dev→QA handoff gap (0 handoff complaints this sprint)"
+- "Improvement pass from S-03 did NOT resolve RAG relevance — same feedback from Developer"
+
+## Critical Rules
+
+- **Never change the framework without human approval.** Propose, don't impose.
+- **Keep all brain surfaces in sync.** A change to CLAUDE.md must be reflected in GEMINI.md, AGENTS.md, and cursor-rules/.
+- **Log everything.** Every change goes in `brains/CHANGELOG.md` with the finding that motivated it.
+- **Run pre_bounce_sync.sh after changes.** Updated skills and rules must be re-indexed for RAG.
+- **Don't over-engineer.** Fix the actual problem reported by agents. Don't add speculative improvements.
+- **Respect the hierarchy.** Template changes are low-risk. Process flow changes are high-risk. Scope accordingly.
+- **Skills are living documents.** If a skill's instructions consistently confuse agents, rewrite the confusing section — don't add workarounds elsewhere.
+
+## Keywords
+
+improve, self-improvement, framework evolution, retro, retrospective, process feedback, friction, template improvement, skill improvement, brain sync, meta-process, self-aware

package/templates/charter.md

@@ -16,7 +16,7 @@ Ambiguity Score:
 - 🟡 Medium: Tech TBD but logic clear → Ready for Roadmap
 - 🟢 Low: All filled → Ready for Epics
 
-Output location: `product_plans/{project}_charter.md`
+Output location: `product_plans/strategy/{project}_charter.md`
 
 Document Hierarchy Position: ROOT
 Charter is the source of truth for WHY. All downstream documents inherit from it:

package/templates/delivery_plan.md

@@ -1,197 +1,44 @@
 <instructions>
-FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
-
-1. **YAML Frontmatter**: Set status, last updated, roadmap ref, risk registry ref, delivery ref, and sprint cadence
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+1. **Header**: Set Status, link to Roadmap + Risk Registry, Sprint Cadence
 2. **§1 Project Window**: Start/End dates, total sprints, team
-3. **§2 Sprint Registry**: Table of ALL sprints with goals and status (auto-populated between markers)
-4. **§3 Active Sprint**: CURRENT sprint only — goal + assigned stories with L1-L4 labels + V-Bounce state
-5. **§4 Backlog**: Prioritized stories not yet assigned to a sprint (includes Escalated + Parking Lot)
-6. **§5 Context Pack Status**: Per-story readiness checklist (ONLY for Active Sprint stories)
-6b. **§5b Open Questions**: Operational questions that may block active sprint stories
-7. **§6 Completed Sprints**: ONE-LINE summaries of finished sprints (full detail in version history)
-8. **§7 Change Log**: Auto-appended on updates
-9. **§8 Applied Hotfixes**: Ledger of L1 Trivial fixes that bypassed Epic/Story hierarchy (auto-appended by `hotfix_manager.sh ledger`)
-
-Sprint Lifecycle:
-- When a sprint completes: update Sprint Registry row to "Completed",
-  REPLACE §3 Active Sprint with the next sprint's stories,
-  move old sprint summary to §6 Completed Sprints (one row, not full detail).
-- Full historical detail is preserved in vp_document_versions (auto-snapshots on every update).
-
-Sprint States: Planning → Active → Completed → Cancelled
-
-Story Labels (complexity_label):
-- L1: Trivial (single file, <1hr vibe time)
-- L2: Standard (2-3 files, known pattern) — DEFAULT
-- L3: Complex (cross-cutting, spike may be needed)
-- L4: Uncertain (requires Probing/Spiking before Bounce)
-
-V-Bounce States (11 total):
-Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architect Passed → Sprint Review → Done
-  ↳ Refinement → Probing/Spiking → Refinement (spike loop)
-  ↳ Any → Parking Lot (deferred)
-  ↳ Bouncing → Escalated (3+ failures)
-
-IMPORTANT: The §2 Sprint Registry is auto-populated by SyncEngine.
-Rows between <!-- SPRINT_REGISTRY_START --> and <!-- SPRINT_REGISTRY_END -->
-markers MUST be on their own lines (not inside table pipes).
-
-Output location: `product_plans/{delivery}/DELIVERY_PLAN.md`
-(Lives at the root of its delivery folder. One Delivery Plan per delivery/release.)
-
-Document Hierarchy Position: LEVEL 5 — EXECUTION
-Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → **Delivery Plan** (execution) → Risk Registry (risks)
+3. **§2 Epics Included**: Table of all Epics assigned to this delivery
+4. **§3 High-Level Backlog**: Unassigned stories (Epics being broken down)
 
-This is the OPERATIONAL layer. It does NOT define what to build (that's Roadmap + Epic).
-It defines WHEN and in WHAT ORDER stories execute within sprints.
-
-Upstream sources:
-- Stories come from Epics (via Epic §9 Artifact Links)
-- Sprint goals align with Roadmap §2 Release Plan milestones
-- Story complexity labels (L1-L4) are defined in the Story template
-
-Downstream consumers:
-- Team Lead Agent reads this to initialize the Bounce (via agent-team skill)
-- §5 Context Pack Status gates whether a story is Ready to Bounce
-- Sprint Reports are generated from Active Sprint data + agent reports
-- Risk Registry §2 Risk Analysis Log references sprint transitions
+Delivery Lifecycle:
+- This document tracks the *milestone* across multiple sprints.
+- Active sprint work happens inside `sprints/sprint-{XX}/sprint-{XX}.md`, not here.
+- When the delivery is fully shipped, this entire document is archived.
 
+Output location: `product_plans/strategy/{delivery}_delivery_plan.md`
 Do NOT output these instructions.
 </instructions>
-
+# Delivery Plan: {Project Name}
 ---
-last_updated: "{YYYY-MM-DD}"
-status: "Planning / In Sprint / Delivered"
-roadmap_ref: "product_plans/{project}_roadmap.md"
-risk_registry_ref: "product_plans/RISK_REGISTRY.md"
-delivery_ref: "D-{NN}_{release_name}"
-sprint_cadence: "1-week sprints within 2-week project window"
+> **Last Updated**: {YYYY-MM-DD}
+> **Status**: Planning / In Delivery / Completed
+> **Roadmap**: `product_plans/{project}_roadmap.md`
+> **Risk Registry**: `product_plans/RISK_REGISTRY.md`
+> **Delivery**: `D-{NN}_{release_name}`
+> **Sprint Cadence**: 1-week sprints
 ---
-
-# Delivery Plan: {Project Name}
-
 ## 1. Project Window
-
 | Key | Value |
 |-----|-------|
 | **Start Date** | {YYYY-MM-DD} |
 | **End Date** | {YYYY-MM-DD} |
 | **Total Sprints** | {N} |
-| **Sprint Length** | 1 week |
-| **Project Window** | 2 weeks |
 | **Team** | {CE name(s) / Agent config} |
-
----
-
-## 2. Sprint Registry
-
-<!--
-AUTO-POPULATED SECTION
-Updated when sprints are created or completed.
-DO NOT manually edit the table rows - they are managed by the system.
--->
-
-| Sprint | Dates | Sprint Goal | Status | Stories | Completed |
-|--------|-------|-------------|--------|---------|-----------|
-<!-- SPRINT_REGISTRY_START -->
-| S-01 | {MM/DD - MM/DD} | {One-sentence North Star} | Planning / Active / Completed | {X} | {Y}/{X} |
-<!-- SPRINT_REGISTRY_END -->
-
 ---
-
-## 3. Active Sprint
-
-### Sprint Goal
-> {One-sentence functional "North Star" — what is shippable at the end of this sprint?}
-
-### Assigned Stories
-
-| # | Story | Epic | Label | V-Bounce State | Context Pack |
-|---|-------|------|-------|----------------|--------------|
-| 1 | STORY-XXX-YY: {name} | EPIC-XXX | L1/L2/L3/L4 | Draft / Refinement / Ready to Bounce / Bouncing | Locked / Open |
-
-### Sprint Notes
-- {Blockers, dependencies, decisions made during the sprint}
-
----
-
-## 4. Backlog
-
-> Prioritized stories not yet assigned to a sprint.
-
-| Priority | Story | Epic | Label | V-Bounce State | Blocker |
-|----------|-------|------|-------|----------------|---------|
-| 1 | STORY-XXX-YY: {name} | EPIC-XXX | L2 | Draft | — |
-
-### Escalated
-> Stories with 3+ bounce failures requiring PM/BA intervention.
-
-| Story | Epic | Bounce Count | Escalation Reason |
-|-------|------|--------------|-------------------|
-| — | — | — | No escalated stories |
-
-### Parking Lot
-> Stories moved out of current project window scope (V-Bounce state: Parking Lot).
-
-- STORY-XXX-YY: {name} — Reason: {why deferred}
-
----
-
-## 5. Context Pack Status
-
-> Tracks readiness of ACTIVE SPRINT stories only.
-> A story is **Ready to Bounce** only when all items are checked.
-> Context Packs for future sprints are tracked when they enter the Active Sprint.
-> L4 stories MUST pass through Probing/Spiking before reaching Ready to Bounce.
-
-### {STORY-XXX-YY}: {name} (Label: {L1/L2/L3/L4})
-- [ ] Story spec complete (§1 The Spec)
-- [ ] Acceptance criteria written (§2 The Truth)
-- [ ] Implementation guide filled (§3 Implementation Guide)
-- [ ] Ambiguity: Low
-- [ ] BA sign-off
-- [ ] Architect sign-off
-- [ ] Spike completed (L4 only — skip for L1-L3)
-- **V-Bounce State**: {current state} → Ready to Bounce
-
----
-
-## 5b. Open Questions
-
-> Operational questions that may block stories in the active sprint.
-> Strategic questions belong in the Roadmap §6.
-> The Team Lead MUST check this section before starting a sprint — do NOT bounce stories with unresolved blocking questions.
-
-| Question | Affects Story | Impact | Owner | Status |
-|----------|--------------|--------|-------|--------|
-| {e.g., "Which date format for the API?"} | STORY-001-02 | Blocks implementation | {name} | Open / Resolved |
-
----
-
-## 6. Completed Sprints
-
-> One-line summaries only. Full detail preserved in document version history.
-
-| Sprint | Goal | Delivered | Notes |
-|--------|------|-----------|-------|
-| — | — | — | No sprints completed yet |
-
----
-
-## 7. Change Log
-
-<!-- Auto-appended when Delivery Plan is updated -->
-
-| Date | Change | By |
-|------|--------|-----|
-| {YYYY-MM-DD} | Initial creation from Roadmap | Architect |
-
----
-
-## 8. Applied Hotfixes
-
-> L1 Trivial fixes that bypassed the Epic/Story hierarchy. Auto-appended by `hotfix_manager.sh ledger`.
-
-| Date | Title | Brief Description |
-|------|-------|-------------------|
-| — | — | No hotfixes applied yet |
+## 2. Epics Included
+| Epic | Name | Status | Stories | V-Bounce Phase |
+|------|------|--------|---------|----------------|
+| EPIC-XXX | {Name} | Draft / Refinement / Bouncing / Done | {Y}/{X} | {Phase Name} |
+---
+## 3. High-Level Backlog
+> Stories prioritized for this delivery but not yet assigned to an active Sprint.
+| Priority | Story | Epic | Label | Blocker |
+|----------|-------|------|-------|---------|
+| 1 | STORY-XXX-YY: {name} | EPIC-XXX | L2 | — |
+### Escalated / Parking Lot
+- STORY-XXX-YY: {name} — Reason: {escalated / deferred}

package/templates/epic.md

@@ -17,7 +17,7 @@ Ambiguity Score:
 - 🟡 Medium: Scope clear, tech TBD → Ready for decomposition
 - 🟢 Low: All filled → Ready for Stories
 
-Output location: `product_plans/{delivery}/EPIC-{NNN}_{epic_name}/EPIC-{NNN}.md`
+Output location: `product_plans/backlog/EPIC-{NNN}_{epic_name}/EPIC-{NNN}_{epic_name}.md`
 
 Document Hierarchy Position: LEVEL 3 (Charter → Roadmap → **Epic** → Story)
 
@@ -188,9 +188,11 @@ Feature: {Epic Name}
 ## 9. Artifact Links
 > Auto-populated as Epic is decomposed.
 
-**Stories:**
-- [ ] STORY-{ID}-01: {name}
-- [ ] STORY-{ID}-02: {name}
+**Stories (Status Tracking):**
+> Keep track of where stories live contextually.
+- [ ] STORY-{ID}-01-{story_name} -> Backlog
+- [ ] STORY-{ID}-02-{story_name} -> Active (Sprint XX)
+- [x] STORY-{ID}-03-{story_name} -> Archived (Sprint YY)
 
 **References:**
 - Charter: [PROJECT CHARTER](link)

package/templates/risk_registry.md

@@ -13,7 +13,7 @@ Risk Levels:
 
 Risk Statuses: Open → Mitigating → Mitigated → Closed / Accepted
 
-Output location: `product_plans/RISK_REGISTRY.md`
+Output location: `product_plans/strategy/RISK_REGISTRY.md`
 
 Document Hierarchy Position: LEVEL 6 — CROSS-CUTTING
 Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → **Risk Registry** (risks)
@@ -43,7 +43,7 @@ roadmap_ref: "product_plans/{project}_roadmap.md"
 
 | ID | Risk | Phase | Source | Likelihood | Impact | Mitigation | Owner | Status |
 |----|------|-------|--------|------------|--------|------------|-------|--------|
-| R-001 | {Risk description} | {Verification/Bounce/Review} | {EPIC-XXX or STORY-XXX-YY} | Low/Medium/High | Low/Medium/High/Critical | {Mitigation strategy} | {Owner} | Open |
+| R-001 | {Risk description} | {Verification/Bounce/Review} | {EPIC-XXX or STORY-XXX-YY-{story_name}} | Low/Medium/High | Low/Medium/High/Critical | {Mitigation strategy} | {Owner} | Open |
 
 **Summary**: {X} Active | {Y} Mitigating | {Z} Accepted
 

package/templates/roadmap.md

@@ -11,7 +11,7 @@ FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
 8. **§7 Delivery Log**: Release notes for completed deliveries (appended by Team Lead on delivery archive)
 9. **§8 Change Log**: Auto-appended on updates
 
-Output location: `product_plans/{project}_roadmap.md`
+Output location: `product_plans/strategy/{project}_roadmap.md`
 
 Role of this document:
 - This is the STRATEGIC layer between Charter (why) and Delivery Plan (operational execution).

package/templates/sprint.md

@@ -0,0 +1,48 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-2.
+
+1. **YAML Frontmatter**: Sprint ID, Goal, Dates, Status
+2. **§1 Active Scope**: Table of stories pulled into this sprint. The V-Bounce state tracks its progression.
+3. **§2 Sprint Open Questions**: Unresolved items blocking this active execution window.
+
+Output location: `product_plans/sprints/sprint-{XX}/sprint-{XX}.md`
+
+Role of this document:
+- This is the Tactical view of the active sprint execution.
+- It tracks ONLY the stories claimed for this 1-week window.
+- The Team Lead agent reads this to know what is in scope.
+
+Document Lifecycle:
+- Created by the Team Lead or PM during Sprint Setup.
+- Selected stories are physically moved from `product_plans/backlog/EPIC-*/` to `product_plans/sprints/sprint-{XX}/`.
+- When the sprint completes, this document (and the entire sprint folder) moves to `product_plans/archive/sprints/sprint-{XX}/`.
+
+Do NOT output these instructions.
+</instructions>
+
+---
+sprint_id: "sprint-{XX}"
+sprint_goal: "{One-sentence North Star}"
+dates: "{MM/DD - MM/DD}"
+status: "Planning / Active / Completed"
+---
+
+# Sprint S-{XX} Plan
+
+## 1. Active Scope
+> Stories pulled from the backlog for execution during this sprint window.
+> The V-Bounce State tracks the live status of the story (Draft -> Ready to Bounce -> Bouncing -> QA Passed -> Architect Passed -> Sprint Review -> Done).
+
+| Priority | Story | Epic | Label | V-Bounce State | Blocker |
+|----------|-------|------|-------|----------------|---------|
+| 1 | [STORY-XXX-YY: name](./STORY-XXX-YY-name.md) | EPIC-XXX | L2 | Draft | — |
+
+### Escalated / Parking Lot
+- STORY-XXX-YY: {name} — Reason: {escalated / deferred}
+
+## 2. Sprint Open Questions
+> Unresolved items that affect this specific 1-week execution window.
+
+| Question | Options | Impact | Owner | Status |
+|----------|---------|--------|-------|--------|
+| {question} | A: {x}, B: {y} | Blocks {stories} | {name} | Open / Decided |

package/templates/sprint_report.md

@@ -25,6 +25,7 @@ sprint_id: "S-{XX}"
 sprint_goal: "{One-sentence North Star}"
 dates: "{MM/DD - MM/DD}"
 status: "Achieved / Partially Achieved / Failed"
+total_tokens_used: {N}
 delivery_ref: "D-{NN}_{release_name}"
 delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 ---
@@ -50,12 +51,12 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 ### Not Completed
 > Stories that were planned but didn't make it (escalated, deferred, or partially done).
 
-- {e.g., "STORY-001-03: Email notifications — Escalated (template integration failed 3x)"}
+- {e.g., "STORY-001-03-email_notifications — Escalated (template integration failed 3x)"}
 
 ### Product Docs Affected
 > Any product documentation files modified, created, or identified for updates. Handed off to Scribe agent.
 
-- {e.g., "product_documentation/api_reference.md — Added rate limiting details"}
+- {e.g., "vdocs/api_reference.md — Added rate limiting details"}
 
 ---
 
@@ -63,13 +64,13 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 
 | Story | Epic | Label | Final State | Bounces (QA) | Bounces (Arch) | Correction Tax |
 |-------|------|-------|-------------|--------------|----------------|----------------|
-| STORY-{ID}: {name} | EPIC-{ID} | L{N} | Done / Escalated / Parking Lot | {N} | {N} | {X}% |
+| STORY-{ID}-{story_name} | EPIC-{ID} | L{N} | Done / Escalated / Parking Lot | {N} | {N} | {X}% |
 
 ### Story Highlights
-- **{STORY-ID}**: {1-sentence summary of what was built and any notable decisions}
+- **STORY-{ID}-{story_name}**: {1-sentence summary of what was built and notable decisions}
 
 ### Escalated Stories (if any)
-- **{STORY-ID}**: Escalated after {N} bounces. Root cause: {why}. Recommendation: {rewrite spec / descope / kill}.
+- **STORY-{ID}-{story_name}**: Escalated after {N} bounces. Root cause: {why}. Recommendation: {rewrite spec / descope / kill}.
 
 ---
 
@@ -104,13 +105,13 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 
 | Story | Tokens | Duration | Agent Sessions | Bounces | Cost |
 |-------|--------|----------|----------------|---------|------|
-| STORY-{ID} | {N} | {Xh Ym} | {N} | {N} | ${X.XX} |
+| STORY-{ID}-{story_name} | {N} | {Xh Ym} | {N} | {N} | ${X.XX} |
 
 ### Threshold Alerts
 > Flag any metrics that crossed warning or critical thresholds. If none, write "No threshold alerts."
 
-- {e.g., "STORY-001-05: Correction Tax 10% (🟡) — root cause: test architecture rework due to ESM timer conflict"}
-- {e.g., "STORY-002-03: 2 QA bounces — spec ambiguity in edge case handling"}
+- {e.g., "STORY-001-05-test_arch: Correction Tax 10% (🟡) — root cause: test architecture rework due to ESM timer conflict"}
+- {e.g., "STORY-002-03-edge_cases: 2 QA bounces — spec ambiguity in edge case handling"}
 
 ---
 
@@ -120,7 +121,7 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 
 | Source | Lesson | Approved? |
 |--------|--------|-----------|
-| STORY-{ID} Dev Report | {What happened and proposed rule} | Pending / Yes / No |
+| STORY-{ID}-{story_name} Dev Report | {What happened and proposed rule} | Pending / Yes / No |
 
 ---
 
@@ -135,17 +136,55 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 ### What Didn't Go Well
 > Problems encountered, root causes, and impact on the sprint.
 
-- {e.g., "STORY-001-03 escalated because the spec was ambiguous — 3 QA bounces wasted"}
-- {e.g., "Merge conflict on STORY-002-01 required a fix story — cost an extra half-day"}
+- {e.g., "STORY-001-03-api_spec escalated because the spec was ambiguous — 3 QA bounces wasted"}
+- {e.g., "Merge conflict on STORY-002-01-database required a fix story — cost an extra half-day"}
 
-### Process Improvements
-> Changes to the V-Bounce delivery process itself — not just this project, but how we work.
+### Framework Self-Assessment
+> Aggregated from agent Process Feedback sections. Categorized by area of the V-Bounce framework.
+> Severity: **Friction** (slowed work) or **Blocker** (required workaround).
+> These feed the `improve` skill for framework evolution.
 
-- {e.g., "Story specs for L3+ stories should require Architect pre-review before bouncing"}
-- {e.g., "QA found the same import ordering issue in 3 stories — add linting rule to Dev setup, not just LESSONS.md"}
-- {e.g., "L3 stories consumed 4x the tokens of L2s — add a complexity budget to sprint planning"}
-- {e.g., "First-pass success rate was 40% — require Ambiguity 🟢 on all stories, not just Context Pack checks"}
-- {e.g., "Sprint Integration Audit (Step 6) found no issues in 3 consecutive sprints — consider making it conditional for small sprints"}
+#### Templates
+> Template sections that were confusing, incomplete, had unused fields, or were missing critical information.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "Story §3 missing 'existing modules to reuse' field"} | Developer | Friction | {Add a reuse checklist to the story template} |
+
+#### Agent Handoffs
+> Information that was missing, redundant, or unclear when passed between agents via reports.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "Dev report didn't specify test runner — QA had to discover it"} | QA | Friction | {Add 'test_runner' to Dev report YAML frontmatter} |
+
+#### RAG Pipeline
+> Context quality issues — irrelevant results, missing critical context, stale embeddings.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "Query for 'auth constraints' returned old sprint results"} | Developer | Friction | {Add date-weighted ranking to vbounce_ask.mjs} |
+
+#### Skills
+> Skill instructions that were unclear, had gaps, or could be improved for better agent performance.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "vibe-code-review Deep Audit missing accessibility dimension"} | Architect | Friction | {Add dimension 7 to deep-audit.md} |
+
+#### Process Flow
+> Steps that were unnecessary, wrongly ordered, or missing for this type of work.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "Fast Track stories still triggered Architect pass in the checklist"} | Team Lead | Blocker | {Update agent-team SKILL.md Step 4 skip logic} |
+
+#### Tooling & Scripts
+> Script failures, validation gaps, or automation opportunities.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "validate_report.mjs doesn't check for Process Feedback section"} | Team Lead | Friction | {Add optional section validation} |
 
 ---