vbounce-engine 2.5.1

package/skills/lesson/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: lesson
+description: Use when recording project-specific mistakes, gotchas, or hard-won knowledge. Also activates proactively when a mistake pattern is detected during work.
+---
+
+# Lessons Learned
+
+Captures project-specific mistakes and rules into `LESSONS.md` so they are never repeated. YOU MUST read `LESSONS.md` before modifying code in any session.
+
+**Core principle:** Every mistake is an investment — but only if you record it.
+
+## Trigger
+
+`/lesson` OR `/lesson [description]` OR proactively when a mistake or gotcha is detected during work.
+
+## Announcement
+
+When using this skill, state: "Recording a lesson learned."
+
+## Awareness: Always-On Behavior
+
+This is NOT just a command — it is a standing directive:
+
+1. **Before modifying code**, read `LESSONS.md` at the project root. Treat recorded rules as hard constraints.
+2. **During work**, if you encounter any of these signals, offer to record a lesson:
+   - A bug caused by a non-obvious platform behavior (Supabase, Vercel, Next.js, etc.)
+   - A fix that took multiple attempts to get right
+   - A pattern that silently fails or produces unexpected results
+   - A deployment or environment gotcha
+   - An approach that was abandoned after significant effort
+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
+
+If the user provides a description (`/lesson [description]`), use it. Otherwise:
+- Review the current session for what went wrong or what was learned
+- Ask the user: *"What's the lesson here — what should we never do again?"*
+
+**WAIT** for user input if context is unclear.
+
+### Step 2: Format the Entry
+
+Use this exact format — no deviations:
+
+```markdown
+### [YYYY-MM-DD] Short descriptive title
+**What happened:** One or two sentences describing the problem or mistake.
+**Rule:** The actionable rule to follow going forward. Write as an imperative.
+```
+
+Rules for formatting:
+- Date is today's date
+- Title is a short phrase, not a sentence
+- "What happened" is factual — what you tried and what went wrong
+- "Rule" is a direct command — "Always...", "Never...", "Use X instead of Y"
+
+### Step 3: Append to LESSONS.md
+
+1. Read `LESSONS.md` at the project root
+2. If the file does not exist, create it with the header `# Lessons Learned`
+3. Append the new entry at the bottom of the file
+4. Confirm to the user: *"Recorded. This lesson is now active for all future sessions."*
+
+## File Format
+
+`LESSONS.md` lives at the project root. Flat, chronological, no categories.
+
+```markdown
+# Lessons Learned
+
+### [2026-02-18] RLS policies break cascade deletes
+**What happened:** Tried cascade delete on projects table, silently failed due to RLS.
+**Rule:** Always use soft deletes with RLS. Never cascade.
+
+### [2026-02-15] Vercel preview URLs break CORS
+**What happened:** OAuth failed on every preview deploy because preview URLs weren't in the CORS allowlist.
+**Rule:** Use wildcard pattern for Vercel preview branch origins in CORS config.
+```
+
+## Critical Rules
+
+- **Read before write.** ALWAYS read `LESSONS.md` before modifying project code. No exceptions.
+- **Ask before recording.** Never append a lesson without user approval.
+- **One lesson per entry.** Do not combine multiple learnings into one entry.
+- **Rules are imperatives.** Write rules as direct commands, not suggestions.
+- **No duplicates.** Before recording, check if a similar lesson already exists. If so, update it instead of creating a new one.
+- **Keep it flat.** No categories, no tags, no metadata beyond the entry format. Simplicity is the feature.
+
+## Lesson Graduation
+
+Lessons that have been proven effective across 3+ sprints become permanent agent config rules.
+
+### Graduation Criteria
+
+A lesson is a **graduation candidate** when:
+- It has been active for 3+ sprints
+- It has been triggered (prevented a recurrence) at least once
+- No bounce in the last 3 sprints matches its root cause
+
+#### Accelerated Graduation
+
+A lesson qualifies for **accelerated graduation** (after 1 sprint instead of 3) when:
+- It affected 5+ files across multiple stories, OR
+- It caused a bounce (QA or Architect failure directly attributable to the lesson's root cause), OR
+- It describes a cross-cutting concern (UI consistency, naming conventions, shared patterns) that will recur every sprint
+
+Accelerated candidates are flagged by `suggest_improvements.mjs` with impact level P1. The human still approves — the only difference is the 3-sprint waiting period is waived.
+
+### Graduation Process
+
+1. `.vbounce/scripts/suggest_improvements.mjs` flags graduation candidates in improvement suggestions
+2. Human approves graduation
+3. Lead adds the rule to the relevant agent config (`.claude/agents/developer.md`, etc.)
+4. Lead removes or archives the lesson from `LESSONS.md` with a note: `[Graduated to {agent} config on {date}]`
+5. Record in `.vbounce/improvement-log.md` under "Applied"
+
+### Why Graduation Matters
+
+`LESSONS.md` is a staging area, not a permanent rule store. Lessons that graduate become enforced constraints in the agent's core instructions — they can't be forgotten or overlooked. Lessons that stay in `LESSONS.md` are read on every session but are softer guidance. Keep `LESSONS.md` lean — stale lessons dilute the signal.

package/skills/product-graph/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: product-graph
+description: "Use when you need to understand document relationships, check what's affected by a change, find blocked documents, or assess the state of planning documents. Provides structured awareness of the full product document graph without reading every file. Auto-loaded during planning sessions."
+---
+
+# Product Graph — Document Relationship Intelligence
+
+## Purpose
+
+This skill gives you instant awareness of all product planning documents and their relationships. Instead of globbing and reading every file in `product_plans/`, you read a single JSON graph that maps every document, its status, and how it connects to other documents.
+
+## Three-Tier Loading Protocol
+
+When you need to understand the product document landscape, load information in tiers — stop at the tier that answers your question:
+
+### Tier 1: Graph JSON (~400-1000 tokens)
+Read `.vbounce/product-graph.json` for a bird's-eye view.
+- All document IDs, types, statuses, and paths
+- All edges (dependencies, parent relationships, feeds)
+- **Use when:** answering "what exists?", "what's blocked?", "what depends on X?"
+
+### Tier 2: Specific Frontmatter (~200-500 tokens per doc)
+Read the YAML frontmatter of specific documents identified in Tier 1.
+- Ambiguity scores, priorities, tags, owners, dates
+- **Use when:** you need details about specific documents (not the full set)
+
+### Tier 3: Full Documents (~500-3000 tokens per doc)
+Read the complete document body.
+- Full specs, scope boundaries, acceptance criteria, open questions
+- **Use when:** creating or modifying documents, decomposing epics, or resolving ambiguity
+
+## Edge Type Semantics
+
+| Edge Type | Meaning | Direction |
+|-----------|---------|-----------|
+| `parent` | Document is a child of another (Story → Epic) | parent → child |
+| `depends-on` | Document cannot proceed until dependency is done | dependency → dependent |
+| `unlocks` | Completing this document enables another | source → unlocked |
+| `context-source` | Document draws context from another | source → consumer |
+| `feeds` | Document contributes to a delivery/release | document → delivery |
+
+## When to Regenerate the Graph
+
+Run `vbounce graph` (or `node .vbounce/scripts/product_graph.mjs`) after:
+- **Any document edit** that changes status, dependencies, or relationships
+- **Sprint lifecycle events** (sprint init, story complete, sprint close)
+- **Planning session start** — ensure graph reflects current state
+- **Document creation or archival** — new nodes or removed nodes
+
+The graph is a cache — it's cheap to regenerate and stale data is worse than no data.
+
+## Blocked Document Detection
+
+A document is **blocked** when:
+1. It has incoming `depends-on` edges from documents with status != "Done"/"Implemented"/"Completed"
+2. It has `ambiguity: 🔴 High` and linked spikes are not Validated/Closed
+3. Its parent document has status "Parking Lot" or "Escalated"
+
+To find blocked documents:
+1. Read the graph (Tier 1)
+2. For each node, check its incoming `depends-on` edges
+3. Look up the source node's status
+4. If any source is not in a terminal state → document is blocked
+
+## Impact Analysis
+
+To understand what changes when you modify a document:
+```bash
+vbounce graph impact <DOC-ID>        # human-readable
+vbounce graph impact <DOC-ID> --json # machine-readable
+```
+
+This runs BFS traversal and returns:
+- **Direct dependents** — documents immediately affected
+- **Transitive dependents** — documents affected through cascading dependencies
+- **Upstream feeders** — documents that feed into the changed document
+
+## Graph JSON Schema
+
+```json
+{
+  "generated_at": "ISO-8601 timestamp",
+  "node_count": 5,
+  "edge_count": 12,
+  "nodes": {
+    "EPIC-002": {
+      "type": "epic|story|spike|charter|roadmap|delivery-plan|sprint-plan|risk-registry|hotfix",
+      "status": "Draft|Refinement|Ready to Bounce|Bouncing|Done|Implemented|...",
+      "ambiguity": "🔴 High|🟡 Medium|🟢 Low|null",
+      "path": "product_plans/backlog/EPIC-002_.../EPIC-002_....md",
+      "title": "Human-readable title from first heading"
+    }
+  },
+  "edges": [
+    { "from": "EPIC-002", "to": "D-02", "type": "feeds" }
+  ]
+}
+```
+
+## Keywords
+
+product graph, document graph, dependency, impact analysis, what's affected, what's blocked, document relationships, planning state