# Explain Work

> Review a PR, ticket, or path and explain it so it sticks — mache/CODEOWNERS/ ticket context synthesized into a taught explanation, not a bare findings list. Own work gets onboarding framing; a peer's gets findings-teaching. Not for posting reviews (pr-review) or the reviewer-only pre-flight alone (review-prep). Local only.

- Skill: `jamestexas/explain-work` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jamestexas/explain-work`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jamestexas/explain-work/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jamestexas (https://skillmd.com/u/jamestexas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jamestexas/explain-work

---


# 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.

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.