Conversations belong
with concepts.

A concrete example, before the abstract problem.

You're working in ~/projects/customer-portal/ on a checkout-flow polish. Mid-session, you notice the order-history page's refund button needs a partial-refund variant — and that's an API contract change in ~/projects/billing-service/refund-flow/, a subsystem with its own deploy cycle, its own stakeholders, its own multi-month roadmap.

The work just shifted concepts. The customer-portal session is the wrong place to design a refund-flow improvement. /refocus moves the conversation to where the artifacts will land — and where the reasoning will be findable later.

customer-portal/
├── CLAUDE.md
├── src/checkout/    ← you started here
│   ├── ReviewStep.tsx
│   └── PaymentStep.tsx
├── src/orders/      ← noticed the issue here
│   └── RefundButton.tsx
├── docs/
└── tests/

billing-service/
├── CLAUDE.md
├── refund-flow/     ← spawn HERE
│   ├── CLAUDE.md    ← own context
│   ├── api/contracts/
│   ├── docs/
│   └── tests/
├── invoicing/
└── reconciliation/

Stay at customer-portal: the refund-flow reasoning gets buried in someone else's transcript and the design rationale is lost the moment you close the session. Spawn to refund-flow: it accumulates its own focused history; future sessions there inherit the full reasoning by just cd-ing in.

Same example. Where does the conversation actually live?

The directories on disk don't change. What changes is whether one session accumulates everything and mis-tags most of it, or two sessions each accumulate what belongs to them. Claude Code stores every session by the cwd it was opened in — so the transcript lands wherever you launched it, regardless of where the work eventually touches.

~/.claude/projects/
└── -home-administrator-projects-customer-portal/
    └── <session>.jsonl
        ├── UI design discussion         ← belongs here
        ├── Refund-flow API debate       ← mis-tagged
        ├── Reviewer pushback rationale  ← mis-tagged
        └── Final design decisions       ← mis-tagged

~/.claude/projects/
├── -home-administrator-projects-customer-portal/
│   └── <parent>.jsonl
│       └── UI design discussion only        ← clean
│
└── -home-administrator-projects-billing-service-refund-flow/
    └── <child SID>.jsonl
        ├── Refund-flow API debate           ← right home
        ├── Reviewer pushback rationale      ← right home
        └── Final design decisions           ← right home

The technical pivot that makes this work: when /refocus spawns a child, it generates a UUIDv4 session ID up front and tells the user to run cd <dest> && claude --session-id <SID>. The child's transcript lands at the destination's encoded-cwd location — exactly where future sessions there will discover it.

After the work — three layers live at the destination.

Same refund-flow example, after /refocus-complete finishes. Three distinct places hold three different shapes of knowledge: the transcript (full reasoning), the per-event audit (what work happened), and the canonical state (current truth that future sessions auto-load).

