debrief

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
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

```bash
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.

2. **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.

3. **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.

From spacedock-dev/spacedock, Apache-2.0.

More from spacedock-dev/spacedock