vbounce-engine 2.5.1

package/skills/file-organization/TEST-RESULTS.md

@@ -0,0 +1,193 @@
+# File Organization Skill — Eval Results
+
+## Eval 1: Repro Script vs. Handler Fix
+
+**Prompt:** "I need to fix a race condition in the websocket handler. I wrote a quick Python script to simulate concurrent connections and reproduce the bug. I also fixed the actual handler. Where does each file go?"
+
+**Expected Output:** The Python repro script is a working artifact → /temporary/. The websocket handler fix is a deliverable → commit in place.
+
+**Relevant Guidance:**
+- "Script to reproduce a bug → debug-repro.py (working artifact)" (Line 33)
+- "I'm creating this because the user asked for it / it solves the task" → Project tree (Line 11)
+- "I'm creating this to help me work — debug, analyze, test an idea" → /temporary/ (Line 12)
+
+**Analysis:**
+The skill clearly distinguishes between debugging artifacts ("Script to reproduce a bug") and actual fixes. An agent following the core principle would recognize:
+- The Python script's intent: "help me understand/debug" → /temporary/
+- The handler fix's intent: "solves the task" → project tree
+
+The guidance is unambiguous. The agent gets the correct answer.
+
+**Rating: PASS**
+
+---
+
+## Eval 2: User-Requested Tests vs. Scratch File
+
+**Prompt:** "User asked me to add unit tests for the payment module. I also created a scratch file to test some regex patterns I needed for the validation logic. Where does each go?"
+
+**Expected Output:** The unit tests are deliverables (user asked for them) → project tree. The regex scratch file is a working artifact → /temporary/.
+
+**Relevant Guidance:**
+- "Write unit tests for auth" → auth.test.ts (deliverable) (Line 26)
+- "Add user validation with tests" example shows validate.test.ts as deliverable because "User asked for tests" (Line 85)
+- "Quick test to verify an assumption → check-behavior.js (working artifact)" (Line 35)
+
+**Analysis:**
+The skill explicitly handles this distinction in the "Add user validation with tests" example (Lines 76-85), which directly parallels Eval 2:
+- User-requested tests (validate.test.ts) = deliverable
+- Scratch working files (scratch-regex-test.js) = working artifact
+
+The key insight is whether **the user asked for** the tests. The skill states this clearly. An agent would correctly identify:
+- User explicitly asked for unit tests → deliverable
+- Regex pattern scratch file is "to help me work" (testing an assumption) → working artifact
+
+**Potential gap:** The skill doesn't address a borderline case where scratch tests could be mistaken for part of the test suite if the agent isn't careful about the "user asked for" criterion. However, the stated guidance is clear enough.
+
+**Rating: PASS**
+
+---
+
+## Eval 3: Existing Tracked Tests vs. Debug Script
+
+**Prompt:** "I see there's a tests/ directory with existing test files. I also see a file called check-api.sh in the root that I created yesterday to debug an endpoint. What should I do?"
+
+**Expected Output:** Leave the tests/ directory alone — it's an existing tracked test suite. Move check-api.sh to /temporary/ since it's a debug working artifact.
+
+**Relevant Guidance:**
+- "Existing files you modified (they're already tracked in git)" — Never working artifacts (Line 108)
+- "Test suites the project already has (`tests/`, `__tests__/`, `spec/`)" — Never working artifacts (Line 109)
+- "If a file already exists in the git tree, it belongs there. Your job is only to route **new files you create** during your working process." (Line 116)
+
+**Analysis:**
+The skill explicitly states that existing tracked files are "NEVER working artifacts" and gives `tests/` as a direct example. For check-api.sh, the intent is clear: debug artifact, not user-requested deliverable.
+
+An agent would correctly identify:
+1. tests/ is already tracked → don't touch it
+2. check-api.sh intent: "to help me debug" → /temporary/
+
+The guidance is explicit and unambiguous. The agent would get the right answer.
+
+**Rating: PASS**
+
+---
+
+## Eval 4: Generated-but-Committed Migration vs. Analysis Notes
+
+**Prompt:** "I'm working on a database migration task. I generated a migration file using the ORM CLI, and I also wrote an analysis.md exploring different indexing strategies. Where do these go?"
+
+**Expected Output:** The migration file is a deliverable (generated but committed as part of the project) → project tree. The analysis.md is a working artifact → /temporary/.
+
+**Relevant Guidance:**
+- "Database migrations are generated but absolutely committed" (Line 94)
+- "Migration files (database schema changes)" — Never working artifacts (Line 112)
+- "Markdown notes analyzing the codebase → analysis.md (working artifact)" (Line 34)
+
+**Analysis:**
+The skill handles this well. It explicitly recognizes that "generated" doesn't mean "working artifact" — migrations are generated by the ORM but belong in the project because they're **part of the deliverable** (schema changes that must be committed).
+
+For the migration file: The skill states directly "Migration files (database schema changes)" as something that is never a working artifact.
+
+For analysis.md: The skill lists "Markdown notes analyzing the codebase → analysis.md (working artifact)" — this directly matches the evaluation scenario.
+
+An agent would correctly identify:
+1. Migration file: "the project commits this" + "database schema changes" → project tree
+2. analysis.md: "notes analyzing the codebase" + "to help me work" → /temporary/
+
+The guidance is explicit and covers both cases directly.
+
+**Rating: PASS**
+
+---
+
+## Eval 5: Requested Component vs. Debug Render vs. Existing Test Suite
+
+**Prompt:** "I created a new React component as requested, plus a debug-render.jsx to test how it renders in isolation. The project already has a __tests__/ folder. Where does everything go?"
+
+**Expected Output:** The React component is a deliverable → project tree. debug-render.jsx is a working artifact → /temporary/. The __tests__/ folder is existing tracked code — don't touch it.
+
+**Relevant Guidance:**
+- "The user asked for it / it solves the task" → Project tree (Line 11)
+- "I need this to help me understand, debug, or explore" → /temporary/ (Line 31)
+- "Test suites the project already has (`tests/`, `__tests__/`, `spec/`)" — Never working artifacts (Line 109)
+
+**Analysis:**
+This eval tests three things:
+1. **Requested component:** Clear deliverable intent
+2. **Debug render file:** Clearly a working artifact ("test how it renders in isolation" = debugging/exploring)
+3. **Existing __tests__/ folder:** Explicitly listed as something to never move
+
+The skill handles all three. The guidance is clear. An agent would get the right answer.
+
+**Rating: PASS**
+
+---
+
+## Eval 6: Git Status Cleanup (Layer 2)
+
+**Prompt:** "Before committing, I ran git status and see: modified src/api/users.ts, new file src/api/users.test.ts (user asked for tests), new file output.log, new file temp-check.py. How do I clean this up?"
+
+**Expected Output:** Commit users.ts (modified existing) and users.test.ts (deliverable). Move output.log and temp-check.py to /temporary/ (working artifacts).
+
+**Relevant Guidance:**
+- Layer 2 reactive check (Lines 42-55)
+- "Did the user's task require this file? If no → move to /temporary/" (Line 53)
+- "Does this file exist in the project already? If yes, you're editing existing code — that's fine, leave it" (Line 54)
+- "Is this a new file I created to help myself work? If yes → move to /temporary/" (Line 55)
+- Example showing git status cleanup (Lines 57-74) with similar structure
+
+**Analysis:**
+The skill provides the Layer 2 reactive framework directly:
+1. **modified users.ts:** Already tracked → commit
+2. **new users.test.ts:** User asked for tests (stated in prompt) → commit
+3. **new output.log:** Created during working process (debug output) → /temporary/
+4. **new temp-check.py:** Name itself suggests "to help myself work" + temporary → /temporary/
+
+The example (Lines 57-74) shows the exact scenario structure. The three questions in Layer 2 map directly:
+- Q1 (did user ask?): No for output.log and temp-check.py → move
+- Q2 (already exists?): No for new files, but users.ts exists → commit users.ts
+- Q3 (new artifact?): Yes for output.log and temp-check.py → move
+
+An agent would get the right answer following the Layer 2 framework.
+
+**Rating: PASS**
+
+---
+
+## Summary Assessment
+
+| Eval | Result | Confidence | Notes |
+|------|--------|-----------|-------|
+| 1 | PASS | High | Clear distinction between debug script and fix |
+| 2 | PASS | High | Explicit example matches eval scenario |
+| 3 | PASS | High | Existing files explicitly excluded from working artifacts |
+| 4 | PASS | High | Migrations explicitly covered; analysis.md directly exemplified |
+| 5 | PASS | High | All three elements (new component, debug file, existing suite) handled clearly |
+| 6 | PASS | High | Layer 2 framework provides exact decision tree; example mirrors scenario |
+
+## Critical Findings
+
+**All evals achieve PASS.** The skill provides:
+
+1. **Clear intent-based framework** that works across all scenarios
+2. **Explicit examples** that map directly to evals 2, 4, 5, and 6
+3. **Direct lists** of files that are "NEVER working artifacts," covering edge cases in evals 3 and 5
+4. **Layer 2 reactive checks** that handle the git status scenario (eval 6) with a concrete decision tree
+5. **Explicit handling of "generated but committed"** files like migrations (eval 4)
+
+The skill successfully distinguishes user-requested deliverables from working artifacts across all cases. Agents following either Layer 1 (proactive) or Layer 2 (reactive) would arrive at correct answers for all six evals.
+
+### Strengths of the Skill
+
+- **Not file-type dependent:** The "intent" approach works for all scenarios without fragile extension-based rules
+- **Handles edge cases explicitly:** Migrations, codegen, existing tracked files all explicitly addressed
+- **Concrete examples:** Evals 2, 4, 5 are nearly identical to skill examples
+- **Dual-layer approach:** Catches mistakes at creation time or before commit
+
+### No Significant Gaps Identified
+
+All three "focus areas" from the prompt are handled well:
+- **Eval 2 (user-requested vs. scratch tests):** Clear distinction via "user asked for"
+- **Eval 3 (existing tracked files):** Explicit list + general rule about existing files
+- **Eval 4 (generated-but-committed):** Direct mention of migrations + intent-based reasoning
+

