explain-work — review coupled with "explain this to me"

Take one unit of work and explain it at the altitude the available context justifies. The value is not new analysis — it is composing analysis you already produce (structural, ownership, intent) and teaching it. This is a generic skill: it contains no personal or org-specific data. All situated context is read at runtime from sources below, so the skill stays shareable and PII-free.

Output is local only. Post nothing, edit nothing.

Arguments

$ARGUMENTS — <PR number, owner/repo#N, LINEAR-ID, or path> [--deep]

• The target resolves to a PR, a Linear ticket, or a path/diff (auto-detected).
• --deep runs the full review-lens panel (see Step 4). Default is a light pass.

Step 0 — Check for prior session context

Before fetching anything, check whether the current session already contains analysis of the same target. If a pr-review-kit, pr-review, or review-prep pass was just run in this session for the same PR/path, reuse that context rather than re-fetching. The layers that are already materialised (file reads, commit history, inline comment triage, matrix rows) should be treated as the hard layer from Step 2 — no need to repeat the gh calls or worktree setup.

Signal that session context was reused in the degradation report (Step 6) so the user knows the explanation was built from the live analysis, not a cold fetch.

Step 1 — Resolve the unit of work and authorship

1. Detect the input type: PR number / owner/repo#N → a PR; [A-Z]+-\d+ → a Linear ticket; otherwise a path or the current diff.
2. Determine authorship: is this the user's own work or a peer's? For a PR, compare the PR author to the active gh login (gh api user --jq .login). For a ticket, check the assignee / linked PR author. Authorship sets the teaching emphasis (Step 5).

Step 2 — Assemble context layers (use what is reachable; degrade gracefully)

Each layer is a seam: present it when the source is available, skip it silently when it is not. Never block on a missing layer. Track each layer's outcome (reached / partial / skipped + reason) for the degradation report in Step 6.

• Code / structural — run review-prep (spec + emergent diagrams + impact) for a PR/diff, or read the files directly for a path. This is the hard layer.
• Boundaries / dependencies — run seam-discovery on the touched project(s) to map what this work depends on and what depends on it.
• Team ownership — read the repo CODEOWNERS; map the touched paths to owning team(s) ("who owns this / who will review it").
• Intent — for a Linear ticket (or a PR's linked ticket), pull the ticket body / design / acceptance criteria so the explanation is anchored to intent, not just code.
• Situated identity (optional, never required) — read the user's native context if present: ~/.claude/rules/identity.md, user-level ~/.claude/rules/*.md, and auto-memory (MEMORY.md). Also derive a lightweight identity signal from the user's recent commits and the CODEOWNERS teams of the paths they touch. If a richer observational source is available (e.g. an observational-memory MCP query for recent work / intersecting teams, if your harness provides one), use it.

Step 3 — Reconcile authored vs derived identity

If both an authored identity (Step 2) and a derived signal exist and they meaningfully diverge — e.g. the authored team/project does not match the CODEOWNERS teams of the user's recent work — surface it with one AskUserQuestion before explaining ("your profile says project Y, but your recent commits are in project Z — which lens for this?"). Do not nag on minor or ambiguous differences; only ask when the divergence would change the altitude of the explanation.

Step 4 — Review

• Default (light): the structural + ownership + intent context from Step 2 is enough to explain most work. Note what is notable / risky inline; do not run a full agent panel.
• --deep: run the full review-lens panel (delegate to pr-review-kit discipline / parallel analysis agents) and fold confirmed findings into the teaching. Use when the user is reviewing a substantial peer PR and wants the findings, not just the shape.

Step 5 — Teach (the point of the skill)

Synthesize the layers into an explanation, not a report. For each notable thing, give the why, not just the what — tie a finding or design choice to the seam / ownership / intent that makes it make sense ("this touches the auth seam your team co-owns with X, which is why the validation order matters here").

Shift emphasis by authorship (Step 1):

• The user's own work → domain-onboarding: the design, the AC, the trade-offs and the parts a reviewer will probe — so they can defend it.
• A peer's work → findings-teaching: the concept behind each finding and how to recognize it next time.

Nothing here is posted, but each finding inside the teaching is still written as if it were — tagged, cited, and framed the same way — so the user can lift one into a review comment without rewriting it, and so a [Question] never reads as a verdict just because it was never sent:

Every finding carries a severity tag whose merge impact is explicit, so the author never has to guess whether a comment is a gate or a thought:

Lead with the TL;DR in plain language, before any detail: what you found, whether it blocks, and what you would do. Burying the verdict under three paragraphs of trace makes the author read the whole comment to learn it was a nit.

Frame findings as questions rather than commands — "It looks like X — would it be worth considering Y?" rather than "You should do X." The imperative is only honest when you are certain, and you are certain less often than you feel; the question costs the same characters and leaves the author room to answer "no, because…" without it reading as defiance.

Every finding cites evidence: a file:line, another PR, a ticket, a doc URL, or the output of an experiment you actually ran. A finding with no citation is an opinion wearing a severity tag.

Never flag style, formatting, or naming. The formatter and the linter own those. A review that spends its first three comments there teaches the author to skim the rest of it.

Match the tone to the author. Someone senior in this code wants the mechanism and nothing around it; someone newer needs the why and a pointer to the pattern the codebase already uses. The finding is identical either way — only the scaffolding changes.

Scale to the context available: sparse context yields a solid code + findings explanation; rich context (ownership + intent + identity) yields a situated one.

Step 6 — Degradation report (always emit, even when everything worked)

After the teaching output, append a compact block showing what context was actually available. This lets the user calibrate how much to trust the explanation and where to dig deeper themselves.

Format:

---
**Context used for this explanation**

| Layer | Status | Notes |
|---|---|---|
| Code / structural | ✅ reached (session reuse) | pr-review-kit pass earlier this session |
| Seam / boundaries | ❌ skipped | seam-discovery not available |
| Team ownership | ✅ reached | CODEOWNERS: @org/team-name |
| Intent / ticket | ⚠️ partial | PR body only; no linked Linear ticket |
| Situated identity | ❌ skipped | no identity.md or memory present |

Status values:

• ✅ reached — full data available and used
• ✅ reached (session reuse) — used prior-session analysis, no re-fetch
• ⚠️ partial — some data available; note what was missing
• ❌ skipped — not available; note why (tool not connected, file absent, etc.)

Keep notes brief — one clause each. The block is a signal, not a diagnosis. Do not omit the block when everything worked; a clean all-✅ table is itself useful signal that the explanation is built on solid ground.

Posture

• Local / explain only. Post nothing to GitHub, edit no files. (For posting a review, hand off to pr-review.)
• The skill carries no personal or org-specific data. Identity and org context live in the user's native rules / memory and are read at runtime, so the skill remains generic and shareable.