@sandrinio/vbounce 1.9.0 → 2.0.0

package/skills/doc-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doc-manager
-description: "Use when creating, modifying, or navigating V-Bounce Engine planning documents. Trigger on any request to create a charter, roadmap, epic, story, delivery plan, or risk registry — or when the user asks to update, refine, decompose, or transition documents between phases. Also trigger when an agent needs to know which template to use, where a document fits in the hierarchy, or what upstream/downstream documents to read before writing. This skill manages the full document lifecycle from Charter through Sprint execution."
+description: "Use when creating, modifying, or navigating V-Bounce Engine planning documents. Trigger on any request to create a charter, roadmap, epic, story, delivery plan, sprint plan, or risk registry — or when the user asks to update, refine, decompose, or transition documents between phases. Also trigger when the user asks about work status, backlog, what's next, what's blocked, or wants to plan/start a sprint. This skill manages the full document lifecycle from Charter through Sprint Planning and execution."
 ---
 
 # Document Hierarchy Manager
@@ -49,7 +49,7 @@ Roadmap §5 (Constraints) ──→ Delivery Plan (sprint capacity)
 
 Epic §2 (Scope Boundaries) ──→ Story §1 (The Spec)
 Epic §4 (Technical Context) ──→ Story §3 (Implementation Guide)
-Epic §5 (Decomposition) ──→ Story creation sequence
+Epic §5 (Decomposition) ──→ Codebase research scope + Story creation sequence
 Epic §6 (Risks) ──→ Risk Registry §1 (Active Risks)
 Epic §7 (Acceptance Criteria) ──→ Story §2 (The Truth)
 Epic §9 (Artifact Links) ──→ Delivery Plan §3 (Backlog)
@@ -64,6 +64,12 @@ Sprint Plan §1 (Context Pack Readiness) ──→ Ready to Bounce gate
 Delivery Plan ──→ Updated at sprint boundaries ONLY (never mid-sprint)
 
 Risk Registry ←── ALL levels (cross-cutting input)
