mandrel 1.93.0 → 2.0.0

package/.agents/skills/core/incremental-implementation/SKILL.md

@@ -1,271 +0,0 @@
----
-name: incremental-implementation
-description:
-  Delivers changes incrementally. Use when implementing any feature or change
-  that touches more than one file. Use when you're about to write a large amount
-  of code at once, or when a task feels too big to land in one step.
----
-
-# Incremental Implementation
-
-## Policy Capsule
-
-- Deliver in thin vertical slices: **Implement → Test → Verify → Commit → Next slice**. Never write more than ~100 lines before testing.
-- Each slice MUST leave the system in a working, testable state — build green, existing tests pass, type-check and lint clean.
-- Each commit changes one logical thing; never mix refactors with features or formatting with behavior.
-- Apply Simplicity First: write the naive, obviously-correct version. Three similar lines beats a premature abstraction; do not build for hypothetical future requirements.
-- Enforce Scope Discipline: touch only what the task requires. No drive-by cleanups, import re-orderings, comment deletions, or syntax modernizations in files you're "just reading" — note them instead.
-- Gate incomplete work behind a feature flag rather than holding a long-lived branch; default new behaviour to safe / opt-in.
-- Keep increments rollback-friendly: prefer additive changes, ship DB migrations with rollbacks, and never delete + replace in the same commit.
-- Prefer vertical slices that deliver end-to-end functionality; use contract-first slicing only when backend/frontend must develop in parallel, and risk-first slicing when the riskiest piece dominates the plan.
-- Verify the increment checklist before moving on: tests pass, build succeeds, types check, lint clean, change committed with a descriptive message.
-
-## Overview
-
-Build in thin vertical slices — implement one piece, test it, verify it, then
-expand. Avoid implementing an entire feature in one pass. Each increment should
-leave the system in a working, testable state. This is the execution discipline
-that makes large features manageable.
-
-## When to Use
-
-- Implementing any multi-file change
-- Building a new feature from a task breakdown
-- Refactoring existing code
-- Any time you're tempted to write more than ~100 lines before testing
-
-**When NOT to use:** Single-file, single-function changes where the scope is
-already minimal.
-
-## The Increment Cycle
-
-```text
-┌──────────────────────────────────────┐
-│                                      │
-│   Implement ──→ Test ──→ Verify ──┐  │
-│       ▲                           │  │
-│       └───── Commit ◄─────────────┘  │
-│              │                       │
-│              ▼                       │
-│          Next slice                  │
-│                                      │
-└──────────────────────────────────────┘
-```
-
-For each slice:
-
-1. **Implement** the smallest complete piece of functionality
-2. **Test** — run the test suite (or write a test if none exists)
-3. **Verify** — confirm the slice works as expected (tests pass, build succeeds,
-   manual check)
-4. **Commit** -- save your progress with a descriptive message (see
-   `git-workflow-and-versioning` for atomic commit guidance)
-5. **Move to the next slice** — carry forward, don't restart
-
-## Slicing Strategies
-
-### Vertical Slices (Preferred)
-
-Build one complete path through the stack:
-
-```text
-Slice 1: Create a task (DB + API + basic UI)
-    → Tests pass, user can create a task via the UI
-
-Slice 2: List tasks (query + API + UI)
-    → Tests pass, user can see their tasks
-
-Slice 3: Edit a task (update + API + UI)
-    → Tests pass, user can modify tasks
-
-Slice 4: Delete a task (delete + API + UI + confirmation)
-    → Tests pass, full CRUD complete
-```
-
-Each slice delivers working end-to-end functionality.
-
-### Contract-First Slicing
-
-When backend and frontend need to develop in parallel:
-
-```text
-Slice 0: Define the API contract (types, interfaces, OpenAPI spec)
-Slice 1a: Implement backend against the contract + API tests
-Slice 1b: Implement frontend against mock data matching the contract
-Slice 2: Integrate and test end-to-end
-```
-
-### Risk-First Slicing
-
-Tackle the riskiest or most uncertain piece first:
-
-```text
-Slice 1: Prove the WebSocket connection works (highest risk)
-Slice 2: Build real-time task updates on the proven connection
-Slice 3: Add offline support and reconnection
-```
-
-If Slice 1 fails, you discover it before investing in Slices 2 and 3.
-
-## Implementation Rules
-
-### Rule 0: Simplicity First
-
-Before writing any code, ask: "What is the simplest thing that could work?"
-
-After writing code, review it against these checks:
-
-- Can this be done in fewer lines?
-- Are these abstractions earning their complexity?
-- Would a staff engineer look at this and say "why didn't you just..."?
-- Am I building for hypothetical future requirements, or the current task?
-
-```text
-SIMPLICITY CHECK:
-✗ Generic EventBus with middleware pipeline for one notification
-✓ Simple function call
-
-✗ Abstract factory pattern for two similar components
-✓ Two straightforward components with shared utilities
-
-✗ Config-driven form builder for three forms
-✓ Three form components
-```
-
-Three similar lines of code is better than a premature abstraction. Implement
-the naive, obviously-correct version first. Optimize only after correctness is
-proven with tests.
-
-### Rule 0.5: Scope Discipline
-
-Touch only what the task requires.
-
-Do NOT:
-
-- "Clean up" code adjacent to your change
-- Refactor imports in files you're not modifying
-- Remove comments you don't fully understand
-- Add features not in the spec because they "seem useful"
-- Modernize syntax in files you're only reading
-
-If you notice something worth improving outside your task scope, note it — don't
-fix it:
-
-```text
-NOTICED BUT NOT TOUCHING:
-- src/utils/format.ts has an unused import (unrelated to this task)
-- The auth middleware could use better error messages (separate task)
-→ Want me to create tasks for these?
-```
-
-### Rule 1: One Thing at a Time
-
-Each increment changes one logical thing. Don't mix concerns:
-
-**Bad:** One commit that adds a new component, refactors an existing one, and
-updates the build config.
-
-**Good:** Three separate commits — one for each change.
-
-### Rule 2: Keep It Compilable
-
-After each increment, the project must build and existing tests must pass. Don't
-leave the codebase in a broken state between slices.
-
-### Rule 3: Feature Flags for Incomplete Features
-
-If a feature isn't ready for users but you need to merge increments:
-
-```typescript
-// Feature flag for work-in-progress
-const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';
-
-if (ENABLE_TASK_SHARING) {
-  // New sharing UI
-}
-```
-
-This lets you merge small increments to the main branch without exposing
-incomplete work.
-
-### Rule 4: Safe Defaults
-
-New code should default to safe, conservative behavior:
-
-```typescript
-// Safe: disabled by default, opt-in
-export function createTask(data: TaskInput, options?: { notify?: boolean }) {
-  const shouldNotify = options?.notify ?? false;
-  // ...
-}
-```
-
-### Rule 5: Rollback-Friendly
-
-Each increment should be independently revertable:
-
-- Additive changes (new files, new functions) are easy to revert
-- Modifications to existing code should be minimal and focused
-- Database migrations should have corresponding rollback migrations
-- Avoid deleting something in one commit and replacing it in the same commit —
-  separate them
-
-## Working with Agents
-
-When directing an agent to implement incrementally:
-
-```text
-"Let's implement Task 3 from the plan.
-
-Start with just the database schema change and the API endpoint.
-Don't touch the UI yet — we'll do that in the next increment.
-
-After implementing, run `npm test` and `npm run build` to verify
-nothing is broken."
-```
-
-Be explicit about what's in scope and what's NOT in scope for each increment.
-
-## Increment Checklist
-
-After each increment, verify:
-
-- [ ] The change does one thing and does it completely
-- [ ] All existing tests still pass (`npm test`)
-- [ ] The build succeeds (`npm run build`)
-- [ ] Type checking passes (`npx tsc --noEmit`)
-- [ ] Linting passes (`npm run lint`)
-- [ ] The new functionality works as expected
-- [ ] The change is committed with a descriptive message
-
-## Common Rationalizations
-
-| Rationalization                                    | Reality                                                                                           |
-| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| "I'll test it all at the end"                      | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice.                          |
-| "It's faster to do it all at once"                 | It _feels_ faster until something breaks and you can't find which of 500 changed lines caused it. |
-| "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful.                       |
-| "I'll add the feature flag later"                  | If the feature isn't complete, it shouldn't be user-visible. Add the flag now.                    |
-| "This refactor is small enough to include"         | Refactors mixed with features make both harder to review and debug. Separate them.                |
-
-## Red Flags
-
-- More than 100 lines of code written without running tests
-- Multiple unrelated changes in a single increment
-- "Let me just quickly add this too" scope expansion
-- Skipping the test/verify step to move faster
-- Build or tests broken between increments
-- Large uncommitted changes accumulating
-- Building abstractions before the third use case demands it
-- Touching files outside the task scope "while I'm here"
-- Creating new utility files for one-time operations
-
-## Verification
-
-After completing all increments for a task:
-
-- [ ] Each increment was individually tested and committed
-- [ ] The full test suite passes
-- [ ] The build is clean
-- [ ] The feature works end-to-end as specified
-- [ ] No uncommitted changes remain

