--- name: sprint-debrief description: >- Walk the user through everything that shipped in a sprint so they end up with a real, durable mental model of it — not a summary they nod along to. Reconstructs what was built from git (commits, PRs, diff), then teaches it across four lenses (product, architecture, how-to-use, operational/run-it) one chunk at a time, checking understanding before moving on and pausing for questions. Use whenever the user says the sprint/cycle/iteration is over or wraps up, asks "what did we build", "walk me through what shipped", "help me understand this sprint", "onboard me to what was done", "catch me up on the release", or wants to review/understand a body of recently-merged work as a learner rather than a reviewer. Trigger even if they don't say "sprint" — the signal is "make me understand a chunk of shipped work, in stages." Do NOT use for reviewing a single open PR for correctness (that's code review), writing new code, or explaining one isolated function. --- # Sprint Debrief The user just finished a sprint and wants to *understand* what shipped — deeply enough to hold it in their head, explain it to someone else, use it, and operate it. Your job is not to dump a summary. It's to **teach**, in stages, the way a good tutor would, until the mental model is actually in their head. Two research-backed ideas drive everything here: 1. **Understanding is built by retrieval, not by listening.** People forget a walkthrough they nodded along to. They remember what they had to explain back. So this skill teaches one chunk, then asks the user to recall it, *before* advancing. A failed recall isn't a failure — it's the signal of exactly what to re-teach. 2. **A system is understood through distinct lenses, and mixing them overwhelms.** "What is it / who's it for" (product), "how is it built" (architecture), "how do I use it" (user), and "how do I run it" (operational) are different questions. Answer one at a time, announce which one you're in, and stay there. Keep your communication in the user's house style: short, layered, plain language, no jargon dumps, and if they're working in Hebrew, keep it pure Hebrew. --- ## The shape of a debrief ``` Stage 0 Scope the sprint → what delimits it? reconstruct from git. Stage 1 Offer the format → pacing + (for complex work) a visual companion. Stage 2 Teach the four lenses → Product → Architecture → User → Operational, one chunk at a time, quizzing between chunks. Stage 3 Land it → re-narrate the whole; offer a handover artifact. ``` Don't rush to Stage 2. The reconstruction in Stage 0 is what makes the teaching accurate instead of hand-wavy. --- ## Stage 0 — Scope the sprint, then reconstruct **First, ask what delimits "the sprint."** Don't guess. Offer the common options: - a **git tag** or release (`since v2.3.0`), - a **date range** ("the last two weeks", `--since="2026-05-26"`), - a **branch** diff (`main..sprint-foo`), or - a **list of PRs / a milestone / a label**. If you're not in a git repo, say so and ask the user to point you at the repo, or to describe what shipped. **Then reconstruct what was built, reading at three altitudes** — this order matters because each altitude feeds a different lens: | Read | Altitude | Feeds | |------|----------|-------| | PR titles + descriptions (`gh pr list`, `gh pr view`) | *why* — intent | Product + Architecture | | Commit messages in order (`git log --oneline`) | *how it was built* — steps | Architecture narration | | The diff (`git diff`, `git diff --stat`) | *what literally changed* | Reference facts, runbook prereqs | Build yourself a private inventory before teaching anything: - the **features/outcomes** that shipped (for the product lens), - the **modules/services touched** and how data flows between them (architecture), - the **user-facing surfaces** — new commands, endpoints, UI (user lens), - **operational signals** — and watch for these specifically, because they mean an operational lens is *required*, not optional: new migrations, env vars, config keys, services/daemons, deploy or infra changes, feature flags, cron jobs. - new **config/params/schema** → collect into one reference table. Delegate this reconstruction to a sub-agent if the diff is large — you want the *findings* (inventory), not a head full of raw diff. Return with a structured inventory, then come back to teach. If the sprint is genuinely large, **don't try to teach all of it.** Tell the user what you found, group it into 2–4 themes, and let them pick where to start. Teaching everything badly is worse than teaching the important half well. --- ## Stage 1 — Offer the format (on startup) Once you know roughly how much shipped, offer the user how they want to go through it. Present these as a short menu, not a wall of prose: **Pacing** — pick one: - **Staged Q&A** (default) — teach one chunk, pause, you explain it back, ask questions, then continue. - **Walk + ask anytime** — narrate each lens straight through; user interrupts with questions. Lighter, less retention. - **Document, then walk** — write the handover doc first, then walk through it together. **Visual companion** — *offer this when the work is architecturally complex* (multiple services, non-trivial data flow, or an operational runbook). Tell the user you can open a local web page with visual aids — an architecture diagram, a data-flow trace, and a playbook the walkthrough follows along with — at a URL they can keep open beside the chat. If they want it, build it with the bundled template and serve it (see **Visual companion** below). Don't force it on a small, simple sprint — a two-file change doesn't need a diagram. Also, quietly **calibrate to their expertise** — and do it *per subsystem*, not per person. The user may have written the API layer themselves but never seen the new caching code. For parts they clearly know, don't narrate — pose a prediction ("given what you know, what do you think happens on a cache miss?") and confirm. For unfamiliar parts, give the full guided trace. Over-explaining familiar code actively slows an expert down; that's the expertise-reversal effect, and it's real. --- ## Stage 2 — Teach the four lenses Go in this order. It moves from *why it exists* → *how it's shaped* → *how to drive it* → *how to keep it running*, which is how understanding compounds. **Announce each lens as you enter it** ("Let's start with the product view — what this actually is and who it's for"). This is the single discipline that prevents overwhelm: never blend architecture detail into a product framing or reference facts into an explanation. ### 1. Product lens — what is it, who's it for One line per feature: *"As a ``, you can now ``, so that ``."* Frame around the problem solved and who's better off — not the code. This is the frame the user will actually retain and repeat to others. ### 2. Architecture lens — how it's built Narrate in zoom levels (this mirrors how senior engineers actually read code: hypothesis first, detail only to confirm): 1. **Context** — one sentence: the system, its users, neighboring systems. 2. **Container** — the deployable pieces and how traffic flows. 3. **Component** — zoom *only* into what the sprint touched. 4. **Data-flow trace** — the most important move: follow *one concrete request* end-to-end through the new code. "A request enters here → hits this new service → writes here → returns this." Concrete-before-abstract is what gives the boxes meaning. Spell out the glue you'd be tempted to skip. You know this code, so the "obvious" transitions are exactly the ones the user needs ("this returns a promise, so the next line awaits it — that's why ordering matters here"). Defaulting to one extra explicit step beats one fewer. ### 3. User lens — how to use it Switch to tutorial/how-to mode. Give a **guided first run** of the key new capability ("here's exactly how you'd do X with what we shipped"), then the how-to for the main goal. If there's a live surface, encourage the user to drive while you describe — doing beats watching. ### 4. Operational lens — how to run and rig it Required for any operational component flagged in Stage 0. For each, give a **mini-runbook** in fixed slots so it's scannable under pressure: > **Purpose · Prereqs/config · Start/stop/deploy · Health check (what "good" looks like) · Top 1–3 failure modes + recovery · Rollback** Then run a quick readiness check out loud: *is it monitored? does it alert? who owns it? how do we roll back?* Flag any "no" as a real gap — don't paper over it. ### Reference — keep it separate Emit new config keys, params, env vars, and schema fields as **one table**, not woven into prose. Reference facts and explanations serve different needs; mixing them helps neither. ### The per-chunk teaching loop (the heart of it) Within every lens, for each chunk (one service, one flow, one abstraction — **~4 new moving parts max**; if more, split it): 1. **Concrete anchor** — open with a runnable trace or example, not a definition. 2. **Reveal the chunk** — defer edge cases, error handling, and helper-naming until the core lands. 3. **Narrate the glue** — the "obvious" steps you'd skip. 4. **Retrieval check** — ask the user to explain it back, in their words, *before advancing*: "Without scrolling up — what does this module hand to the next, and why?" Make it recall ("explain the flow"), not recognition ("is this X or Y?"). This is also where you open the floor for their questions. 5. **Branch on the answer** — clean plain-language explanation → advance and fade your guidance. Jargon-leaning or hand-wavy → that's the gap; re-teach *that chunk*, don't push on. 6. **Re-surface earlier chunks** as they recur ("remember the auth token from the product lens? here's where it's validated"). Spaced re-encounters consolidate the model better than one exhaustive pass. Quiz gently. The goal is to surface gaps so you can fill them, not to catch the user out. If they ask you to ease off the quizzing, do — but a quick explain-back at the end of each lens is the cheapest, highest-leverage thing in this whole skill. For the framework detail behind any lens (C4, Diátaxis quadrants, runbook anatomy), read `references/four-lenses.md`. For the pedagogy detail (cognitive load, retrieval practice, expertise reversal, the expert blind spot), read `references/teaching-loop.md`. You don't need them to run a debrief — pull them in when you want depth on a specific move. --- ## Stage 3 — Land it Close by **re-narrating the whole** now that the parts have meaning — a 60-second "so, end to end, here's what this sprint did and how it hangs together." Whole → parts → whole is the arc. Then offer a **handover artifact** — a one-page document mirroring the four lenses (product / architecture / user / operational), plus an explicit **"gotchas / tacit knowledge"** section for the things not visible in any diff (the judgment calls, the sharp edges, the "don't touch X before Y"). This is what survives after the conversation scrolls away. --- ## Visual companion (optional, for complex work) When the user wants the visual aid, generate a single self-contained HTML page from the bundled template and serve it locally. 1. Read `assets/companion_template.html`. It has three tabbed sections — **Architecture**, **Data flow**, **Playbook** — using Mermaid for diagrams and styled blocks for the runbook. Placeholders: `__TITLE__`, `__ARCHITECTURE_MERMAID__`, `__DATAFLOW_MERMAID__`, `__PLAYBOOK_HTML__`, `__OVERVIEW_HTML__`. 2. Fill the placeholders from your Stage 0 inventory: - **Architecture** — a Mermaid `graph` of the containers/components the sprint touched. - **Data flow** — a Mermaid `sequenceDiagram` of the one concrete request you trace in the architecture lens. - **Playbook** — the operational mini-runbooks as styled steps. 3. Write the filled file to a temp path and serve it (run from the skill directory, or use the script's absolute path): ```bash python3 scripts/serve_companion.py ``` It prints a `http://localhost:` URL and opens the browser. Give the user the URL and tell them to keep it open beside the chat — **the walkthrough then follows the page**: when you enter the architecture lens, point at the Architecture tab; when you trace a request, point at the Data flow tab; for the operational lens, the Playbook tab. Keep the page in sync with where you are in the walkthrough — its value is that the user sees the structure while you narrate it, instead of holding it all in working memory. --- ## A note on doing this well You also "know" the code you're teaching, which makes it tempting to skip ahead — the same expert blind spot a human author has. Resist it. The user asked to *understand*, and understanding is slower than summarizing. Read their signals: repeated questions, slow or wrong recalls, "wait, go back" — every one is a cue to slow down and surface a step you skipped, not to push forward. One extra explicit step is almost never the wrong call here.