+
+Epic §8 (Open Questions) ──→ Spike §1 (Question)
+Epic §4 (Technical Context) ──→ Spike §3 (Approach)
+Spike §4 (Findings) ──→ Epic §4 (Technical Context) [update]
+Spike §5 (Decision) ──→ Roadmap §3 (ADRs) [if architectural]
+Spike §6 (Residual Risk) ──→ Risk Registry §1 (Active Risks)
 ```
 
 ## Template Locations
@@ -77,6 +83,7 @@ Risk Registry ←── ALL levels (cross-cutting input)
 | Sprint Plan | `templates/sprint.md` | `product_plans/sprints/sprint-{XX}/sprint-{XX}.md` |
 | Epic | `templates/epic.md` | `product_plans/backlog/EPIC-{NNN}_{name}/EPIC-{NNN}_{name}.md` |
 | Story | `templates/story.md` | `product_plans/backlog/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}-{StoryName}.md` |
+| Spike | `templates/spike.md` | `product_plans/backlog/EPIC-{NNN}_{name}/SPIKE-{EpicID}-{NNN}-{topic}.md` |
 | Hotfix | `templates/hotfix.md` | `product_plans/hotfixes/HOTFIX-{Date}-{Name}.md` |
 | Sprint Report | `templates/sprint_report.md` | `product_plans/sprints/sprint-{XX}/sprint-report.md` |
 
@@ -94,7 +101,8 @@ product_plans/
 │   ├── EPIC-001_authentication/
 │   │   ├── EPIC-001_authentication.md
 │   │   ├── STORY-001-01-login_ui.md
-│   │   └── STORY-001-02-auth_api.md
+│   │   ├── STORY-001-02-auth_api.md
+│   │   └── SPIKE-001-001-auth-provider.md
 │
 ├── sprints/                       ← active execution workspace
 │   ├── sprint-01/                 ← active sprint boundary
@@ -152,6 +160,36 @@ Brain files contain the V-Bounce process, critical rules, and skill references.
 
 ## Document Operations
 
+### Ambiguity Assessment Rubric
+
+When creating or reviewing an Epic or Story, assess ambiguity using these signals:
+
+**🔴 High — Discovery Required (any ONE triggers 🔴):**
+- Epic §4 Technical Context has "TBD" or "unknown" in dependencies or affected areas
+- Epic §8 Open Questions has items marked blocking
+- Multiple competing approaches mentioned with no ADR deciding between them
+- Unknown external dependencies or integrations
+- No acceptance criteria defined (Epic §7 empty)
+- Vague scope language in §2 ("various", "possibly", "might", "somehow", "rethink")
+
+**🟡 Medium — Conditional Progress:**
+- Technical Context partially filled (some areas known, others TBD)
+- Open Questions exist but are non-blocking
+- Dependencies listed but unconfirmed
+
+**🟢 Low — Ready to Proceed:**
+- All sections filled with specific, concrete content
+- All Open Questions resolved or non-blocking
+- ADRs exist for every major technical choice
+- Acceptance criteria are concrete Gherkin scenarios
+
+**When 🔴 is detected:**
+1. Set `ambiguity: 🔴 High` in frontmatter
+2. Identify which signals triggered it
+3. For each signal, recommend a spike with a one-sentence question
+4. Create spike documents from `templates/spike.md`
+5. Block downstream transitions until spikes reach Validated or Closed
+
 ### CREATE — Making a New Document
 
 Before creating any document, YOU MUST:
@@ -169,8 +207,10 @@ Before creating any document, YOU MUST:
 |----------|-----------------|
 | Charter | Nothing — Charter is root. Gather from user input. |
 | Roadmap | Charter (full document) |
-| Epic | Charter §1, §2, §5 + Roadmap §2, §3, §5 |
-| Story | Parent Epic (full document) + Roadmap §3 (ADRs) |
+| Epic | Charter §1, §2, §5 + Roadmap §2, §3, §5 + **Codebase** (explore affected areas for §4) |
+| Story | Parent Epic (full document) + Roadmap §3 (ADRs) + Codebase (affected files) |
+| Spike | Parent Epic (full document) + Roadmap §3 (ADRs) + Risk Registry |
+| Sprint Plan | All candidate stories + Risk Registry + Archive (completed work) + Backlog state |
 | Delivery Plan | Roadmap §2 (Release Plan) + All Stories in scope |
 | Risk Registry | Charter §6 + Roadmap §4, §5 + All Epic §6 sections |
 
@@ -199,20 +239,99 @@ When modifying a document:
 | Epic §4 (Technical Context) | All child Stories §3 (Implementation Guide) |
 | Story status (V-Bounce State) | Delivery Plan §3 (Active Sprint table) |
 | Story — new risk discovered | Risk Registry §1 (new row) |
+| Spike §4/§5 (Findings/Decision) | Epic §4 Technical Context, Epic §8 Open Questions, Risk Registry §1 |
+| Spike §5 (Decision — architectural) | Roadmap §3 ADRs (new row) |
 
 ### DECOMPOSE — Breaking Down Documents
 
 **Epic → Stories:**
 
-1. Read Epic §5 (Decomposition Guidance) for the checklist and suggested sequence
-2. Create one Story per checked category (Schema, API, UI, Integration, etc.)
-3. For each Story:
-   - Pull §1 The Spec from Epic §2 Scope Boundaries (relevant items only)
-   - Pull §2 The Truth from Epic §7 Acceptance Criteria (decomposed per story)
-   - Pull §3 Implementation Guide from Epic §4 Technical Context
-   - Set Complexity Label (L1-L4) based on file count and pattern familiarity
-4. Link all created Stories back in Epic §9 Artifact Links
-5. Update Delivery Plan §3 High-Level Backlog with new stories
+Stories are NOT created by mechanically splitting epic sections by category. The AI must analyze the epic, research the actual codebase, and produce small, focused stories — each delivering a tangible, independently verifiable result.
+
+#### Phase 1: Analyze & Research
+
+1. Read the full Epic document (all sections)
+2. Read Roadmap §3 (ADRs) for architecture constraints
+3. **Research the codebase** — this is mandatory, not optional:
+   - Read every file listed in Epic §4 Affected Areas
+   - Explore the surrounding code to understand current architecture, patterns, and conventions
+   - Identify actual dependencies, imports, and integration points in the code
+   - Note existing tests, utilities, and shared modules that stories will interact with
+4. Build a mental model of what needs to change and in what order
+
+#### Phase 2: Draft Stories by Deliverable, Not by Category
+
+Do NOT create stories by layer (one for schema, one for API, one for UI). Instead, create stories by **tangible outcome** — each story should deliver a small, specific, working result that can be verified.
+
+**Story sizing rules:**
+- Each story has **one clear goal** expressible in a single sentence
+- Each story touches **1-3 files** (if more, it needs splitting)
+- Each story produces a **verifiable result** — something you can see, test, or demonstrate
+- Each story is **independently meaningful** — it delivers value or unlocks the next story, not just "part of a layer"
+- Prefer vertical slices (thin end-to-end) over horizontal slices (full layer)
+
+**If a drafted story exceeds size:**
+- Ask: "Can this be split into two stories that each produce a tangible result?"
+- If yes → split it. Each sub-story must still have its own clear goal.
+- If no (the work is inherently atomic) → keep it as one story, label it L3, and document why it can't be smaller.
+
+#### Phase 3: Write Stories with Codebase-Informed Detail
+
+For each story, use what you learned from codebase research:
+- §1 The Spec: Write requirements informed by actual code state (not just epic abstractions)
+- §2 The Truth: Write Gherkin scenarios that reference real components, routes, and data shapes found in the code
+- §3 Implementation Guide: Reference actual file paths, existing patterns, real function signatures — not placeholders. The developer should be able to start coding immediately.
+- Set Complexity Label (L1-L4) based on actual code complexity discovered during research
+
+#### Phase 4: Link & Update
+
+1. Link all created Stories back in Epic §9 Artifact Links
+2. Update Delivery Plan §3 High-Level Backlog with new stories
+
+### SPRINT PLANNING — Preparing a Sprint
+
+Sprint Planning is a collaborative process between AI and human. No sprint starts without a confirmed Sprint Plan.
+
+**Workflow:**
+
+1. **Read current state:**
+   - Scan `product_plans/backlog/` — read all epic and story frontmatter (status, priority, ambiguity, complexity_label, open questions)
+   - Scan `product_plans/archive/` — understand what's already shipped and what context carries forward
+   - Read `product_plans/strategy/RISK_REGISTRY.md` — identify risks affecting candidate stories
+   - If `vdocs/_manifest.json` exists, read it for documentation context
+
+2. **Propose sprint scope:**
+   - Select stories based on priority, dependencies, and capacity
+   - Identify dependency chains — stories with `Depends On:` must be sequenced
+   - Group parallel-safe stories into phases
+   - Flag stories with 🔴 High ambiguity — these CANNOT enter the sprint without completed spikes
+
+3. **Surface blockers to the human:**
+   - Open questions from epics (§8) and stories that haven't been resolved
+   - Environment prerequisites missing from stories
+   - Risks from Risk Registry that affect planned stories
+   - Edge cases or ambiguity the human may not have considered
+   - Dependencies on incomplete work
+
+4. **Collaborate with the human:**
+   - Present proposed scope, risks, and blockers
+   - Discuss and adjust — add/remove stories, resolve open questions
+   - Agree on execution mode per story (Full Bounce vs Fast Track)
+
+5. **Create Sprint Plan:**
+   - Create `product_plans/sprints/sprint-{XX}/sprint-{XX}.md` from `templates/sprint.md`
+   - Fill §0 Sprint Readiness Gate checklist
+   - Fill §1 Active Scope with confirmed stories + Context Pack Readiness
+   - Fill §2 Execution Strategy (phases, dependencies, risk flags)
+   - Fill §3 Sprint Open Questions (all must be resolved or non-blocking)
+   - Set status: `Planning`
+
+6. **Gate — Human confirms:**
+   - Present finalized plan to human
+   - Explicitly ask for confirmation
+   - On confirmation: set `status: Confirmed`, fill `confirmed_by` and `confirmed_at`
+   - Move story files from `product_plans/backlog/EPIC-{NNN}/` to `product_plans/sprints/sprint-{XX}/`
+   - Sprint is now ready for Phase 3 (Execution)
 
 ### TRANSITION — Moving Documents Between Phases
 
@@ -223,7 +342,12 @@ When modifying a document:
 | Charter → Ready for Roadmap | Ambiguity 🟡 or 🟢 (§1 and §5 filled) |
 | Roadmap → Ready for Epics | Charter Ambiguity 🟢 + Roadmap §2 and §3 filled |
 | Epic → Ready for Stories | Ambiguity 🟡 or 🟢 (§2 Scope and §4 Tech Context filled) |
-| Story → Ready to Bounce | Ambiguity 🟢 + ALL Context Pack items checked (Delivery Plan §5) |
+| Story → Ready to Bounce | Ambiguity 🟢 + ALL Context Pack items checked (Sprint Plan §1) |
+| Sprint Plan → Confirmed | §0 Readiness Gate checklist complete + Human explicitly confirms |
+| Sprint Plan → Active | Status is Confirmed (human approval obtained) |
+| Story (Probing/Spiking) → Refinement | All linked spikes are Validated or Closed |
+| Spike → Validated | Architect confirms findings against Safe Zone |
+| Spike → Closed | All items in §7 Affected Documents are checked off |
 | Hotfix → Bouncing | Complexity strictly L1 + Targets 1-2 files |
 
 **Physical Move Rules for State Transitions:**
@@ -257,9 +381,9 @@ Bouncing → Done: Dev implements + Human manually verifies + DevOps runs `hotfi
 | Agent | Documents Owned | Documents Read |
 |-------|----------------|----------------|
 | **Team Lead** | Delivery Plan, Sprint Report, Delivery archive | Charter, Roadmap, ALL Stories (for context packs) |