package/skills/file-organization/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "file-organization",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to fix a race condition in the websocket handler. I wrote a quick Python script to simulate concurrent connections and reproduce the bug. I also fixed the actual handler. Where does each file go?",
+      "expected_output": "The Python repro script is a working artifact → /temporary/. The websocket handler fix is a deliverable → commit in place.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "User asked me to add unit tests for the payment module. I also created a scratch file to test some regex patterns I needed for the validation logic. Where does each go?",
+      "expected_output": "The unit tests are deliverables (user asked for them) → project tree. The regex scratch file is a working artifact → /temporary/.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I see there's a tests/ directory with existing test files. I also see a file called check-api.sh in the root that I created yesterday to debug an endpoint. What should I do?",
+      "expected_output": "Leave the tests/ directory alone — it's an existing tracked test suite. Move check-api.sh to /temporary/ since it's a debug working artifact.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I'm working on a database migration task. I generated a migration file using the ORM CLI, and I also wrote an analysis.md exploring different indexing strategies. Where do these go?",
+      "expected_output": "The migration file is a deliverable (generated but committed as part of the project) → project tree. The analysis.md is a working artifact → /temporary/.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "I created a new React component as requested, plus a debug-render.jsx to test how it renders in isolation. The project already has a __tests__/ folder. Where does everything go?",
+      "expected_output": "The React component is a deliverable → project tree. debug-render.jsx is a working artifact → /temporary/. The __tests__/ folder is existing tracked code — don't touch it.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Before committing, I ran git status and see: modified src/api/users.ts, new file src/api/users.test.ts (user asked for tests), new file output.log, new file temp-check.py. How do I clean this up?",
+      "expected_output": "Commit users.ts (modified existing) and users.test.ts (deliverable). Move output.log and temp-check.py to /temporary/ (working artifacts).",
+      "files": []
+    }
+  ]
+}

