The /start-session orientation
How a fresh session gets oriented: it reads the saved project state, checks what git has done since, looks for a second session that may have changed things underneath you, then prints one brief and one recommended next move. It reads everything and writes nothing.
Still a work in progress. The line we're least sure of is how loud the warnings should be: too quiet and you miss a stale handoff, too loud and you ignore them. Tell us where that line sits. Reply on LinkedIn.
How to read this map
Pick a stage to walk, or start at the top
The walkthrough, as text
Every stage of the interactive walkthrough above, as plain readable text. Each stage has its own link.
Stage 1Read stateLoad the saved handoff
Read · state
The session starts by reading the file where the last session wrote down exactly where things stood, plus the standing list of loose ends, so you don't have to remember any of it.
Read STACK.md (the handoff), scan the standing follow-up backlog, and run an integrity check on the saved follow-up notes.
What happens
The orientation reads STACK.md: the canonical live state, where the previous /end-session wrote the handoff directly into the Current location section. There is no separate handoff file; the last session's handoff is that section. It then reads Standing-FUs.md, the cross-cutting follow-up backlog, scanning for any whose trigger may now have fired.
When the project defines the script, it runs npm run verify:fus as a read-only integrity report. A light project with no such script just reports its follow-up integrity as n/a. That check flags two things: anchor drift (an anchored follow-up whose cited code moved or was deleted, leaving a stale citation) and stale-home (a follow-up still homed at a CLOSED phase, meaning the close-time cleanup was skipped). The global scope file is skimmed only if STACK's current campaign is unclear.
Who acts
- Read, tool: Reads STACK.md and Standing-FUs.md verbatim: the live state and the cross-cutting backlog.
- ls (Bash), tool: Confirms STACK.md and Standing-FUs.md exist before relying on them.
- verify:fus, tool: Read-only integrity report: flags anchor drift and follow-ups homed at a closed phase. A bespoke Red Line check.
The rules
- Current location is the handoff. There is no separate handoff file. STACK's Current location section is what the last
/end-sessionwrote. To see the prior handoff, usegit show.:STACK.md - Scan standing follow-ups for fired triggers. Read
Standing-FUs.mdand check each trigger (an Nth caller now existing, or a date passed) that may have come due. - Integrity check is read-only.
verify:fusonly reports DRIFT and STALE-HOME lines; if it emits no summary the check itself may be broken and is run manually. - Skim global scope only if unclear.
docs/plans/2026-05-31-refactor-overview.mdis read only when STACK's current campaign can't be resolved from STACK alone.
In: Your invocation argument + the files on disk. Out: The loaded handoff, the standing backlog, and a follow-up integrity summary.
Stage 2Working tree + git divergenceCheck what git has done
Verify · git
Next it looks at git: whether you have uncommitted changes sitting around, and how far ahead your local work is of what's been published.
Capture the working-tree state, the commits ahead of origin, and the exact commit the session is sitting on.
What happens
Three git reads run in sequence. git status --porcelain captures whether the working tree is clean or carrying modifications. git log origin/main..HEAD --oneline lists commits that exist locally but haven't been pushed. git log -n 1 records the current HEAD's SHA and subject.
These three facts (tree state, push distance, and the exact HEAD) are the raw material for both the orientation brief and the conflict check that follows. If no upstream is configured the push-distance read is skipped and its absence is noted rather than treated as an error.
Who acts
- git status, tool: Reports the working tree as clean or a list of modified files.
- git log, tool: Lists unpushed commits and records the current HEAD SHA and subject.
The rules
- Porcelain for a stable read.
git status --porcelaingives machine-stable output: clean, or an explicit list of modified paths. - Count what's unpushed.
git log origin/main..HEAD --onelineenumerates commits ahead of origin; the count feeds the push-state line in the brief. - Pin the exact HEAD.
git log -n 1 --format="%H %s"records the SHA and subject the conflict check compares against. - No upstream is not a failure. If
origin/main..HEADcan't resolve, push-state checks are skipped and their absence is noted in the brief.
In: The current git repository state. Out: Working-tree status, unpushed-commit count, and the current HEAD SHA + subject.
Stage 3Multi-session conflict checkDid another session move things?
Verify · conflict
It then checks whether a different session committed work after the saved state was written, which would mean the handoff you're reading is already out of date.
Compare the commit that last wrote STACK.md against the actual HEAD. If they've diverged, a second session likely shipped since the last sync.
What happens
The check compares two SHAs: the commit that last touched STACK.md (git log -1 --format=%H -- STACK.md: the previous /end-session sync) and the actual HEAD from Stage 2.
If HEAD is ahead of the last STACK.md sync by commits not made in this session, another session probably committed since the last /end-session. That makes STACK's Current location potentially stale relative to what actually shipped. The pipeline surfaces a conflict warning and recommends re-reading the recent commit bodies before acting on the handoff.
Who acts
- git log, tool: Finds the SHA of the commit that last wrote STACK.md, to compare against HEAD.
The rules
- Two SHAs, one comparison. Last STACK.md-writing commit vs. actual HEAD. Equal means the handoff is current; HEAD ahead means a possible second session.
- Divergence raises a warning, not an edit. A detected gap surfaces a conflict warning in Stage 5. The command still changes nothing on disk.
- Commit bodies are the tiebreaker. When divergence is flagged, the recommendation is to re-read recent commit bodies before trusting the saved Current location.
In: The HEAD SHA from Stage 2 + the last STACK.md sync SHA. Out: A clean read, or a possible-multi-session-conflict signal for Stage 5.
Stage 4Output orientation briefPrint the self-contained brief
Output · brief
Now it prints the brief: global plan, active phase, where you left off, the lessons in force, and recent commits, echoed straight from the saved state so nothing gets reworded or misremembered.
Assemble one self-contained orientation brief, echoing STACK's sections verbatim rather than summarizing them.
What happens
The brief is emitted in a fixed structure: Global plan, the ACTIVE phase row, the full Current location block (Pipeline, Pending, Next move, Last commit), Push state, the FU integrity summary from Stage 1, the In-force lessons list, and any promotion candidates. Sections are echoed verbatim from STACK, not interpreted or summarized, because re-deriving from parent plans produces variance.
Below the brief, the last five commits are printed for grounding (git log --oneline -5). Promotion candidates are any in-force lessons carrying an [audits survived: 3+] tag, ripe for /consolidate-memory or a memory-file entry. Push state is read from STACK, or computed via git rev-list --count origin/main..HEAD if the field is missing.
Who acts
- Read (STACK.md), tool: Source of the verbatim brief sections: global plan, phase, current location, lessons.
- git log / git rev-list, tool: Supplies recent-commit grounding and a computed push count when STACK omits it.
The rules
- Echo verbatim, never summarize. Brief sections are copied from STACK as written. Interpreting them re-introduces the variance the command exists to remove.
- Fixed brief structure. Global plan → active phase → Current location → push state → FU integrity → in-force lessons → promotion candidates, in that order, every run.
- Promotion candidates surface themselves. Any lesson tagged
[audits survived: 3+]is listed as ripe for/consolidate-memoryor a memory-file entry. - Recent commits for grounding.
git log --oneline -5is appended below the brief so the state is anchored to real history.
In: The loaded state from Stage 1 + git facts from Stage 2. Out: A self-contained orientation brief plus the last five commits.
Stage 5Surface warningsFlag anything that looks off
Surface · warnings
Before handing back, it raises a plain warning line for anything that looks wrong: uncommitted changes, a possible second session, a broken link, a follow-up pointing at code that moved, or a batch of work that's ready to run.
Emit one plain warning line per inconsistency found: dirty tree, stale handoff, broken plan link, anchor drift, orphaned homes, or batch-ready clusters.
What happens
This stage runs the warning table against everything gathered so far. A dirty working tree, a HEAD ahead of the last sync, a detected multi-session conflict, a broken plan link, anchor drift, or an orphaned follow-up homed at a closed phase each emit a distinct ⚠️ line. Each names the exact files, paths, or counts involved.
It also raises 💡 opportunity lines: promotion candidates that have survived 3+ audits, a same-type follow-up cluster at batch threshold (/cluster-fus for the full bucketing), a standing follow-up whose trigger may have fired, push-eligibility at a phase close, or a STACK that appears complete and ready for a close ritual. Nothing here is acted on. Every line is information for you to decide on.
Who acts
- verify:fus, tool: Its DRIFT and STALE-HOME counts drive the anchor-drift and orphaned-home warnings.
- cluster-fus, tool: Named as the disposition path when a batch-ready follow-up cluster is flagged.
The rules
- One warning line per condition. Each applicable row in the table emits its own
⚠️or💡line, naming the exact files, paths, or counts. - Dirty tree warns, doesn't block.
⚠️ Working tree dirty:, surfaced, not auto-cleaned.. Resolve before starting new work. - Orphaned follow-ups must be re-homed. A follow-up at a CLOSED phase means the close-time GC was skipped; the warning routes it to
/cluster-fusbefore the home lies further. - Opportunities are flagged, not taken. Batch-ready clusters, promotion candidates, fired triggers, and push-eligibility are
💡hints. The command never executes them.
In: Every fact gathered in Stages 1–4. Out: A set of plain warning and opportunity lines, or silence if all is clean.
Stage 6Closing recommended actionOne recommended next move
Closing
Finally it ends with a single line: the one next move to make, lifted straight from where the last session said it left off, so you can start work immediately.
Append one recommended-action line, taken verbatim from STACK's Next move: the single thing to do first.
What happens
The orientation closes with a single action prompt: Ready to proceed. Recommended first action: followed by the Next move field copied verbatim from STACK's Current location. After this line you can begin work without manually re-reading STACK.md or recalling chat context.
This is the terminal feel of the whole pipeline, not a code ship, just ready to proceed. By satisfying CLAUDE.md's "restate before any context switch" mandate, the command leaves you oriented and pointed at exactly one next action.
Who acts
- Read (STACK.md), tool: Supplies the verbatim Next move that becomes the recommended first action.
The rules
- Exactly one recommended action.
Ready to proceed. Recommended first action:, a single line, copied verbatim, no menu. - Ready to proceed, not shipped. The closing feel is orientation complete. There is no commit, no diff, no state change to announce.
- Satisfies the restate mandate. The brief plus this line fulfill CLAUDE.md's "restate before any context switch" requirement in one pass.
In: STACK's Next move field. Out: A single recommended-first-action line ending the orientation.
Stage ✓Oriented: read-only, idempotentOriented, nothing written
Termination
The run ends with you fully oriented and not a single file changed, and because it only ever reads, running it again gives you the exact same answer.
By design the command writes nothing and is idempotent. Its only product is the brief, the warnings, and one next move in the chat.
What happens
By the end you have a self-contained orientation brief, recent commits for grounding, any warnings about state inconsistencies, and a single recommended next action, enough to start work without manually reading STACK.md or recalling chat context.
The whole pipeline is read-only: no file writes, no commits, no state changes. It is idempotent. Running it twice produces the same output. Its failure modes all exit cleanly with a plain instruction: no STACK.md means start a major effort with /brainstorm, /module-build, or /change-heavy; a malformed STACK means repair it or re-run /end-session; an unusual repo means verify git state before proceeding.
Who acts
- Read, Bash, tool: The command's only two allowed tools, both read-only; there is no write path.
The rules
- No writes, ever. No file edits, no commits, no state changes. The only output is text in the chat.
- Idempotent. Running
/start-sessiontwice on the same state produces identical output. - Failure modes exit cleanly. Missing STACK.md, a malformed STACK, or an unusual repo each print one plain instruction and stop, no half-state.
In: Whatever state the pipeline read. Out: An oriented session: brief, warnings, and one next move, zero files touched.