-| **Developer** | Story §3 updates (during implementation) | Story §1 + §3, LESSONS.md |
+| **Developer** | Story §3 updates (during implementation), Spike §4 Findings (during investigation) | Story §1 + §3, Spike §1 + §2 + §3, LESSONS.md |
 | **QA** | QA Validation Report | Story §2, Dev Implementation Report |
-| **Architect** | Architectural Audit Report, Risk flags (in report — Lead writes to Registry) | Full Story, Roadmap §3 ADRs, Risk Registry |
+| **Architect** | Architectural Audit Report, Risk flags (in report — Lead writes to Registry), Spike validation (Findings Ready → Validated) | Full Story, Spike §4 + §5, Roadmap §3 ADRs, Risk Registry |
 | **DevOps** | DevOps Reports (merge + release) | Delivery Plan, LESSONS.md, gate reports |
 | **Scribe** | Product documentation, _manifest.json | Sprint Report, Dev Reports, codebase |
 | **PM/BA (Human)** | Charter, Roadmap, Epic, Story §1 + §2 | Everything |
@@ -289,4 +413,4 @@ When a sprint is complete:
 
 ## Keywords
 
-charter, roadmap, epic, story, delivery plan, risk registry, document hierarchy, template, create document, update document, decompose epic, story breakdown, ambiguity score, context pack, V-Bounce state, phase transition, cascade update, planning documents
+charter, roadmap, epic, story, delivery plan, risk registry, sprint plan, sprint planning, document hierarchy, template, create document, update document, decompose epic, story breakdown, ambiguity score, context pack, V-Bounce state, phase transition, cascade update, planning documents, backlog, what's next, what's blocked, start sprint