~/projects/billing-service/refund-flow/        ← the destination
├── src/...                                       (code — the actual work)
├── tests/...
├── CLAUDE.md                                     ← auto-loads docs/context/* on session start
└── docs/
    ├── context/                                   ← LAYER 3 — canonical state
    │   ├── architecture.md         ← updated by /context-save
    │   ├── interfaces.md           ← updated by /context-save
    │   ├── conventions.md
    │   └── gotchas.md              ← updated by /context-save
    └── refocus/                                   ← LAYER 2 — per-event audit
        ├── 2026-04-26-refund-redesign-a3f91c.md  (Brief + Result + material_changes)
        └── INDEX.md                              (gitignored, auto-regenerated)

~/.claude/projects/                              ← LAYER 1 — full transcript
└── -home-administrator-projects-billing-service-refund-flow/
    └── a3f91c2e-7b8d-…-jsonl       ← every word of reasoning, resumable

Color-coded by layer: green = canonical state, teal = per-event audit, orange = full transcript. Next slide: how content actually gets into each layer, and the trigger chain that makes Layer 3 happen reliably.

The chain that gets it there — three triggers, one guarantee.

Each layer is populated by a different mechanism. The load-bearing one is Layer 3 (canonical state) — it's how material decisions escape the per-event brief and become the current truth that the next session at this directory auto-loads on startup.

The chain: child enumerates material_changes → /refocus-complete appends Result → invokes /context-save → docs/context/* updated → next session inherits the new truth. Three triggers ensure it happens: cognitive (mandatory enumeration in Result), mechanical (chained invocation), belt-and-suspenders (SessionEnd hook for abandonment).

One conversation. Three concepts. Zero of them where they belong.

This deck was designed in a session that started about agent-memory, drifted into a platform-wide MCP standard, then drifted again into this skill. Three distinct conceptual scopes — three sets of artifacts in three different directories. But the reasoning behind every decision lives in one transcript, mis-tagged under the first directory.

This is what every session looks like in a multi-year ecosystem with thousands of project directories. Drift is normal. The cost is invisible until future-me opens a directory looking for the reasoning that produced its artifacts — and finds the artifacts but not the reasoning.

So we built /refocus — a way to match conversations to concepts.

Principles ordered by dependency: philosophy first (why), topology second (how the work behaves), substrate third (where it lives). Reverse the order and the rest doesn't make sense.

Three things that should always be 1:1:1 — and rarely are.

The model that makes the rest of this deck make sense: every concept is developed by a conversation that produces artifacts in a directory. When all three line up, knowledge accumulates cleanly. When they don't, conversations bleed into wrong directories and reasoning gets lost.

The drift problem is what happens when one conversation develops three concepts whose homes are three different directories. The /refocus answer is to make conversation boundaries match concept boundaries, automatically and with auditable history.

How a refocus event flows from spawn to result.

Five stages. The parent stays in its session; the child gets a curated brief, runs to completion, and returns its result for the parent to act on. Call-stack semantics.

Manual launch (step 2) is the default. The pre-generated session ID is the architectural pivot — it ensures the child's transcript lands at the destination's encoded-cwd location, so future sessions in <dest> can claude --resume <SID> and inherit the full reasoning.

What do you want to know more about?

The hardest call: does this sub-service deserve its own conversation?

Imagine you're working at ~/projects/myapp/ and the work shifts to authentication. Three options: stay at myapp/, spawn to myapp/auth/, or carve out an entirely new project. Granularity is a judgment call, not a formula — but five signals push spawn and four push stay.

This is the part of the design we'll keep refining as we use the skill. The signals on the next slide are the starting heuristic; expect them to evolve as patterns emerge.

Five signals a sub-service earns its own conversation.

If three or more hold, spawn. If only one or two, ask: would future-me, opening that subdirectory cold, expect to find a focused history there? If yes, spawn. If "I'd just look at the parent," stay.

• 1
  It has its own CLAUDE.md (or equivalent local context). The directory already announces "I am a separate concept" — the conversation should match.
• 2
  It has its own deploy / build / test cycle. Independent operational lifecycle = independent reasoning lifecycle.
• 3
  The work has multi-week lifespan. A standard, a migration, a substantial feature — work that will be revisited and refined over time.
• 4
  Distinct stakeholders or decisions. Different reviewers, different acceptance criteria, different Definition-of-Done than the parent project's.
• 5
  Will produce more than one artifact in this subtree. One quick file edit doesn't earn a session; a multi-file change with cross-references does.

When to STAY at the parent — even if work touches a sub-service.

Granularity errors run in both directions. Spawning too eagerly fragments reasoning across micro-sessions; staying too long bleeds context into wrong directories. These are the four cases where not refocusing is the right call.

When in doubt: start at the parent and spawn later. It's cheaper to refocus mid-conversation than to discover three weeks later that the reasoning lives in the wrong directory.

Children are leaves. Only parents fork.

The spawn graph is a strict tree from a single root, not a DAG. This is enforced by a hard guardrail in the skill — not just a written rule in the brief. It mirrors call-stack semantics every enterprise programmer already knows: a function call returns to its caller; the caller decides what to call next.

parent
├── child A ← runs, returns
├── child B ← runs in parallel, returns
└── child C ← runs, returns

(parent reads results, decides what to spawn next)

parent
└── child A
    └── grandchild ← refused

ERROR: Architectural violation.
Children cannot fork.
Surface this in suggested_follow_ups
and return to parent.

Detection: when a session is launched via a refocus brief, a SessionStart hook sets SESSION_REFOCUS_ROLE=child. The /refocus command reads this env var and refuses to execute.

What happens when a child needs work elsewhere?

The honest failure mode: a child session, while doing its assigned work, discovers that a blocker requires changes in a different directory it has no jurisdiction over. The strict-tree rule says it can't fork to clear the blocker. The procedure:

• 1
  Child runs /refocus-complete with Status: blocked. Result section explicitly distinguishes "completed successfully" from "blocked, returning to parent for orchestration."
• 2
  Result.suggested_follow_ups names the work that needs to happen elsewhere — directory + slug + one-line reason for each blocker.
• 3
  Parent's auto-receive surfaces the blocked result on next session resume. Parent reads, decides: spawn one or more clearing children, or absorb the unblocking work itself.
• 4
  Once the clearing children return, parent re-spawns the original blocked work as a fresh refocus, with parent_refocus_id chained to the original. The full chain is reconstructable.
• 5
  The original brief stays canonical. Re-spawn updates the brief with new context but the fork chain shows what unblocked it.

Pre-generate the session ID before the child starts.

The architectural pivot from review-board cycle 1: pre-generate a UUIDv4 child session ID at spawn time, embed it in the brief, and pass it to claude --session-id when the user launches the child. The transcript lands at ~/.claude/projects/<encoded-dest-cwd>/<SID>.jsonl — exactly where future sessions in <dest> can find it via claude --resume.

$ /refocus ~/projects/mcp --slug mcp-standard
  → wrote brief at ~/projects/mcp/docs/refocus/2026-04-26-mcp-standard-a3f91c.md
  → child_session_id: a3f91c2e-7b8d-4e5f-9a1b-c2d3e4f5a6b7
  → relaunch: cd ~/projects/mcp && claude --session-id a3f91c2e-7b8d-4e5f-9a1b-c2d3e4f5a6b7

(later, after child completes)
$ cd ~/projects/mcp
$ claude --resume a3f91c2e-7b8d-4e5f-9a1b-c2d3e4f5a6b7
  → resumed in destination directory's encoded-cwd location
  → full transcript history available

This is the property that makes the directory-bound history actually work. Without --session-id, the child gets a random ID, the user can't find it later by name, and the "future-me opens dest, gets the reasoning" promise breaks.

Three options considered. One chosen as primary.

Each option fails one of three criteria: cwd-bound transcript, interactivity for child, parent doesn't block. The picked one is the only path that satisfies all three.

Subagents have a real role — drafting the brief itself is a clean subagent task. But they aren't the fork mechanism, because their transcripts don't land at the right directory.

Context management at a glance — every layer has a home and an owner.

Five places hold knowledge in this ecosystem. Each has a specific scope, a specific updater, and a specific lifetime. Refocus's mainline outputs live in rows 1–4 (files); row 5 is a different scope and rarely involved.

Garbage collection (rows 2 + 3): per-event files at status=result for >90 days move to docs/refocus/archive/YYYY-QN/; INDEX surfaces only live entries plus the last 30 days. Archive is grep-able offline — keeps the index scannable across years.

Scope boundary (row 5): the agent-memory MCP server (~/projects/agents/memory) holds cross-project user/feedback facts — bullet-fact-shaped, outside any single project's scope. Refocus's project-scoped outputs (rows 2 & 4) live in the files above, never in agent-memory. The two systems compose at different scopes; they don't overlap. Test for the rare exception: outcome is bullet-fact-shaped and can't live in any project's docs/context/*.

When does drift earn a refocus?

Two firing conditions, both required. The second one is the test that makes the call instinctual instead of rules-based:

When NOT to refocus: quick lookups, debug interludes, cross-cutting work that genuinely needs the source's full reasoning context (the canonical example: a design that's three review-board cycles deep — the child won't make sense without the rejection history).

Risks we're tracking honestly.

• 1
  Granularity is a judgment call we haven't fully solved. The five signals + four counter-cases get us most of the way, but edge cases will accumulate. Mitigation: treat the rubric as v1 and refine as patterns emerge from real use.
• 2
  Briefs that are too thin or too thick. Thin → child redoes work; thick → it's a transcript dump. Mitigation: schema enforces section minimums + maximums; pointer-back to source jsonl exists as a "go check yourself" fallback.
• 3
  Manual relaunch friction. User has to run cd <dest> && claude --session-id <SID> in a new terminal. Acceptable for a v1 — subagent-as-fork was rejected for breaking the cwd-bound-history property; manual is the cost of getting that property right.
• 4
  Auto-discovery depends on a SessionStart hook. If the hook doesn't fire (mis-installed, settings overridden), pending briefs sit unloaded. Mitigation: skill provides explicit fallback commands; INDEX.md is human-readable so a manual cat always works.
• 5
  Source jsonl can be archived before child completes. User spawns, works at dest for weeks, source's transcript is auto-compacted. Mitigation: brief's "Inherited context" is self-contained; the pointer-back to source jsonl is a bonus, not a dependency.

Where we are. Where we're going.

The skill isn't built yet — this is a design walkthrough, not a launch announcement. v2 of the design is locked after one full review-board cycle (Gemini + Codex + Claude review-board), and the pieces are in sequence.

Once /refocus exists, every session in the ecosystem can stop being an unintentional accumulator of cross-cutting context. Knowledge lives where work is. Future sessions inherit history naturally just by cd-ing in.

Roadmap for enterprise use — what's NOT in v1, by design.

v1 ships single-developer. Items below close gaps that matter only at multi-engineer / 24×7 scale — deferred until friction is real, mapped here before we need them.

Not on this list — concurrent /context-save: each engineer works off a local clone and merges via git. Parallel updates surface as ordinary merge conflicts; no locking machinery needed.

Sequencing if/when adopted: 1, 3, 4 (brief-schema additions) are zero-risk and can ship anytime. 6–9 cluster: don't ship #6 without #7 and #9. Items 2 and 5 are independent quality-of-life additions that can land last.

"Am I outsmarting Anthropic?" — when a custom skill earns its keep.

Anthropic optimizes for the median user (one session that grows; auto-compaction; subagents; long context). Power users with specific workflows are expected to deviate. The real question isn't "does Anthropic do this?" — it's "does this pay for itself vs the default I'd reach for instead?"