Get back into the flow of a session in one glance. A read-only ORIENTATION report — not what-did-we-do-and-was-it-good (that's /summarize) but where do things stand RIGHT NOW: what work was done, where the branch is (git), where the ticket stands (Linear), what's blocked on YOUR decision, and what's next. The orchestrator writes its own live bearings, then a subagent scans the raw transcript JSONL (dropping read-noise, KEEPING every decision/state-bearing call — AskUserQuestion, Skill/Task, plan-accept, commit/ticket/PR), reconstructs the state BLIND, flags stale narrative artifacts, and reconciles against the bearings, transcript-authoritative. Reuses /graph to render the work trajectory (only when it actually branches) — phases, divergences, snapshots, milestones, plan completion, where you are now, what's upcoming — then walks you through every open thread. Saved to builds/ by default; degrades gracefully (no ticket/plan/thin transcript → report whatever exists). Dual audience: a human returning cold, and
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Get back into the flow of a session in one glance. A read-only ORIENTATION report — not what-did-we-do-and-was-it-good (that's /summarize) but where do things stand RIGHT NOW: what work was done, where the branch is (git), where the ticket stands (Linear), what's blocked on YOUR decision, and what's next. The orchestrator writes its own live bearings, then a subagent scans the raw transcript JSONL (dropping read-noise, KEEPING every decision/state-bearing call — AskUserQuestion, Skill/Task, plan-accept, commit/ticket/PR), reconstructs the state BLIND, flags stale narrative artifacts, and reconciles against the bearings, transcript-authoritative. Reuses /graph to render the work trajectory (only when it actually branches) — phases, divergences, snapshots, milestones, plan completion, where you are now, what's upcoming — then walks you through every open thread. Saved to builds/ by default; degrades gracefully (no ticket/plan/thin transcript → report whatever exists). Dual audience: a human returning cold, and the agent itself getting its bearings. A building block: it orients and reports, never touches code/git/ticket content. Triggers: "/report", "where are we", "where do things stand", "what's the state of this session", "get me back in the flow", "orient me", "where did we leave off — on STATE, not on what-we-did", "I'm lost — catch me up on the state".
version
1
tier
lightweight
args
[-- <what you most want re-oriented on>]
Get back into the flow of a session in one glance. /report is the present-tense orientation sibling of the workflow family. Where /summarize reports backward (what did we do, was it good, interrogate it) and /session status prints thin mechanical state (.state.json phase, lifecycle), /report answers the question you actually have when you return to a window cold: "where do things stand right now, what's waiting on me, and what's next?" — with a rendered state graph.
It is read-only (¶INV_REPORT_READ_ONLY) and sessionless, and runs within the active session: locate the transcript → write the orchestrator's own bearings → spawn a transcript-scanning subagent (file handoff to builds/) → reconcile → graph → render → walk the open threads → save. <trailDir> = <sessionDir>/builds/.
Dual audience. The report serves two readers at once: a human returning after a break (or after /clear — the session persists and is reactivated), and the agent itself re-establishing its bearings. Both need the same thing — the current state, grounded in what actually happened, not a hopeful summary.
Hard boundaries. Not /summarize (never reviews work quality, runs the inverse-ask palette, or dwells on the past beyond what establishes the present). Not /snapshot (never commits, posts to a ticket, or re-runs a gate). Not /session (a rich re-orientation, not a state dump). A bug or risk it notices is an open-thread line item, not a repair.
/report Protocol
1. Locate the transcript & resolve targets
Establish the ground-truth sources, degrading gracefully (¶INV_REPORT_GRACEFUL) — a missing source narrows the report, never aborts it.
The active session (<sessionDir>): its *_LOG.md, plan (if present), DIALOGUE.md, and builds/.
The raw transcript JSONL (<transcript>) — the subagent's primary source (§3). Resolve it deterministically from the session id Claude Code exports (¶INV_REPORT_TRANSCRIPT_IDENTITY) — never by newest-mtime, which under multiple open windows returns a sibling window's file:
If ends up empty, the subagent falls back to + (already tool-call-free) — thinner, but never a hard fail, and never the wrong window's transcript. The orchestrator resolves the path and passes the substituted absolute path to the subagent.
# Fallback ONLY if the env var is unset or the file is missing:
if
"$CLAUDE_CODE_SESSION_ID"
"$TRANSCRIPT"
then
ls
"$HOME/.claude/projects/$SLUG"
head
# Mechanical verify: the tail must contain THIS session's dir, else it's the wrong window.
tail
"$TRANSCRIPT"
"$(basename "$sessionDir")"
""
fi
<transcript>
DIALOGUE.md
*_LOG.md
The ticket(s) — derive the Linear key from the session's tickets[] (.state.json) or the branch name (fin-2833-… → FIN-2833). Read-only. Sanity-check relevance: a branch-derived key may be unrelated to this session's actual work (e.g. an engine-tooling session on a feature branch) — flag low-relevance rather than presenting it as the ticket. No key → skip the section.
Git — the repo(s) the work actually landed in (¶INV_REPORT_GIT_FOLLOWS_WORK). Do NOT assume cwd-git is the work's repo. Report cwd git, AND any other repo the session actually modified (e.g. an engine/skill session edits ~/.claude/engine — a separate repo; cwd-git is then unrelated). For each: branch, dirty-file count, last commit; ahead/behind vs base only if an upstream/base is set (guard it). Use git log --oneline -n 10 (safe on young branches — never HEAD~10.. which errors under 10 commits).
Echo one line:Orienting on <session "<slug>"> — transcript <id|fallback>, ticket <KEY(rel?)|none>, work-repo <path>. Building bearings…
2. Orchestrator's own bearings
Write down what you (the orchestrator) currently believe the state to be, from your own in-context memory. Do it now so it's captured — but it is a hypothesis to be checked, not the answer (¶INV_REPORT_RECONCILE). Keep it tight (you hand it to the subagent in §3): the goal as you understand it, what you think was just done, what you believe is pending, and — honestly — where you're unsure or may have lost the thread. On a cold start with little context, say so plainly; the transcript scan then carries the load.
3. Spawn the transcript-scanning subagent (file handoff)
Before dispatching — §CMD_LOG_SKILL_INVOCATION: log this dispatch to the session log (why + context-pack pointer + one-line re-tread) so a restarted session can re-tread it. Fire it as the last step before the Task/Agent handoff.
Spawn one subagent (general-purpose or analyzer) to reconstruct the state from <transcript>. File handoff (¶INV_REPORT_FILE_HANDOFF): it WRITES its full digest to <trailDir>/REPORT_DIGEST.md and RETURNS only a 6–10 line summary — keeping the orchestrator lean and leaving a durable artifact beside the other builds/ files. Run it foreground (§4–§8 need it).
Guard: if neither <transcript> nor DIALOGUE.md/*_LOG.md exists, skip the subagent — the orchestrator does git + ticket directly.
Construct a fully self-contained prompt:
ROLE: You are a session cartographer. Reconstruct the TRUE current state of a work session from its raw transcript. You READ and RECONSTRUCT; you never mutate, commit, post, fix, or re-run a gate.
PRIMARY SOURCE — the raw transcript: Read <transcript> (JSONL, one message/line). Filter as you read (¶INV_REPORT_TRANSCRIPT_FILTER) — the cut line is decision/state-bearing vs read-noise, NOT "only AskUserQuestion":
KEEP every user text message and every assistant text block (reasoning, plans, claims).
KEEP, unfiltered, all decision/state-bearing tool calls + results: AskUserQuestion (both sides — the decision record), Skill/Task invocation headers (name + one-line input + one-line result — these are the major moves: /build, /snapshot, /experiment, /ticket, /pr), ExitPlanMode (plan acceptance), and any commit/ticket/PR-producing call + its result (git commit, linear save_*, gh pr create → the SHAs / keys / URLs the narrating text often omits).
DROP read/inspection noise: Read, Grep, Glob, read-only Bash, and engine log appends. Note that such work happened from surrounding text; don't ingest the payloads.
If <transcript> is absent/empty, fall back to DIALOGUE.md + *_LOG.md and say so.
RECONSTRUCT BLIND FIRST (¶INV_REPORT_RECONCILE): Derive your State line, Work-done, Pending, Open-threads, and Graph-inputs from the transcript before you read the orchestrator's bearings. Do not read the bearings block below until your independent reconstruction is written. This prevents anchoring on a possibly-wrong narrative.
STALENESS CHECK (always run — ¶INV_REPORT_STALENESS): Compare the mtime of every narrative artifact (the debrief and other non-log *.md, the plan, and — if fetched — the ticket/PR body) against the timestamp of the last substantive log entry / commit. Flag any narrative artifact that predates the last real work as stale (stat -f %m on macOS). "Artifact X was written before verdict/work Y" is consistently the single highest-value finding — surface each stale artifact in Open threads, and in Reconciliation deltas when it changes the state read.
ALSO READ (state, not narrative), read-only: git for every repo the work touched (cwd, and e.g. ~/.claude/engine for engine work — label which holds this session's work and whether committed) — git -C <repo> status --porcelain + git -C <repo> log --oneline -n 10; the plan file's [x]/[ ]if one exists (many skills have none — skip silently); the Linear ticket via MCP only if a relevant key is given.
THEN — and only then — read the orchestrator's bearings and diff:<paste the §2 bearings note verbatim>
Where the transcript contradicts or outruns the bearings, the transcript wins; capture each mismatch in the deltas section.
WRITE the full digest to <trailDir>/REPORT_DIGEST.md with these sections, then RETURN a 6–10 line summary (state line + the headline finding + counts):
State line — one sentence: where the work stands right now.
Work done — 3–6 substantive things, most recent first.
Git state — per repo, labeled; which holds this session's work; committed or not.
Ticket state — status + most relevant point, or "none / branch-derived (unrelated)".
Pending on the user — decisions/questions explicitly awaiting the human (mine unresolved AskUserQuestion exchanges + direct asks).
What's next — immediate next actions, ordered.
Open threads / dangling — unanswered questions, #needs-* tags, deferred items, stale artifacts, "come back to X" — each with a one-line disposition hint.
Graph inputs — ordered trajectory nodes (milestones, phase/branch divergences, snapshots=commits, decision points, plan steps) each marked done/current/upcoming; AND a one-word verdict branches | linear on whether the trajectory actually forks (drives §5's gate).
Reconciliation deltas — where your (transcript-first) reconstruction differs from the bearings, including any stale-artifact corrections.
4. Reconcile & assemble
Read <trailDir>/REPORT_DIGEST.md. The subagent's transcript-first reconstruction is authoritative on facts; your §2 bearings contribute only unstated intent (what you were about to do) — never override a transcript fact with a bearing. Surfacing a reconciliation delta (§3.9) is often the single most useful line for an agent that had lost the thread.
5. Render the flowgraph — reuse /graph, gated on real structure
Gate first (¶INV_VISUALIZE_STRUCTURE_WITH_GRAPH): render a flowgraph only when the trajectory actually branches / loops / diverges (digest §8 verdict = branches). If it's linear or thin (degraded path → a flat commit list), skip the graph — the ordered "What's next" list is clearer; a flowgraph of 1→2→3 is noise.
When it does branch, invoke /graphinline via the Skill tool (tell it to render once, no revision prompt) over the digest's graph-inputs, as a trajectory graph in the §CMD_FLOWGRAPH Status & Trajectory vocabulary — never freehand glyphs (§INV_VISUALIZE_STRUCTURE_WITH_GRAPH):
done → ✓; upcoming → ○; dropped/cancelled → ✗; stale → ⚠ (pairs with the staleness check);
current position → ◄ HERE (exactly once); snapshots → ▣ <sha>; pivots → ╰► ⟨branched-off⟩;
decisions → ◆ with the outcome annotated (◆ … → chose X / ◆ (OPEN)).
Wrap in a code fence.
6. Render the report
Render the assembled report in chat (graph included when §5 rendered one), using the shape in assets/TEMPLATE_REPORT.md (the skill's base dir — do not hardcode ~/.claude). Match the project's prose density and stick to the template's plain section headers — no decorative emoji unless the template itself carries them (the project leans terse-and-plain; do not freehand decoration on top of the shape). Lead with the state line and a compact state strip (branch · work-repo committed? · dirty · [plan x/y — omit if no plan] · open-threads), then the reconciliation deltas (near the top — it's the payload), then: work done → git (per repo) → ticket → the flowgraph (or ordered next-list if gated out) → pending-on-you → what's next → open threads.
7. Walk every open thread
Walk the user through each open thread / pending decision (digest §5 + §7) for disposition — the thorough close is what turns a report into being back in the flow. Batch via AskUserQuestion (4 per batch, §INV_BATCH_SIZE_4). Per thread offer disposition: address now / defer (tag) / dismiss / note & move on — and always honor an "explain first" request (a returning human often needs the why before deciding, not just fix/defer/dismiss): explain the thread's stakes, then re-present its disposition. "Address now" = route it (resume the work, or hand to the owning skill) — never fix code inside /report. "Defer (tag)" applies an orientation #needs-* bookkeeping tag (permitted by ¶INV_REPORT_READ_ONLY's scope — it touches no code/git/ticket content). Zero open threads → say so and skip to §8.
8. Save (default) & stop
Save the report by default (¶INV_REPORT_SAVE_BY_DEFAULT) — it's a durable artifact, not an ephemeral glance. Write it to <sessionDir>/builds/REPORT.md, latest-wins (overwrite on re-run). The digest already sits beside it at <trailDir>/REPORT_DIGEST.md. Report the saved path (clickable), then stop.
Constraints
¶INV_REPORT_READ_ONLY — /report never mutates code, git, or ticket content: no commits, no ticket posts, no code edits, no gate/test re-runs. Permitted: writing its own report + digest under <trailDir>, and applying orientation #needs-* bookkeeping tags during the §7 thread-walk (session-state bookkeeping only). A bug or risk it notices is an open-thread line item, not a repair.
¶INV_REPORT_ORIENTATION_NOT_REVIEW — Forward/present-facing: where are we, what's blocked, what's next. Disjoint from /summarize — it does NOT judge work quality, run goal-vs-actual retrospection, or offer the inverse-ask palette. "Was this good / interrogate what we did" → route to /summarize. Past events appear only insofar as they establish the present state.
¶INV_REPORT_TRANSCRIPT_IDENTITY — Resolve the transcript by session identity ($CLAUDE_CODE_SESSION_ID), never by newest-mtime. With multiple windows open, newest-.jsonl is routinely a sibling session; the mtime path is a last-resort fallback and must be verified against this session's dir before use.
¶INV_REPORT_TRANSCRIPT_FILTER — The subagent drops read/inspection noise but retains all decision/state-bearing calls: AskUserQuestion (unfiltered), Skill/Task invocations, ExitPlanMode, and commit/ticket/PR calls (with their SHAs/keys/URLs) — plus all user + assistant text.
¶INV_REPORT_RECONCILE — The subagent reconstructs from the transcript blind first, then reads the orchestrator's bearings only to diff for the deltas section. Transcript-authoritative on facts; bearings add unstated intent only. Reconciliation deltas are surfaced, not hidden.
¶INV_REPORT_STALENESS — The subagent always checks narrative-artifact mtimes against the last substantive work and flags any that predate it (a debrief/ticket/PR body written before the last real work). Stale-narrative is a recurring highest-value finding — name it, don't hope it emerges.
¶INV_REPORT_FILE_HANDOFF — Subagent→orchestrator handoff is via file: the digest is written to <trailDir>/REPORT_DIGEST.md (returning only a short summary), and the final report is saved to <sessionDir>/builds/REPORT.md. Both are durable artifacts beside the other builds/ files.
¶INV_REPORT_SAVE_BY_DEFAULT — The report is saved by default (not offered/ephemeral), latest-wins.
¶INV_REPORT_GIT_FOLLOWS_WORK — Report git for the repo(s) the session actually modified, not cwd by assumption; cwd-git can be entirely unrelated (e.g. engine work under ~/.claude/engine).
¶INV_REPORT_GRACEFUL — Degrade, never hard-fail. No ticket → skip. No plan → omit plan segment. No transcript → DIALOGUE + log; none of those → skip the subagent, orchestrator does git + ticket. Young branch → -n 10, guarded ahead/behind. Always render whatever exists.
Subagent for the transcript read; interactive walk stays with the orchestrator.
