| name | Session Orientation |
| description | Orient from the workspace's project registry before working - canonical repo paths, current versions, pending state - instead of rediscovering them by searching. Activate at the start of any new or resumed session in a multi-project workspace, on project-state requests ("check the work on X", "is everything up to date", "continue where we left off"), before any broad audit, and before searching the filesystem for a project whose location should be known. Also owns closeout: promote scratchpad work to durable paths and update the registry before ending a session that changed state. |
Session Orientation
Purpose
A fresh session starts with amnesia about everything outside its context window:
where repos live, which copy is canonical, what version is current, what is
pending. Without a fixed orientation step, every session pays a rediscovery tax —
filesystem archaeology, stale-memory guesswork, unscoped audits — and sessions
restart instead of compounding. This skill makes orientation a procedure: read the
map, verify what matters live, then work — and makes writing the map back a
closeout duty, because the read side only works if sessions keep it true.
When to use this skill
- First substantive action in a new or resumed session in a multi-project workspace.
- Project-state requests: "check the work on X", "is GitHub up to date",
"continue the launch", "where are we on X" — oblique names count ("the scanner").
- About to
find/glob for a project whose canonical location should be recorded.
- About to start a broad audit with no defined scope.
- A session that changed durable project state is about to end (closeout half).
When NOT to use
- Single-project repos where the task names its own files — orientation is one
git status, not a procedure.
- Questions with no project-state component.
- Mid-session once oriented — re-run only after resume/compaction, or when
evidence contradicts the map (
memory-hygiene territory).
The procedure
-
Map before territory. Read the workspace registry (ACTIVE-PROJECTS.md or
whatever CLAUDE.md names) before any filesystem search or audit. Find the
entry the request refers to.
-
Trust order, stated: live observed state > registry > memory files >
recollection. The registry locates truth cheaply; it isn't truth. Live-verify
any registry or memory fact that is load-bearing (the entry's verify commands,
or git status -sb + a real git fetch at minimum).
-
Canonical path or explain yourself. Work happens in the registry-listed
clone. Copies found in scratchpads, temp dirs, or other sessions' workspaces
are never source of truth; using one requires saying so and why.
-
"Updated/done/published" is a compound claim. Check the parts and name
which you checked: tree clean; local == origin after a fetch; CI at HEAD; and
for releases: tag position, package registry, one consumer-side check (fresh
install or raw URL). A subset checked = a subset claimed.
-
Broad requests get scoped by the map: registry pending list + the
requester's emphasis, stated as an explicit scope — never an unbounded sweep.
-
Closeout writes the map back. Before ending a session that changed state:
promote durable work out of scratchpad paths (they die with the session);
update the registry entry (state, pending, pitfalls, date). A session that
changed state but not the registry is unfinished. No registry yet and the
workspace has outgrown one project? Creating a minimal one IS in scope.
-
Verify the handoff — don't assume it. "Updated" ≠ "would survive a cold
restart." Before relying on the handoff (and always when asked "would this
survive?"), simulate the cold-read: what does a fresh session load first
(registry, auto-memory, git), and does it reconstruct the true current state and
next steps — with NO stale/contradictory claims? Auto-memory drifts stale silently
(it once asserted a result a later session had disproved); the registry can lag;
work can sit unpushed. Actually check: registry current + has the next-steps,
memory not contradicting live state, everything committed AND pushed. Fix what the
cold-read would get wrong. Updating the map is not the same as testing that it works.
Quality bar
- No filesystem search for anything the registry already locates.
- Load-bearing state claims carry their trust level and are live-verified before
driving actions or assertions.
- No "updated/done" claim where only a subset of the compound check ran unnamed.
- Session end: no durable work stranded in scratchpads; touched registry entries
current and dated.
- Handoff tested, not assumed: a cold-read reconstructs the true state + next steps
with no stale/contradictory memory, and nothing is left unpushed.
Common failure modes
- Orientation theater: reading the registry, then repeating it as verified
fact. Run the verify line.
- Registry rot: entries nobody updates become traps — closeout is not
optional; per-entry dates make staleness visible; live state always wins.
- Scratchpad canonicalization: adopting whatever copy a search finds first.
- Audit-first instinct: answering "is everything ok" by scanning everything
instead of map → scope → audit the scope.
Works with sibling skills
live-state-truth supplies step 2's verification reflex; memory-hygiene owns
memory-vs-observation conflicts; intent-clarity decodes which project an oblique
request means; surviving broad audits become plan-gate work; publish-hygiene
owns the public-boundary checks step 4 feeds into; extract-approach captures
lessons while this skill's closeout captures state — notes vs map.
Provenance and maintenance
Added 2026-07-08 after a real failure: a session asked to "check the work" on a
project had to rediscover what it was, that its only clone sat in a dead session's
scratchpad, and which public surfaces were current — despite extensive memory
files. Root cause: state lived in narrative memory; nothing owned orientation.
Re-verify whenever a session re-derives facts a registry should have held: registry
existed but wasn't read → trigger failure; read but wrong → closeout failure.