package/skills/improve/SKILL.md

@@ -1,19 +1,47 @@
 ---
 name: improve
-description: "Use when the V-Bounce Engine 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."
+description: "Use when the V-Bounce Engine 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, analyzes LESSONS.md for automation candidates, identifies patterns, proposes specific changes to templates, skills, brain files, scripts, and agent configs with impact levels, and applies approved changes. This is the system's self-improvement loop."
 ---
 
 # Framework Self-Improvement
 
 ## Purpose
 
-V-Bounce Engine 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.
+V-Bounce Engine 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, analyzes which lessons can be automated, 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.
 
+## Impact Levels
+
+Every improvement proposal is classified by impact to help the human prioritize:
+
+| Level | Label | Meaning | Timeline |
+|-------|-------|---------|----------|
+| **P0** | Critical | Blocks agent work or causes incorrect output | Fix before next sprint |
+| **P1** | High | Causes rework — bounces, wasted tokens, repeated manual steps | Fix this improvement cycle |
+| **P2** | Medium | Friction that slows agents but does not block | Fix within 2 sprints |
+| **P3** | Low | Polish — nice-to-have, batch with other improvements | Batch when convenient |
+
+### How Impact Is Determined
+
+| Signal | Impact |
+|--------|--------|
+| Blocker finding + recurring across 2+ sprints | **P0** |
+| Blocker finding (single sprint) | **P1** |
+| Friction finding recurring across 2+ sprints | **P1** |
+| Lesson with mechanical rule (can be a gate check or script) | **P1** |
+| Previous improvement that didn't resolve its finding | **P1** |
+| Friction finding (single sprint) | **P2** |
+| Lesson graduation candidate (3+ sprints old) | **P2** |
+| Low first-pass rate or high correction tax | **P1** |
+| High bounce rate | **P2** |
+| Framework health checks | **P3** |
+
 ## When to Use
 