package/skills/file-organization/references/gitignore-template.md

@@ -0,0 +1,53 @@
+# .gitignore Template for File Organization Standard
+
+Add this to your `./.gitignore` file to ensure `/temporary/` never gets committed:
+
+```gitignore
+# ============================================
+# Local temporary work (NEVER commit)
+# ============================================
+/temporary/
+```
+
+## Why This Matters
+
+The `/temporary/` folder is where agents and developers place all working files that won't be part of the final codebase:
+- Debug scripts
+- Test experiments
+- Analysis documents
+- Exploration code
+- Generated output
+
+By adding `/temporary/` to `.gitignore`, you ensure:
+1. ✅ No clutter in git history
+2. ✅ Team members only see production code in the repository
+3. ✅ Safe space for experimentation without affecting commits
+4. ✅ Reduced cognitive load when browsing the codebase
+
+## Installation
+
+If you don't have a `.gitignore` file yet:
+1. Create a new file called `.gitignore` in the root of your repository
+2. Add the entry above
+3. Commit it: `git add .gitignore && git commit -m "Add temporary folder to gitignore"`
+
+If you already have a `.gitignore`:
+1. Open it
+2. Add the entry above (preferably in a section labeled "Local temporary work")
+3. Commit the change
+
+## Verification
+
+To verify the setup is correct:
+```bash
+# This should NOT list any files from /temporary/
+git status
+
+# This should show that /temporary/ is ignored
+git check-ignore -v /temporary/something.txt
+```
+
+If `/temporary/` files are appearing in `git status`, double-check that:
+- The `.gitignore` entry is spelled correctly (case-sensitive on Linux/Mac)
+- The file is committed (not just created but not staged)
+- You haven't accidentally added `/temporary/` files with `git add -f`

