Produce a DEEP, massive briefing that re-establishes full mental context on a piece of work just completed on a branch โ every critical workflow with its own code snippets, verbatim test titles, spine files, data paths, new tests, and open follow-ups. Use when returning to a branch after a break, picking up someone else's work, or handing off work to another agent. Length is NOT capped; scannability is the measure โ the briefing must have a Workflow Index for jumping, and every workflow must include a code snippet.
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.
Produce a DEEP, massive briefing that re-establishes full mental context on a piece of work just completed on a branch โ every critical workflow with its own code snippets, verbatim test titles, spine files, data paths, new tests, and open follow-ups. Use when returning to a branch after a break, picking up someone else's work, or handing off work to another agent. Length is NOT capped; scannability is the measure โ the briefing must have a Workflow Index for jumping, and every workflow must include a code snippet.
{"short-description":"Deep re-contextualization briefing on recent work"}
Recontextualize โ Rebuild full mental context on recent work
When you return to a branch after hours or days away, you've lost the thread: you know roughly what you were doing but not the exact surface area, not the pivotal commits, not the snippets of code you should re-read first. This skill produces a self-contained massive briefing that rebuilds the full mental model in one pass: every critical workflow, the code that drives it, the tests that pin it, the data paths it touches, and the follow-ups still open.
This is not a summary skill. Go deep. A 2000-line briefing is fine โ better a thorough one you can jump around in via a Workflow Index than a tight one that cut corners on the workflows you were actually resuming today.
Useful for:
Returning to a long-running branch after a context break
Picking up someone else's in-progress branch
Writing a PR description that captures the why not just the what
Handing off work to another engineer or agent
Filing a design review note
Not a substitute for reading the actual diff or the commit messages. This is the briefing before the diff, the table of contents for the diff.
Inputs
Flag
Default
Purpose
--base <ref>
main (or configured default branch)
The ref to diff against โ everything since this point is "the work"
--branch <ref>
current HEAD
The ref the work lives on
--focus <glob>
none
Restrict analysis to files matching this glob (e.g. packages/core/src/domains/billing/**)
--out <file>
stdout
Write the briefing to a file instead of printing it
--max-snippets N
8
Cap on the number of code snippets in the briefing
Workflow State Machine
START
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 0: RESOLVE REFS โ
โ โ
โ Resolve base + branch refs. Fail fast if base isn't โ
โ reachable from branch (nothing to contextualize). โ
โ โ
โ git merge-base <base> <branch> โ
โ git rev-parse <base> <branch> โ
โ โ
โ Record the merge-base as the "start of work". โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 1: COMMIT SURVEY โ
โ โ
โ Pull the commit stream since the merge-base: โ
โ โ
โ git log --reverse --pretty=format:'%h|%s|%an|%ad' โ
โ --date=short <merge-base>..<branch> โ
โ โ
โ Record: total commit count, authors, date range, โ
โ and the raw list. โ
โ โ
โ If there are > 30 commits, you are probably โ
โ briefing an entire feature branch โ raise the โ
โ snippet budget and expect multiple workflows. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 2: CHANGED-FILE SURVEY โ
โ โ
โ git diff --stat <merge-base>..<branch> โ
โ git diff --name-status <merge-base>..<branch> โ
โ โ
โ If --focus <glob> is set, filter to matching files. โ
โ โ
โ Bucket the files by subsystem using the layer map โ
โ (see "Subsystem Layer Map" below). Each bucket is โ
โ a candidate critical workflow. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 3: IDENTIFY CRITICAL WORKFLOWS โ
โ โ
โ For each bucket with > 0 files, identify its โ
โ "spine" โ the file(s) that drive the control flow: โ
โ โ
โ โข apps/api/src/routes/* โ HTTP entry points โ
โ โข packages/core/.../application/* โ service seam โ
โ โข packages/core/.../domain/* โ pure rules โ
โ โข packages/core/.../ports/* โ port contracts โ
โ โข packages/infra/db/src/repositories/* โ persistenceโ
โ โข apps/worker/src/*-activities.ts โ temporal work โ
โ โข migrations (*.sql) โ schema changes โ
โ โ
โ A workflow = the thread that crosses layers for ONE โ
โ user-facing behavior. Group HTTP โ service โ port โ โ
โ repo together under one workflow heading. โ
โ โ
โ ELEVATION SIGNALS โ any of these MUST get its own โ
โ workflow section, even if the LOC change is tiny: โ
โ โข a new dedicated test file (*.e2e.* or โ
โ focused *.integration.test.*) โ
โ โข a new migration (*.sql under drizzle/migrations) โ
โ โข a new port (Context.Tag) or new adapter โ
โ โข a new domain event type in events.ts โ
โ โข a new middleware file โ
โ โข a new route handler file โ
โ โ
โ Rationale: the author signalled a discrete concept โ
โ by giving it its own file. Burying it inside another โ
โ workflow's prose robs a returning engineer of the โ
โ spine they need to resume that specific thread. โ
โ โ
โ DEMOTION: if a file only has a 1-2 line change AND โ
โ no elevation signal AND no related test landed, โ
โ demote it โ it's likely incidental, not a workflow. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 4: TEST LANDING ZONE โ
โ โ
โ New tests are the BEST specification of intent โ โ
โ they tell you what the author believed the code โ
โ should do. Pull them out separately: โ
โ โ
โ git log --diff-filter=A --name-only --pretty= โ
โ format: <merge-base>..<branch> โ
โ -- '**/*.test.ts' '**/*.integration.test.ts' โ
โ โ
โ Also capture tests that were MODIFIED (an existing โ
โ test's expectation changing is a behavior change): โ
โ โ
โ git log --diff-filter=M --name-only ... โ
โ -- '**/*.test.ts' โ
โ โ
โ For each added test file, extract the describe + โ
โ it() titles VERBATIM โ they are the "intent โ
โ summary" of the work in one glance. โ
โ โ
โ CRITICAL: quote titles verbatim. DO NOT paraphrase. โ
โ "full happy path + error cases" is a paraphrase and โ
โ loses the machine-precision that test names carry. โ
โ '@spec INV-BILLING-009 emits billing.usage_cap_ โ
โ warning when increment crosses 80 percent' is โ
โ what the reader needs โ copy it directly from the โ
โ `it(...)` string. โ
โ โ
โ Use `grep -E "^\s*(describe|it)\s*\('"` or the Grep โ
โ tool to extract the titles without opening the full โ
โ file. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 5: PULL CODE SNIPPETS (MANDATORY PER WORKFLOW) โ
โ โ
โ HARD RULE: every workflow section MUST contain at โ
โ least one code snippet quoted from a file read this โ
โ run, tagged with `file:line`. A workflow without a โ
โ snippet is a thin heading โ demote it out of the โ
โ workflow list into the "Touched but not deep-dived" โ
โ appendix (see template below). โ
โ โ
โ If this rule forces you to read 21 source files, โ
โ read 21 source files. That is the skill working as โ
โ designed โ thin headings with no code-backed โ
โ deep-dive are a regression even if "everything got โ
โ a section". โ
โ โ
โ Snippet selection rules: โ
โ โข Prefer the biggest contiguous changed hunk in the โ
โ spine file over many tiny ones. โ
โ โข Prefer added/new code over lines touched inside โ
โ a large pre-existing function (noise). โ
โ โข Prefer code with non-trivial comments โ the โ
โ author is explaining themselves for a reason. โ
โ โข Cap each snippet at ~30 lines; use `// ...` โ
โ to elide uninteresting middle sections. โ
โ โข Tag every snippet with `file:line` so the reader โ
โ can jump to the source. Never quote without a โ
โ location. โ
โ โข If the spine file is huge, pick ONE hunk โ don't โ
โ try to cover the whole file. โ
โ โ
โ If --max-snippets is set AND you'd exceed it, keep โ
โ snippets on the HIGHEST resume-priority workflows โ
โ (see Step 5.5) and demote the rest to the appendix. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 5.5: ASSIGN RESUME PRIORITY โ
โ โ
โ Before emitting, tag each workflow with a resume- โ
โ priority from {high, med, low}. A returning engineer โ
โ uses this to decide what to read first. โ
โ โ
โ HIGH โ any of: โ
โ โข An uncommitted-work file touches this workflow's โ
โ spine (author was mid-edit here). โ
โ โข The workflow contains the HEAD commit or one of โ
โ the last 3 commits. โ
โ โข A new migration is part of the spine. โ
โ โข The commit messages contain "WIP", "TODO", โ
โ "broken", "FIXME", "wip", "draft". โ
โ โ
โ MED โ any of: โ
โ โข Workflow contains 5+ commits. โ
โ โข A new port / event / middleware is added. โ
โ โข A new dedicated test file is added. โ
โ โ
โ LOW โ everything else (workflow touched only โ
โ incidentally; mainly relevant for full-history โ
โ readers, not for resuming work today). โ
โ โ
โ Sort the Workflow Index HIGH โ MED โ LOW so the โ
โ first screen of the briefing shows the sections โ
โ the reader is most likely resuming. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 6: OPEN THREADS โ
โ โ
โ Scan the diff for: โ
โ โ
โ โข `TODO`, `FIXME`, `XXX`, `HACK`, `NOTE:` comments โ
โ added in this work (not pre-existing) โ
โ โข `Effect.logWarning` calls added โ warnings โ
โ usually flag paths the author left deliberately โ
โ unfinished โ
โ โข `@spec` or `@todo` tags added โ
โ โ
โ Also check the branch working tree for modified-but- โ
โ uncommitted files: โ
โ โ
โ git status --porcelain โ
โ โ
โ These are usually the place the author WAS when they โ
โ context-switched out โ the most important thing to โ
โ look at. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 7: EMIT THE BRIEFING โ
โ โ
โ Render the briefing using the template below. โ
โ Write to --out if provided, else stdout. โ
โ โ
โ There is NO line budget. A long branch earns a long โ
โ briefing โ a 2000-line document is fine *if* every โ
โ workflow carries a code-backed deep-dive and the โ
โ reader can jump via the Workflow Index. โ
โ โ
โ The measure of success is SCANNABILITY, not length: โ
โ โข TL;DR + commit spine + Workflow Index must fit โ
โ in the first ~100 lines (first screen is โ
โ orienting). โ
โ โข Every workflow heading must be reachable from โ
โ the Workflow Index in one click / Ctrl-F. โ
โ โข No padding โ if a line doesn't earn its place, โ
โ cut it. But don't cut a real workflow to save โ
โ lines. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
DONE
Output Template
# Recontextualization: `<branch>`**Base**: `<base>` @ `<base-sha-short>`**Branch**: `<branch>` @ `<head-sha-short>`**Merge-base**: `<merge-base-sha-short>`**Commit range**: `<N>` commits, `<author-count>` author(s), `<start-date>` โ `<end-date>`**Uncommitted changes**: `<clean | N files modified>`## 60-second TL;DR
<3-5 bullets. Each bullet = one sentence, describing the branch's overall
arc and user-facing impact. No commit SHAs in the TL;DR โ this is the
briefing, not the changelog.>
## Commit spine (chronological)
| # | SHA | Subject |
|---|-----|---------|
| 1 | `abc1234` | ... |
(Keep to ~15 rows for a short branch; for a 50+ commit branch, show
the first 5, last 10, and collapse the middle into a single
"... and N more commits in between" row. Never truncate the last
3 commits โ those are the freshest state the author left.)
## Workflow Index
The reader's jump table. One line per workflow, tagged with resume
priority and sorted HIGH โ MED โ LOW. A reader should be able to scan
this and pick 2-3 sections to deep-read.
| # | Priority | Workflow | Spine file |
|---|----------|----------|------------|
| 1 | **HIGH** | `charge.refunded` webhook handler | `packages/core/.../billing-service.ts:1012` |
| 2 | **HIGH** | Per-org rate limit on session endpoints | `apps/api/src/middleware/billing-rate-limit.ts` |
| 3 | MED | Property-based tests for margin math | `packages/contracts/src/billing.properties.test.ts` |
| 4 | LOW | Credit-ledger cursor compound keyset | `packages/infra/db/src/repositories/credit-ledger.ts:459` |
| ... | | | |
## Critical workflows### Workflow 1: <shortdescriptivename> `[priority: HIGH]`**Spine**:
-`path/to/entry.ts:NN-MM` โ HTTP entry
-`path/to/service.ts:NN-MM` โ application logic
-`path/to/repo.ts:NN-MM` โ persistence
**What changed and why**:
<2-4 sentences. Name the before state, the after state, the motivation.>
**Key snippet** (`path/to/file.ts:NN-MM`) โ MANDATORY, one per workflow:
```ts
// ...quoted code with author's comments preserved...
Covered by (quote test titles verbatim, use grep "\bit\s*(\s*'"):
path/to/new.integration.test.ts
describe('billing outbox emission')
it('@spec INV-BILLING-009 emits billing.usage_cap_warning when increment crosses 80 percent')
it('is idempotent on duplicate delivery')
Workflow 2: ... [priority: HIGH]
(repeat โ every workflow MUST have a snippet; no thin headings)
Touched but not deep-dived
Files that changed on this branch but don't merit their own workflow
section โ incidental edits, config bumps, typo fixes, lockfile churn,
generated code. One line each, NO snippets.
pnpm-lock.yaml โ dep bump for fast-check@3.23.2
apps/api/src/routes/teams.ts:44 โ typo fix in error message
specs/index.md โ table of contents regen
(If this section is longer than the "Critical workflows" section, you
probably over-demoted โ promote the most substantive files back up.)
Data paths touched
Short list of the domain types / ports / events that moved. Example:
Ports: CreditLedgerStorePort.append signature widened with failIfSuspended
Schema: migration 0043 โ partial unique index on auto_recharge_attempts
Shared types: StripeWebhookEvent.data.previousAttributes (new field)
(Keep this under 12 bullets. It's a lookup key, not a changelog.)
Tests added or modified
For each NEW test file, list the verbatim describe + it titles. A
paraphrased "what it pins" column is a trap โ it tempts you to write
generic prose instead of quoting the real test names. If a file has
more than ~8 it() titles, group by describe block and keep the most
representative 5-6 titles verbatim; note "โฆand N more" for the tail.
Uncommitted work: <the files the author was mid-edit on, if any>
TODO/FIXME added this branch: <file:line โ short note>
Deliberate warning logs: <file:line โ what it's signalling>
Known follow-ups:
Where to look first
Ordered list of files to read in sequence to rebuild your mental model
end-to-end. 3-5 files, no more.
path/to/spine-file.ts โ start here, it's the nerve center
path/to/new.integration.test.ts โ confirms what "working" means
path/to/migration.sql โ the data shape that everything else assumes
## Subsystem Layer Map
Use this to bucket files in Step 2. When a file matches multiple buckets,
pick the *most specific* one (deepest path wins).
| Bucket | Glob pattern | Layer |
|---|---|---|
| Contracts | `packages/contracts/src/**` | shared types/schemas |
| Domain โ billing | `packages/core/src/domains/billing/**` | core |
| Domain โ assets | `packages/core/src/domains/assets/**` | core |
| Domain โ <other> | `packages/core/src/domains/<name>/**` | core |
| Repos | `packages/infra/db/src/repositories/**` | persistence |
| Migrations | `packages/infra/db/drizzle/migrations/**` | schema |
| Stripe adapter | `packages/infra/stripe/src/**` | external |
| API routes | `apps/api/src/routes/**` | HTTP |
| API middleware | `apps/api/src/middleware/**` | HTTP |
| API integration tests | `apps/api/src/**.integration.test.ts` | tests |
| Worker activities | `apps/worker/src/*-activities.ts` | temporal |
| Worker workflows | `apps/worker/src/workflows.ts` | temporal |
| Web pages | `apps/web/src/app/**` | frontend |
| Specs | `specs/**` | design docs |
## Rules
1. **Go DEEP โ this is a massive-recontextualization skill, not a summary skill.** A returning engineer needs enough context to resume non-trivial work without re-reading the diff. That means thorough code-backed deep-dives per workflow, verbatim test titles, full spine listings, and genuine before/after/motivation prose. A 2000-line briefing with a jumpable Workflow Index is better than a 250-line briefing that cut corners on the workflows you were actually working on.
2. **Every workflow MUST have a code snippet.** A prose-only workflow heading is a failed workflow โ demote it to the "Touched but not deep-dived" appendix. If the mandatory-snippet rule forces you to read 20+ source files, read 20+ source files. That's the skill working as designed.
3. **Scannability is the real measure, not length.** The first ~100 lines (header + TL;DR + commit spine + Workflow Index) must orient the reader. Workflows must be reachable via the Index in one Ctrl-F. No padding โ every line earns its place โ but don't cut content to hit a line count.
4. **Snippets with line numbers, always.** A snippet without `file:line` is a receipt the reader can't verify. Always quote the location.
5. **Tests are the spec โ quoted verbatim.** If an added integration test title answers "what did this work do", copy the it() string literally. Paraphrases lose the machine-precision that makes test names useful.
6. **Verify counts, verify algorithm names.** If you claim "N tests", run `grep -c "it('" <file>` and use that number. If you call something a "token bucket", confirm it by reading the source โ don't infer from feature names. Every count and every technical label must be grounded in a file you actually read this run.
7. **No invented history.** If a commit message says the fix was for bug X, quote the commit message โ don't paraphrase into something stronger.
8. **Elevation signals override LOC heuristics.** A new test file, migration, port, event, middleware, or route handler *always* gets its own workflow section โ even if the LOC change is tiny. The author's filesystem choice is the signal.
9. **Sort workflows by resume priority (Step 5.5).** HIGH โ MED โ LOW. The reader's first screen should surface the things they're most likely picking back up today.
10. **Surface the uncommitted state.** The author was almost certainly in the middle of something when they stopped. `git status --porcelain` is the *most valuable* data point in a recontextualization.
11. **Don't run tests or linters.** This skill is read-only observation. It should never touch the repo state.
12. **One pass, not two.** This skill is cheap only if you run it in a single shot. Don't loop on "maybe I should also look at...". Emit the briefing from what Step 1-6 collected and stop.
## How to run
### Brief the current branch vs main
### Use inside a larger task
The typical flow after a context break:
1. `/recontextualize --out /tmp/brief.md`
2. Read `/tmp/brief.md` end-to-end.
3. Open the files in the "Where to look first" section.
4. Resume work โ now with a fresh mental model of the surface area.
## Anti-patterns
- โ **Thin workflow headings with no code snippet.** A workflow section that is just a spine list and a prose paragraph is a failure โ every workflow must have at least one `file:line`-tagged snippet. If you can't find one to include, the workflow belongs in the "Touched but not deep-dived" appendix, not in the critical-workflows list.
- โ **Dumping a raw `git log --stat`.** The whole point is synthesis โ not a reformatted changelog. Every workflow must have a "What changed and why" paragraph naming the before state, after state, and motivation.
- โ **Quoting entire files.** Individual snippets are ~30 lines max; use `// ...` to elide uninteresting middle sections. If you need more coverage, add a second snippet from a different hunk rather than one giant quote.
- โ **Padding.** No filler sentences that restate what the snippet already shows. No "this is a complex area" throat-clearing. Every line earns its place โ but cut padding, not content.
- โ **Cutting real workflows to hit a line budget.** There is no line budget. A long branch earns a long briefing. The measure is scannability (Workflow Index + jump), not page count.
- โ **Re-running tests to "confirm things work".** This skill is read-only. If the reader wants that, they can run `pnpm test` themselves.
- โ **Editorialising** ("this is clearly a bad pattern"). State what changed and why the author said they changed it. Opinions are noise at recontextualization time.
- โ **Padding the TL;DR with commit SHAs.** The commit table has SHAs; the TL;DR is prose.
- โ **Paraphrasing test names.** "full happy path + error cases" is a paraphrase; `it('refuses a negative quantity')` is the real thing. Always quote verbatim โ use `grep "\bit\s*(\s*'"` or `grep "\bdescribe\s*(\s*'"` to extract.
- โ **Burying an elevation-signal file inside another workflow's prose.** If `charge.refunded` has its own test file `billing-charge-refunded.e2e.integration.test.ts`, it gets its own workflow โ not one sentence inside the broader Stripe-webhook paragraph.
- โ **Guessing at counts or algorithm names.** "8 tests" when `grep -c "it('"` says 7 is a credibility-killing error. "Token bucket" when the source is a sliding-window Map is the same error for technical labels. Verify by reading the file.
- โ **Using a "What it pins" column** in the tests table. It tempts paraphrase. Quote `describe`/`it` strings instead.
- โ **Emitting workflows in chronological or alphabetical order.** Sort by resume priority โ the reader's first screen should surface the sections they're most likely picking back up.