-- After every 2-3 sprints (recommended cadence)
+- **Automatically** — `vbounce sprint close S-XX` runs the improvement pipeline and generates `.bounce/improvement-suggestions.md`
+- **On demand** — `vbounce improve S-XX` runs the full pipeline (trends + analyzer + suggestions)
+- After every 2-3 sprints (recommended cadence for applying approved changes)
 - 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
@@ -21,70 +49,102 @@ V-Bounce Engine is not static. Every sprint generates friction signals from agen
 
 ## Trigger
 
-`/improve` OR when the Team Lead identifies recurring framework friction during Sprint Consolidation.
+`/improve` OR `vbounce improve S-XX` 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."
 
+## The Automated Pipeline
+
+The self-improvement pipeline runs automatically on `vbounce sprint close` and can be triggered manually via `vbounce improve S-XX`:
+
+```
+vbounce sprint close S-XX
+  │
+  ├── scripts/sprint_trends.mjs          → .bounce/trends.md
+  │
+  ├── scripts/post_sprint_improve.mjs    → .bounce/improvement-manifest.json
+  │   ├── Parse Sprint Report §5 Framework Self-Assessment tables
+  │   ├── Parse LESSONS.md for automation candidates
+  │   ├── Cross-reference archived sprint reports for recurring patterns
+  │   └── Check if previous improvements resolved their findings
+  │
+  └── scripts/suggest_improvements.mjs   → .bounce/improvement-suggestions.md
+      ├── Consume improvement-manifest.json
+      ├── Add metric-driven suggestions (bounce rate, correction tax, first-pass rate)
+      ├── Add lesson graduation candidates
+      └── Format with impact levels for human review
+```
+
+### Output Files
+
+| File | Purpose |
+|------|---------|
+| `.bounce/improvement-manifest.json` | Machine-readable proposals with metadata (consumed by this skill) |
+| `.bounce/improvement-suggestions.md` | Human-readable improvement suggestions with impact levels |
+| `.bounce/trends.md` | Cross-sprint trend data |
+
 ## 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:
+### 1. Improvement Manifest (Primary — Machine-Generated)
+Read `.bounce/improvement-manifest.json` first. It contains pre-analyzed proposals with impact levels, automation classifications, recurrence data, and effectiveness checks. This is the richest, most structured input.
+
+### 2. Sprint Report §5 — Framework Self-Assessment
+The structured retro tables are the richest human-authored 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. LESSONS.md — Automation Candidates
+Lessons are classified by automation potential:
+
+| Automation Type | What to Look For | Target |
+|----------------|-----------------|--------|
+| **gate_check** | Rules with "Always check...", "Never use...", "Must have..." | `.bounce/gate-checks.json` or `pre_gate_runner.sh` |
+| **script** | Rules with "Run X before Y", "Use X instead of Y" | `scripts/` |
+| **template_field** | Rules with "Include X in...", "Add X to the story/epic/template" | `templates/*.md` |
+| **agent_config** | General behavioral rules proven over 3+ sprints | `brains/claude-agents/*.md` |
+
+**Key insight:** Lessons tell you WHAT to enforce. Sprint retro tells you WHERE the framework is weak. Together they drive targeted improvements.
 
-### 3. Sprint Execution Metrics
+### 4. 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)
+### 5. Improvement Effectiveness
+The pipeline checks whether previously applied improvements resolved their target findings. Unresolved improvements are re-escalated at P1 priority.
+
+### 6. 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
+### Step 1: Read the Manifest
 ```
-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/
+1. Read .bounce/improvement-manifest.json (if it exists)
+2. Read .bounce/improvement-suggestions.md for human-readable context
+3. If no manifest exists, run: vbounce improve S-XX to generate one
 ```
 
-### 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` |
-| **Context Prep** | Missing context, stale prep packs, truncation issues | `scripts/prep_sprint_context.mjs`, `scripts/prep_qa_context.mjs`, `scripts/prep_arch_context.mjs` |
-| **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` |
+### Step 2: Supplement with Manual Analysis
+The manifest handles mechanical detection. The /improve skill adds judgment:
+- Are there patterns the scripts can't detect? (e.g., misaligned mental models between agents)
+- Do the metric anomalies have root causes not captured in §5?
+- Are there skill instructions that agents consistently misinterpret?
 
-Deduplicate: if 3 agents report the same issue, that's 1 finding with 3 votes — not 3 findings.
+### Step 3: Prioritize Using Impact Levels
+Rank all proposals (manifest + manual) by impact:
 
-### 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)
+1. **P0 Critical** — Fix before next sprint. Non-negotiable.
+2. **P1 High** — Fix in this improvement pass.
+3. **P2 Medium** — Fix if bandwidth allows, otherwise defer.
+4. **P3 Low** — Batch with other improvements when convenient.
 
 ### Step 4: Propose Changes
 For each finding, write a concrete proposal:
@@ -92,7 +152,8 @@ For each finding, write a concrete proposal:
 ```markdown
 ### Proposal {N}: {Short title}
 
-**Finding:** {What went wrong — from the retro}
+**Impact:** {P0/P1/P2/P3} — {reason}
+**Finding:** {What went wrong — from the retro or lesson}
 **Pattern:** {How many times / sprints this appeared}
 **Root Cause:** {Why the framework allowed this to happen}
 **Affected Files:**
@@ -107,15 +168,16 @@ For script changes, describe the new behavior.}
 **Reversibility:** {Easy — revert the edit / Medium — downstream docs may need updating}
 ```
 
-#### Special Case: Gate Check Proposals
+#### Special Case: Lesson → Gate Check Proposals
 
-When agent feedback reveals a mechanical check that was repeated manually across multiple stories (e.g., "QA checked for inline styles 4 times"), propose adding it as a pre-gate check instead of a skill/template change:
+When a lesson contains a mechanical rule (classified as `gate_check` in the manifest):
 
 ```markdown
 ### Proposal {N}: Add pre-gate check — {check name}
 