package/skills/file-organization/references/quick-checklist.md

@@ -0,0 +1,48 @@
+# File Organization Quick Checklist
+
+## At File Creation Time
+
+```
+WHY am I creating this file?
+│
+├─ DELIVERABLE (serves the project / user asked for it)
+│  → Create in project tree
+│
+└─ WORKING ARTIFACT (helps me debug / analyze / explore)
+   → Create in /temporary/
+```
+
+## Before Committing
+
+```bash
+git diff --name-only
+git status
+```
+
+For each file:
+
+| Question | Answer | Action |
+|----------|--------|--------|
+| Did the user's task require this file? | Yes | Commit |
+| Is this an existing file I modified? | Yes | Commit |
+| Did I create this to help myself work? | Yes | Move to /temporary/ |
+| Not sure? | — | Move to /temporary/ (safer) |
+
+## Never Move These to /temporary/
+
+- Existing tracked files you edited
+- Project test suites (`tests/`, `__tests__/`, `spec/`)
+- CI/CD configs (`.github/workflows/`, `Dockerfile`)
+- Lock files (`package-lock.json`, `Cargo.lock`)
+- Migration files
+- Generated code the project commits (protobuf, codegen)
+- Config files (`.eslintrc`, `tsconfig.json`, etc.)
+
+## Common Working Artifacts (Always /temporary/)
+
+- Debug/repro scripts you wrote to investigate
+- Analysis or exploration markdown
+- Scratch files testing an idea
+- Console output or logs you captured
+- Experimental code trying different approaches
+- Notes and drafts that aren't official docs

package/skills/improve/SKILL.md