package/.agents/skills/core/introducing-a-baseline-gate/SKILL.md

@@ -1,213 +0,0 @@
----
-name: introducing-a-baseline-gate
-description:
-  Land a new CI check that asserts on a body of pre-existing state
-  (doc-drift, lint-vocabulary, dependency-cycle, missing-test-coverage,
-  unused-export). Use when introducing a gate whose first run would
-  surface latent findings — the introducing Story MUST guarantee the
-  gate exits 0 at merge, not just that the cited discrepancies pass.
----
-
-# Skill: Introducing a Baseline-Style Gate
-
-## Policy Capsule
-
-- A new check that asserts on pre-existing state MUST exit 0 at merge time. Wiring the gate into CI without proving it's green ships a red gate that blocks every downstream Story.
-- "The cited discrepancies are fixed" is **not** the AC. The AC is **"the gate exits 0 against the full repository on the merge commit"** — write it in the Story body in those words.
-- Choose one of two landing shapes before you write the AC: **advisory-first** (gate exits 0 with warnings; a follow-up Story flips it to blocking) or **populate-the-baseline** (the introducing Story fixes every existing finding in the same PR, or writes them to an ignore-list / baseline snapshot the gate respects).
-- Run the gate against `main` (or `epic/<id>`) **before** writing the AC. The findings count it surfaces is the scope of what landing-green will cost.
-- Wire the gate into `.agentrc.json` `github.branchProtection.requiredChecks` in the **same PR** that ships the gate's first green run — never split "add the check script" from "make it required".
-- Never land a gate red and rely on a follow-up Story to populate the baseline. The window between merge and the follow-up landing blocks every Story in flight.
-
-## When to reach for this
-
-Reach for this skill whenever you're introducing a check whose **first
-run on the existing codebase would surface findings you didn't author**.
-That includes (but is not limited to):
-
-- **Doc-drift gates** — `check-lifecycle-doc-drift.js`, "docs/X.md must
-  enumerate every Y in `src/Y/`", "README badge list must match the CI
-  workflow file list".
-- **Lint-vocabulary gates** — "no `TODO` without an issue link", "every
-  exported function must have a JSDoc summary", "every `agent::*` label
-  must appear in `label-constants.js`".
-- **Dependency-cycle / boundary gates** — "no import from `app/` into
-  `lib/`", "no cycle in module graph", "every workspace dep declared at
-  the right `package.json` level".
-- **Coverage-shape gates** — "every public API surface in
-  `tests/contract/**` has at least one negative-path test", "every
-  feature flag defined in `flags.ts` is referenced".
-- **Baseline-numeric gates** — Lighthouse / bundle-size / CRAP first
-  introduction. (For the numeric-ratchet shape specifically, also read
-  `stack/qa/lighthouse-baseline`.)
-
-If the check only fires on **new** code (e.g. a lint rule wired with
-`--cache` against the diff, or a hook scoped to staged files), this
-skill is not required — there's no latent-state landmine.
-
-## The Trap (Why This Skill Exists)
-
-**Epic #2880, Wave 1.** Story #2895 introduced
-`check-lifecycle-doc-drift.js` — a gate that asserts every entry in the
-project's lifecycle event registry has a matching row in
-`docs/LIFECYCLE.md`. The Story's AC required correcting 3 cited
-discrepancies and adding 2 new event rows. The gate landed wired into
-CI. The first CI run on the **next** Story (#2898) reported **11
-pre-existing drift findings** — drift that had been latent for months,
-silent because no gate enforced it.
-
-Stories #2898 and #2900 were both blocked. A hotfix commit on
-`epic/2880` (5e3ef962) had to populate the full listener table before
-wave 1 could merge. The cost was a half-day of wave-1 wall-clock and
-two interrupted Stories.
-
-**The diagnosis:** the introducing Story's AC was scoped to "fix what
-we cited", not "the gate is green". Those are different ACs. The
-second one is the load-bearing one.
-
-This skill exists so the next drift-style gate doesn't replay that
-pattern.
-
-## Two Landing Shapes — Pick One Before AC Authoring
-
-### Shape A: Advisory-First (exit 0 + warnings)
-
-Land the gate as **non-blocking** in the introducing Story. The script
-exits 0 even when findings exist, but prints them as warnings (and
-optionally posts them as a PR comment). A follow-up Story drives the
-findings count to zero, then flips the gate to blocking
-(`process.exit(1)` on finding-count > 0) and adds it to
-`requiredChecks`.
-
-**When to choose this shape:**
-
-- The existing-state findings are numerous (10+) and a one-shot fix
-  would balloon the introducing Story's scope.
-- The findings need per-finding owner triage (each row is a different
-  module's bug).
-- You want the warnings to surface in PRs immediately so contributors
-  can fix-as-they-touch.
-
-**Required AC line:**
-
-> "The gate runs in advisory mode (exits 0 with warnings on the full
-> repo). The follow-up Story #<NNN> flips it to blocking."
-
-The follow-up Story MUST exist as a real ticket on the board before the
-introducing Story closes — otherwise "follow-up" is a euphemism for
-"never".
-
-### Shape B: Populate-the-Baseline (exit 0 from day one)
-
-The introducing Story includes the work to drive existing findings to
-zero. Two sub-shapes:
-
-1. **Fix-them-all.** Edit the docs / add the missing tests / break the
-   cycles. The PR diff includes the gate code **and** the
-   findings-resolution diff. The first CI run is green.
-2. **Snapshot-as-baseline.** Write the current findings to a committed
-   ignore-list (`baselines/<gate>-ignore.json`) that the gate reads at
-   startup. The gate exits 0 when the only failures are in the ignore
-   list, and exits non-zero on any **new** finding. A follow-up Story
-   shrinks the ignore list to empty.
-
-**When to choose this shape:**
-
-- The findings count is small (≤ 10) and tractable in one PR.
-- Or: the findings reflect real bugs that should be fixed, not papered
-  over.
-- Or: an ignore-list snapshot is a meaningful artifact (it answers
-  "what's our drift debt right now?").
-
-**Required AC line:**
-
-> "On the merge commit, `<gate-script>` exits 0 against the full
-> repository. The gate is wired into `requiredChecks` in this PR."
-
-## Pre-Authoring Step: Run the Gate Against `main`
-
-**Before** writing the AC, run the gate script against `main` (or
-`epic/<id>`) locally and count the findings.
-
-```bash
-# In the introducing Story's worktree, with the gate script written:
-node .agents/scripts/<new-gate>.js
-echo "exit=$?"
-```
-
-That number — the **pre-existing finding count** — is the budget the
-Story is choosing to spend. Write it in the Story body:
-
-```text
-## Pre-existing finding count (as of <SHA>)
-- N findings on main / epic/<id>
-- Landing shape: <Advisory-First | Populate-the-Baseline:fix |
-  Populate-the-Baseline:snapshot>
-```
-
-If you skip this step you are gambling that the count is zero. It
-isn't, that's why you're adding the gate.
-
-## AC Checklist for a Drift-Style Gate Story
-
-Copy this checklist into the Story body. Every line MUST appear:
-
-- [ ] The gate script (`<path>`) exists and runs locally.
-- [ ] The pre-existing finding count on `<base-branch>` is documented
-      in the Story body.
-- [ ] The landing shape (Advisory-First / Populate-fix /
-      Populate-snapshot) is named in the Story body.
-- [ ] If Advisory-First: the follow-up Story (#<NNN>) exists on the
-      board with `type::story` and a link from this Story.
-- [ ] On the merge commit, the gate exits 0 against the full
-      repository (logs attached to the close comment).
-- [ ] The gate is wired into `.agentrc.json`
-      `github.branchProtection.requiredChecks` (Populate-shape) **or**
-      explicitly marked advisory (Advisory-First).
-- [ ] CI on the introducing PR shows the gate green.
-
-## Anti-patterns
-
-- **"The AC just says fix the cited cases."** The cited cases are the
-  spark that surfaced the need for the gate. The AC must cover the
-  whole forest, not just the tree the operator was standing under.
-- **"We'll wire it in now and clean up the drift in a follow-up."**
-  Every Story merged between "wire in" and "clean up" is blocked.
-  That's a wave-stopper, not a follow-up. Either populate-now or
-  advisory-now — never blocking-now-with-debt.
-- **"It's green locally, ship it."** Local environments routinely have
-  uncommitted state that the gate accepts. Verify against the **base
-  branch tip**, not `git status`-clean working tree.
-- **"The hotfix commit on the integration branch counts as cleanup."**
-  It counts as a Story-2895-class debt: the gate is green on
-  `epic/<id>` only because someone manually populated the gap.
-  Codify the populate work as scope of the introducing Story instead.
-- **No follow-up Story for Advisory-First.** "Advisory forever" means
-  the gate is decoration. Either commit to flipping it or don't ship
-  the advisory version.
-
-## Cross-references
-
-- **`stack/qa/lighthouse-baseline`** — for the **numeric-ratchet**
-  flavour of baseline gate (a number with a tolerance band that
-  ratchets only with intent). That skill's `--self-test` and
-  weekly-cadence patterns complement this one's landing-shape
-  patterns; the two skills cover orthogonal concerns (number-shape
-  vs. land-green).
-- **`core/baseline-refresh`** — once the gate exists and is blocking,
-  this skill governs how an intentional drift in the baseline is
-  refreshed without bypassing the gate.
-- **`core/ci-cd-and-automation`** — generic CI-pipeline conventions
-  (gate ordering, no-skip rule, branch-protection wiring) that this
-  skill specialises for the latent-state case.
-- **`.agents/rules/git-conventions.md` § Contract Cutovers** — a
-  drift-style gate is itself a contract cutover (the contract is "the
-  artifact and the source agree"). The hard-cutover policy applies:
-  land green in one PR, don't ship two-shape tolerance.
-- **Source incident:** Epic #2880 friction note **F-W1-1**
-  (LIFECYCLE.md drift exposure), hotfix
-  [`5e3ef962`](https://github.com/dsj1984/mandrel/commit/5e3ef962),
-  Stories
-  [#2895](https://github.com/dsj1984/mandrel/issues/2895),
-  [#2898](https://github.com/dsj1984/mandrel/issues/2898),
-  [#2900](https://github.com/dsj1984/mandrel/issues/2900).

package/.agents/skills/core/knowledge-transfer/SKILL.md

@@ -1,180 +0,0 @@
----
-name: knowledge-transfer
-description:
-  Verifies that a human operator actually understands a plan or a code change
-  through restate-first probing, a why-ladder, incremental mastery gates, and a
-  persistent comprehension checklist. Use "explain", "walk me through", "help
-  me understand", "teach me this change/plan", or "do I understand this?" to
-  trigger. Operator-facing and interactive only.
----
-
-# Knowledge Transfer
-
-## Policy Capsule
-
-- **Restate-first, always.** Open every layer by asking the operator to
-  state their current understanding **before** you explain anything. You
-  are filling gaps in their model, not lecturing from a blank slate. Never
-  lead with the answer.
-- **Confirm mastery before advancing.** Walk the why-ladder one layer at a
-  time and verify comprehension of the current layer (high-level *and*
-  low-level) before moving to the next. Do not dump the whole picture at the
-  end.
-- **The operator can stop at any point.** Every checkpoint MUST offer an
-  explicit exit ("I'm good — proceed"). When the operator takes it, stop
-  immediately and hand back. This is a comprehension *aid*, never a gate
-  that traps the operator. This deliberately overrides any "do not end
-  until verified" framing — operator control wins.
-- **Drive the why-ladder in order:** problem → why the problem existed →
-  branches considered → chosen solution → design decisions → edge cases →
-  broader impact / blast radius. Drill into *why* repeatedly; cover *what*
-  and *how* alongside it.
-- **Keep a persistent checklist artifact.** Write a running markdown
-  checklist to `temp/comprehension-<subject>.md` and update it incrementally
-  as each item is mastered — so even a skipped or interrupted session leaves
-  a readable summary. Artifacts over chat.
-- **Adapt depth on request.** Support ELI5 (explain like I'm five), intern
-  (explain like I'm a new engineer), and peer (explain like I'm a colleague)
-  levels; switch when the operator asks.
-- **Quiz with the host's structured-question mechanism when it sharpens
-  understanding.** Randomize the position of the correct answer, ask one
-  focused question at a time, and do not reveal the answer until the
-  operator has submitted. Quizzing is optional — gate it behind the
-  operator's appetite, never force it.
-- **Interactive only.** This skill MUST NOT run inside a non-interactive
-  delivery sub-agent (`helpers/single-story-deliver`,
-  `helpers/epic-deliver-story`, or any headless parent). There is no
-  operator to teach; skip it entirely.
-- **Be honest, not flattering.** If the operator's restatement is wrong,
-  say so plainly and correct it. A false "you've got it" defeats the
-  purpose.
-
-## What this skill is for
-
-Mandrel drives autonomous delivery: agents plan an Epic and then write and
-merge code the operator merges through the GitHub UI. That leaves two moments
-where the operator may not actually understand what they are authorizing or
-what they now own:
-
-1. **Before delivery** — does the operator understand the **plan** (the Tech
-   Spec, the decomposition, the wave roadmap, the risk) before authorizing a
-   fan-out of subagents?
-2. **After delivery** — does the operator understand the **realized change**
-   (the diff, the design decisions, the edge cases) they just merged?
-
-This skill is the reusable comprehension engine for both. The *subject*
-differs (a plan vs. a diff); the *method* is identical.
-
-## The subject
-
-Before starting, identify the comprehension subject and gather it:
-
-- **A plan** — the Epic body (whose managed sections carry the folded Tech
-  Spec and Acceptance Table), the
-  decomposition (Stories with inline `acceptance[]` / `verify[]`),
-  and the dispatch/wave roadmap.
-- **A change** — a PR, a branch, or a working-tree diff. Read the diff, the
-  PR/issue description, and the surrounding code the change touches.
-
-Ground every explanation in the actual artifact. Do not generalize from the
-title — read the real content first (`Glob` / `Grep` / `Read`, `gh pr view`,
-`git diff`).
-
-## The loop
-
-1. **Frame & gather.** State the subject in one sentence and load it. Write
-   the initial checklist to `temp/comprehension-<subject>.md` with one
-   unchecked item per why-ladder layer.
-2. **Restate-first.** Ask the operator to explain, in their own words, what
-   they currently understand about the subject. Listen for the gaps — this
-   sets where you start.
-3. **Fill gaps, one layer at a time.** For each why-ladder layer the operator
-   has not mastered:
-   - Explain at the requested depth, grounded in the artifact (show the code,
-     the spec section, or the diff hunk).
-   - Probe understanding: a short open question, or a quiz item via the host's
-     structured-question mechanism.
-   - Mark the checklist item only when the operator demonstrates
-     understanding — not when you have merely explained it.
-   - Offer the stop exit before moving on.
-4. **Cover both altitudes.** High-level (motivation, why it matters, what it
-   impacts) and low-level (business logic, specific edge cases). A confident
-   high-level summary with no grasp of the edge cases is not mastery.
-5. **Close.** When every checklist item is mastered — or the operator stops —
-   summarize what was covered, note any unchecked items, and leave the
-   checklist artifact in place.
-
-## The why-ladder (comprehension checklist)
-
-The default checklist. Adapt the wording to the subject; keep the
-progression.
-
-- [ ] **The problem** — what is being solved, in one sentence.
-- [ ] **Why the problem existed** — the root cause or the gap, not just the
-      symptom.
-- [ ] **The branches** — what alternatives were considered and set aside.
-- [ ] **The solution** — what was chosen (the plan, or the realized change).
-- [ ] **Why this solution** — the reasoning that selected it over the
-      branches.
-- [ ] **Design decisions** — the specific choices inside the solution and
-      their trade-offs.
-- [ ] **Edge cases** — the boundaries, failure modes, and what is explicitly
-      *not* handled.
-- [ ] **Broader impact** — the blast radius: what this affects downstream,
-      who is impacted, what to watch.
-
-## Depth levels
-
-- **ELI5** — plain-language analogy, no jargon. For orienting before detail.
-- **Intern** — assumes general engineering literacy, explains the
-  project-specific context and conventions.
-- **Peer** — assumes domain fluency; focuses on the non-obvious decisions and
-  trade-offs.
-
-Default to *intern* and adjust when the operator's restatement or an explicit
-request tells you to go shallower or deeper.
-
-## Quizzing
-
-When a quick check would sharpen understanding, pose a question through the
-host's structured-question mechanism. In Claude Code the reference
-implementation is the `AskUserQuestion` tool; on another host, use that
-host's equivalent structured-choice surface.
-
-- Ask **one** question at a time.
-- For multiple-choice, **randomize** which option is correct across questions.
-- Do **not** reveal or hint at the answer until the operator submits.
-- Follow a wrong answer with a targeted re-explanation of just that gap, then
-  re-probe — do not move on.
-
-## Activation
-
-This skill is the engine behind two operator-facing entry points:
-
-- **An ad-hoc conversational walkthrough** of a realized change (a PR,
-  branch, or diff) — the host's native mode. Read this skill and run the
-  loop directly when the operator asks to be walked through a change.
-  (The former `/explain` workflow wrapper was retired in #4482.)
-- **A post-plan backlog walkthrough** — run the loop over a freshly planned
-  backlog (the Epic body's Tech Spec sections, the Stories, the wave table)
-  before the operator hands off to `/deliver`. Offer it by LM judgment on
-  non-trivial plans; it is no longer a wired phase of
-  [`/plan`](../../../workflows/helpers/plan-epic.md) (the comprehension gate
-  was unwired from the pipeline in Epic #4474), always advisory, and never
-  blocks the hand-off.
-
-It is discovered through the standard skill-activation contract in
-[`.agents/instructions.md` § 1.B](../../../instructions.md) — no separate
-always-on directive is required.
-
-## Constraints
-
-- **Never** run in a non-interactive / headless delivery sub-agent.
-- **Never** advance past a checklist item the operator has not demonstrated
-  understanding of (unless they explicitly stop).
-- **Never** reveal a quiz answer before submission, and never keep the
-  correct choice in a fixed position across questions.
-- **Always** offer an explicit "proceed / stop" exit at every checkpoint.
-- **Always** ground explanations in the real artifact, not the title.
-- **Always** leave the `temp/comprehension-<subject>.md` checklist in place
-  on exit.