-**Finding:** {Agent} manually performed {check description} in {N} stories this sprint.
-**Tokens saved:** ~{estimate} per story (based on agent token usage for this check type)
+**Impact:** P1 — mechanical check currently performed manually by agents
+**Lesson:** "{lesson title}" (active since {date})
+**Rule:** {the lesson's rule}
 **Gate:** qa / arch
 **Check config to add to `.bounce/gate-checks.json`:**
 ```json
@@ -131,10 +193,35 @@ When agent feedback reveals a mechanical check that was repeated manually across
 ```
 ```
 
-This is the primary mechanism for the gate system to grow organically — the `improve` skill reads what agents repeatedly checked by hand and proposes automating those checks via `gate-checks.json`.
+#### Special Case: Lesson → Script Proposals
+
+When a lesson describes a procedural check:
+
+```markdown
+### Proposal {N}: Automate — {check name}
+
+**Impact:** P1 — repeated manual procedure
+**Lesson:** "{lesson title}" (active since {date})
+**Rule:** {the lesson's rule}
+**Proposed script/enhancement:** {describe the new script or addition to existing script}
+```
+
+#### Special Case: Lesson Graduation
+
+When a lesson has been active 3+ sprints and is classified as `agent_config`:
+
+```markdown
+### Proposal {N}: Graduate lesson — "{title}"
+
+**Impact:** P2 — proven rule ready for permanent enforcement
+**Active since:** {date} ({N} sprints)
+**Rule:** {the lesson's rule}
+**Target agent config:** `brains/claude-agents/{agent}.md`
+**Action:** Add rule to agent's Critical Rules section. Archive lesson from LESSONS.md.
+```
 
 ### Step 5: Present to Human
-Present ALL proposals as a numbered list. The human can:
+Present ALL proposals as a numbered list, grouped by impact level. The human can:
 - **Approve** — apply the change
 - **Reject** — skip it (optionally explain why)
 - **Modify** — adjust the proposal before applying
@@ -148,26 +235,27 @@ For each approved proposal:
 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
+5. Record in `.bounce/improvement-log.md` under "Applied" with the impact level
 
 ### 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
+3. Confirm brain file consistency — all 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 |
+| Target | Examples | Typical Impact |
+|--------|---------|----------------|
+| **Gate Checks** | New grep/lint rules from lessons | P1 |
+| **Scripts** | New validation, automate manual steps | P1-P2 |
+| **Templates** | Add/remove/rename sections, improve instructions | P2 |
+| **Agent Report Formats** | Add/remove YAML fields, improve handoff clarity | P1-P2 |
+| **Skills** | Update instructions, add/remove steps, add new skills | P1-P2 |
+| **Brain Files** | Graduate lessons to permanent rules, update skill refs | P2 |
+| **Process Flow** | Reorder steps, add/remove gates, adjust thresholds | P1 |
 
 ### What CANNOT Be Changed Without Escalation
 - **Adding a new agent role** — requires human design decision + new brain config
@@ -177,14 +265,15 @@ After all changes are applied:
 
 ## Output
 
-The improve skill does not produce a standalone report file. Its output is:
+The improve skill produces:
 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
+4. Updates to `.bounce/improvement-log.md` tracking approved/rejected/deferred items
 
 ## 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.
+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 — the pipeline will automatically detect this and re-escalate at P1 priority.
 
 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)"
@@ -199,7 +288,9 @@ The Team Lead should note in the Sprint Report whether the previous improvement
 - **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.
+- **Impact levels drive priority.** P0 and P1 items are addressed first. P3 items are batched.
+- **Lessons are fuel.** Every lesson is a potential automation — classify and act on them.
 
 ## Keywords
 
-improve, self-improvement, framework evolution, retro, retrospective, process feedback, friction, template improvement, skill improvement, brain sync, meta-process, self-aware
+improve, self-improvement, framework evolution, retro, retrospective, process feedback, friction, template improvement, skill improvement, brain sync, meta-process, self-aware, impact levels, lesson graduation, gate check, automation

package/skills/lesson/SKILL.md

@@ -31,6 +31,20 @@ This is NOT just a command — it is a standing directive:
 3. **When offering**, say: *"This looks like a lesson worth recording — want me to capture it?"*
 4. **Never record without the user's approval.** Always ask first.
 
+## Timing: Record Immediately, Not at Sprint Close
+
+**Lessons MUST be recorded as soon as the story that produced them is merged** — not deferred to sprint close. Context decays fast.
+
+**Flow:**
+1. During execution, agents flag lessons in their reports (`lessons_flagged` field)
+2. After DevOps merges a story (Phase 3, Step 9), the Team Lead immediately:
+   - Reads `lessons_flagged` from Dev and QA reports
+   - Presents each lesson to the human for approval
+   - Records approved lessons to LESSONS.md right away
+3. At sprint close (Sprint Report §4), the lesson table serves as a **review of what was already recorded** — not a first-time approval step. This is a confirmation, not a gate.
+
+**Why this matters:** A lesson recorded 5 minutes after the problem is specific and actionable. A lesson recorded 3 days later at sprint close is vague and often forgotten.
+
 ## Recording: The `/lesson` Command
 
 ### Step 1: Gather Context

package/templates/epic.md

@@ -21,10 +21,12 @@ Output location: `product_plans/backlog/EPIC-{NNN}_{epic_name}/EPIC-{NNN}_{epic_
 
 Document Hierarchy Position: LEVEL 3 (Charter → Roadmap → **Epic** → Story)
 
+**Codebase research is mandatory when filling §4 Technical Context.** Do NOT guess at affected files, dependencies, or integration points. Read the actual codebase — explore directories, read files listed in upstream documents, understand current architecture — then fill §4 with real file paths and verified dependencies.
+
 Upstream sources:
 - §1 Problem & Value traces to Charter §1.1 (What It Is) and §5 (Key Workflows)
 - §3.3 Constraints inherits from Charter §6 and Roadmap §5 Strategic Constraints
-- §4 Technical Context references Roadmap §3 ADRs for architecture decisions
+- §4 Technical Context references Roadmap §3 ADRs for architecture decisions AND actual codebase exploration
 - Metadata.Priority aligns with Roadmap §2 Release Plan epic priorities
 
 Downstream consumers:
@@ -132,21 +134,22 @@ flowchart LR
 ---
 
 ## 5. Decomposition Guidance
-> Hints for AI story breakdown. Check all that apply.
-
-- [ ] **Schema/Migration** - Database changes, new tables/fields
-- [ ] **API Work** - New/modified endpoints
-- [ ] **UI Work** - New screens or components
-- [ ] **Integration** - External service connection
-- [ ] **Infrastructure** - Config, env vars, deployment
-- [ ] **Testing** - E2E, integration tests
-- [ ] **Documentation** - User-facing or API docs
-
-### Suggested Story Sequence
-1. {First: usually schema/data layer}
-2. {Then: API/backend layer}
-3. {Then: UI/frontend layer}
-4. {Finally: integration + E2E tests}
+> The AI agent will analyze this epic and research the codebase to create small, focused stories. Each story must deliver a tangible, verifiable result — not just a layer of work.
+
+### Affected Areas (for codebase research)
+- [ ] {Area 1: e.g., "Authentication flow in `src/auth/`"}
+- [ ] {Area 2: e.g., "User profile API in `src/api/users.ts`"}
+- [ ] {Area 3: e.g., "Dashboard component in `src/components/Dashboard/`"}
+
+### Key Constraints for Story Sizing
+- Each story should touch 1-3 files and have one clear goal
+- Prefer vertical slices (thin end-to-end) over horizontal layers
+- Stories must be independently verifiable
+
+### Suggested Sequencing Hints
+1. {What must exist first for other work to build on}
+2. {What depends on #1}
+3. {What can run in parallel}
 
 ---