@@ -0,0 +1,296 @@
+---
+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, 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, 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
+
+- **Automatically** — `vbounce sprint close S-XX` runs the improvement pipeline and regenerates `.vbounce/improvement-suggestions.md` (overwrites previous — always reflects latest data)
+- **On demand** — `vbounce improve S-XX` runs the full pipeline (trends + analyzer + suggestions)
+- **Applying changes:** After every 1-3 sprints, human reviews suggestions and runs `/improve` to apply approved ones. The analysis runs every sprint; applying changes is the human's call.
+- 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 `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
+  │
+  ├── .vbounce/scripts/sprint_trends.mjs          → .vbounce/trends.md
+  │
+  ├── .vbounce/scripts/post_sprint_improve.mjs    → .vbounce/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
+  │
+  └── .vbounce/scripts/suggest_improvements.mjs   → .vbounce/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 |
+|------|---------|
+| `.vbounce/improvement-manifest.json` | Machine-readable proposals with metadata (consumed by this skill) |
+| `.vbounce/improvement-suggestions.md` | Human-readable improvement suggestions with impact levels |
+| `.vbounce/trends.md` | Cross-sprint trend data |
+
+## Input Sources
+
+The improve skill reads from multiple signals, in priority order:
+
+### 1. Improvement Manifest (Primary — Machine-Generated)
+Read `.vbounce/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)
+
+### 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..." | `.vbounce/gate-checks.json` or `pre_gate_runner.sh` |
+| **script** | Rules with "Run X before Y", "Use X instead of Y" | `.vbounce/scripts/` |
+| **template_field** | Rules with "Include X in...", "Add X to the story/epic/template" | `.vbounce/templates/*.md` |
+| **agent_config** | General behavioral rules proven over 3+ sprints | `.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.
+
+### 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
+
+### 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 `.vbounce/archive/` and extract `## Process Feedback` sections directly.
+
+## The Improvement Process
+
+### Step 1: Read the Manifest
+```
+1. Read .vbounce/improvement-manifest.json (if it exists)
+2. Read .vbounce/improvement-suggestions.md for human-readable context
+3. If no manifest exists, run: vbounce improve S-XX to generate one
+```
+
+### 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?
+
+### Step 3: Prioritize Using Impact Levels
+Rank all proposals (manifest + manual) by impact:
+
+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:
+
+```markdown
+### Proposal {N}: {Short title}
+
+**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:**
+- `{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}
+```
+
+#### Special Case: Lesson → Gate Check Proposals
+
+When a lesson contains a mechanical rule (classified as `gate_check` in the manifest):
+
+```markdown
+### Proposal {N}: Add pre-gate check — {check name}
+
+**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 `.vbounce/gate-checks.json`:**
+```json
+{
+  "id": "custom_grep",
+  "gate": "arch",
+  "enabled": true,
+  "pattern": "{regex}",
+  "glob": "{file pattern}",
+  "should_find": false,
+  "description": "{human-readable description}"
+}
+```
+```
+
+#### 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:** `.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, grouped by impact level. 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 `.vbounce/CHANGELOG.md`
+4. If skills were modified, update skill descriptions in all brain files that reference them
+5. Record in `.vbounce/improvement-log.md` under "Applied" with the impact level
+
+### Step 7: Validate
+After all changes are applied:
+1. Run `vbounce doctor` to verify framework integrity
+2. Verify no cross-references are broken (template paths, skill names, report field names)
+3. Confirm brain file consistency — all surfaces should describe the same process
+
+## Improvement Scope
+
+### What CAN Be Improved
+
+| 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
+- **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 produces:
+1. The list of proposals presented to the human (inline during the conversation)
+2. The applied changes to framework files
+3. The `.vbounce/CHANGELOG.md` entries documenting what changed and why
+4. Updates to `.vbounce/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 — 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)"
+- "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 `.vbounce/CHANGELOG.md` with the finding that motivated it.
+- **Run `vbounce doctor` after changes.** Verify framework integrity after applying improvements.
+- **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, impact levels, lesson graduation, gate check, automation