spacedock-dev/spacedock/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.

The debrief skill is user-invocable independent of a first-officer boot, so it cannot assume the checkout has converged — hence the explicit entity_dir_present gate before any git -C {state_checkout} operation.

Step 2 — Determine session boundaries

Check for an existing debrief to anchor the session start:

1. Look for {debrief_root}/_debriefs/*.md files. Sort by filename (lexicographic = chronological).
2. If a prior debrief exists, read the most recent one's YAML frontmatter and extract the last-commit field. The current session starts from the next commit after that hash.
3. If no prior debrief exists, fall back: use git log --oneline --reverse -- {dir} | head -1 to find the first-ever commit in the workflow directory, or use commits from the last 24 hours if the history is large.

Derive {from_commit} (the starting boundary). Run:

git log {from_commit}..HEAD --oneline -- {dir}

Present the session boundary to the captain:

Session boundary

Since: {from_commit} ({date or description})

Commits in scope: {count}

Adjust? (confirm or provide a different starting commit)

Wait for confirmation before proceeding.

Step 3 — Read workflow metadata

Read {dir}/README.md frontmatter to extract:

• Entity label and plural form
• Stage names and ordering
• Which stages are gates, have feedback-to, use worktrees

Phase 2: Extract Session Data

All extraction uses git and local files only — no external services.

2a. Commits

git log {from_commit}..HEAD --oneline -- {dir}
git log {from_commit}..HEAD --oneline

Run both — the first scoped to {dir} for entity-linked commits, the second unscoped to catch workflow-level commits (scaffolding edits, reverts, merge commits) that may live outside {dir}.

Split every commit into one of three buckets:

1. PR squash-merge commits — any commit whose message ends with (#NN) (GitHub's squash-merge pattern). These are the actual PR landings. They are rolled up into the Shipped section as a PR link — never enumerated individually.

1. pr-merge mod landing commits — commits with the pattern merge: {slug} done (PASSED) via PR #NN. These are Spacedock's post-merge state-transition commits emitted by the pr-merge mod after a PR lands. Use them in Phase 2b to resolve shipped entities to their PR numbers. Do NOT list them in the Non-PR section — the information is already captured by the Shipped section's PR link.

1. Non-PR commits — workflow-only commits worth surfacing that did not flow through a PR. Include commits with these prefixes:

• Scaffolding edits: docs:, debrief:, refit:
• Feedback cycles: feedback:
• Ideation stage reports: ideation:
• Mid-session scope updates: update: (entity scope changes, refactors to in-progress specs)
• Direct merges on main that bypassed the pr-merge mod (e.g. merge: {slug} done (PASSED) — direct merge from branch)
• Reverts: Revert ...

Suppress as routine state churn (do NOT list):

• dispatch:, advance:, state:, track: — normal stage-machine transitions; redundant with the Shipped section.
• seed:, file: — captured in the Filed section (2f).
• merge: {slug} done (PASSED) via PR #NN — captured in the Shipped section via the PR link.

Collect the surfaced commits into a list. For each, record the short hash, a compact description (derived from the commit message), and — where useful — a one-clause context note (e.g., "feedback cycle 2 on 116", "reverted in {hash}").

Consolidate adjacent related commits onto a single line when they share context. Examples:

• Feedback cycle commits on 116: \88fe41b\, \bf93c00\, \5306fa4\, \31abc13\ (cycle 1, cycle 1 addendum, cycle 2, cycle 2 addendum).
• Ideation stage-report commits on 121 and 125: \d0a7365\, \e1af6cf\.

If a commit was later reverted in the same session, mark it **[reverted]** and cross-reference the revert commit on the following line.

Record the first and last commit hashes of the full range for frontmatter.

Do NOT group all commits by entity slug — the old grouped-by-entity format is superseded.

2b. Task state changes (Shipped entities)

For each entity file in {dir}/*.md and {dir}/_archive/*.md, read the YAML frontmatter. Identify entities that reached a terminal/done state during this session by cross-referencing with commit messages containing done: / merge: ... done prefixes.

For each shipped entity, resolve the merged PR(s) by scanning the session commit log for the pr-merge squash pattern matching that entity's slug, or by looking at the merge: {slug} done (PASSED) via PR #NN commit. Extract the PR number(s).

Extract a one-sentence description from the entity body: read the entity file, locate the problem statement (the paragraph between the closing --- of the frontmatter and the first ## heading). Use the first sentence as the description. Fallback to the entity title if the problem statement is empty.

For each shipped entity, record:

• Entity ID (numeric, e.g. 115)
• Entity slug (backticked)
• PR number(s) with linked URL (see Phase 3 Step 4 for URL construction)
• One-sentence description

Emit one bullet per shipped entity in this format:

- **{id}** `{slug}` — [#{N}]({pr_url}). {one-sentence description}

If an entity shipped via multiple PRs (e.g. main + fixups), include all PR links inline:

- **{id}** `{slug}` — [#{N1}]({url1}) + [#{N2}]({url2}) fixups. {description}

2c. Gate decisions

Scan for gate-related activity:

• Entities that advanced past gated stages (approved gates)
• Entities that were rejected at gates (look for feedback-to cycles in commit messages or entity files with ### Feedback Cycles sections)
• Extract reasoning from stage reports where available

2d. Issues found

Scan for issues:

• Commits with fix: prefix in the workflow directory
• Entity files whose ## Stage Report sections contain FAIL items
• Any notable problems mentioned in stage reports

Categorize each issue into two buckets:

1. Workflow-specific — bugs or quirks in the user's pipeline (their stages, entities, agent instructions). These stay as local notes in the debrief.
2. Spacedock issues — bugs or limitations in the spacedock framework itself (first-officer template, commission skill, status script, ensign behavior, agent platform issues). These are candidates for GitHub issue filing.

2e. What's next

Extract the dispatchable list and overall workflow view via spacedock status:

spacedock status --workflow-dir {dir} --next
spacedock status --workflow-dir {dir}

If spacedock status is unreachable, raise the error to the captain rather than working around it — the first officer already invoked spacedock status --boot to start the session, so an unreachable launcher here indicates a real environmental problem worth surfacing.

Use the status output to populate:

• Entities blocked at gates (waiting for captain)
• Entities with non-empty worktree field (in-progress or orphaned)
• Overall workflow state

2f. Filed entities (new backlog seeds)

Scan the session commit log for new entity files created during this session. Look for commits with prefix seed: or file: in {dir}:

git log {from_commit}..HEAD --oneline -- {dir} | grep -E '^[a-f0-9]+ (seed|file):'

For each newly-filed entity, read the entity file and extract a one-sentence description from the problem statement (same method as 2b). Emit one bullet per filed entity:

- **{id}** `{slug}` — {one-sentence description}

If a filed entity also shipped in the same session (appears in both 2b and 2f), still list it in both sections — the Filed section documents what was added to the backlog, the Shipped section documents what landed.

Phase 3: Draft and Review

Step 1 — Collect the agent testimonial

Ask the driving agent:

Before answering, self-identify as the agent driving this session:

- Harness/runtime: the agent harness or runtime you are operating in (for example Claude Code, Codex, or Pi).

- Model: the model name.

- Model version/build: the exact version or build when runtime metadata exposes it.

Write unknown for any identity field you cannot verify; do not infer or guess. Then, setting the project's subject matter aside: how would you describe the experience using Spacedock versus driving the same work without it? Be honest about friction, costs, or places where the workflow got in your way; this is not a request for praise.