debrief

Session Debrief

You are producing a session debrief — a structured record of what happened during a workflow session. The debrief captures commits, task state changes, gate decisions, issues found, and observations. It feeds forward into the next session so the first officer starts with context instead of cold.

Follow these phases in order. Do not skip or combine phases.

---

Phase 1: Discovery

Launcher command invariant: Prefer ${SPACEDOCK_BIN:-spacedock} for Spacedock helper calls so an explicit front-door launcher remains the command source; when unset, fall back to spacedock on $PATH. Bare spacedock examples are shorthand for that expression.

Step 1 — Identify the workflow

The user may provide a workflow directory path as an argument. If they didn't, search for it:

1. Run ${SPACEDOCK_BIN:-spacedock} status --discover. It prints one resolved workflow directory path per line on stdout, scanning from the enclosing git repository root and pruning agent-managed worktrees (.claude/worktrees/) and other build/vendor noise.
2. If exactly one path is returned, use it as {dir}. If multiple, ask which one. If none, report "No Spacedock workflow found."

Store the confirmed path as {dir}.

Step 1b — Resolve the debrief home

The debrief home is not always {dir}. For a split-root workflow (its README declares a state: checkout) the established _debriefs/ history and the auto-syncing convention live in the state checkout, not the definition dir on the code branch. Let the binary tell you which it is rather than re-parsing state: yourself:

1. Run ${SPACEDOCK_BIN:-spacedock} status --boot --json --workflow-dir {dir} once and read three fields the binary already resolves: state_backend (single-root | split-root), entity_dir (the absolute resolved debrief home), and entity_dir_present.
2. Set {debrief_root} = entity_dir. Use {debrief_root}/_debriefs/ everywhere _debriefs/ appears below.

• state_backend == single-root → entity_dir is {dir}; debriefs read, write, and commit under {debrief_root}/_debriefs/ on the current branch (unchanged behavior).
• state_backend == split-root → set {state_checkout} = entity_dir (= {debrief_root}). Halt-gate: if entity_dir_present is false the declared checkout is NOT materialized (an orphan state branch with no linked worktree — a fresh clone or a removed worktree). HALT, report "state not initialized," and stop. Do NOT fall back to writing into {dir} on the code branch. Tell the captain to run spacedock state init (manual fallback: git fetch origin {state_branch} && git worktree add {state_checkout} {state_branch}), then re-run the debrief. Otherwise the reads, the new-file write, and the commit all run in the state checkout on its own branch — never in {dir} on the code branch. Resolve the state branch from the checkout itself: git -C {state_checkout} rev-parse --abbrev-ref HEAD.