--- name: workflow-retro description: > Records the outcome half of a feature's workflow evaluation at the end of a /feature session: which steps ran or were skipped, cycle counts, what each critic caught and what was adopted, plus a short judgment section. Writes one fixed-schema file per feature branch to .workflow-log/ (gitignored), including the session IDs the companion /workflow-inspect skill needs to append the cost half later. Run manually, optionally, at the end of a feature session. --- # /workflow-retro — Record the Feature's Workflow Outcome Run this skill at the end of a feature session — typically after the PR is opened (Step 9 of `/feature`), or when the feature is abandoned. It records what the workflow actually did for this feature: which steps ran, what each one caught, and what that changed. Over several features, these records are the evidence base for tuning the workflow — which steps earn their cost, which are candidates for skip rules. This is the **outcome half** of the record. The **cost half** (tokens per step, wall-clock, file-read overlap) is computed from the session transcripts by the companion `/workflow-inspect` skill and appended to the same file later. If that skill is not installed yet, the Cost section simply stays pending — nothing here depends on it. **Ground rules:** - **Facts come from artifacts.** Fill each field from the PR body, `git log`, and the plan/critique/review/QA outputs in this session — not from memory alone when an artifact exists. Anything not established is recorded as `unknown`, never guessed. - **The log is local evaluation data.** `.workflow-log/` is gitignored — never commit it or its contents, and never move it into the repo history. - **One file per feature branch.** If a file for the current branch already exists (a previous retro, or the feature spans multiple sessions), update it — fill gaps, correct facts, append the new session ID — instead of creating a duplicate. Exception: if the existing file evidently records a *different* feature that reused the branch name (its PR is already merged, or its dates are far from this session's), ask the user whether to replace it or pick another filename — do not merge two features into one record. - Writing the log file (and creating its directory) is the **only** mutation this skill performs. - The skill assumes a `/feature` session. In a session that ran only part of the workflow (an ad-hoc `/plan-draft`, a review-only pass), record what applies and mark the rest `n/a`. ## Step 1 — Locate the log target The log lives at `.workflow-log/.md` under the repository's **main worktree** — which is not necessarily the current directory: feature work often runs in a per-feature `git worktree` that is deleted once the PR merges, and the log must outlive it. Resolve the location with a single `git rev-parse --path-format=absolute --git-common-dir`: that prints the shared `.git` directory, whose **parent** is the main worktree root, and the log directory is `.workflow-log/` there (covered by the `.gitignore` entry `/init-workflow` adds). In a plain single-checkout clone this resolves to the repository root itself. Sanity-check the result: if the resolved parent path still contains a `.git` segment (e.g. the project is a git *submodule*, where the common dir lives under the outer repo's `.git/modules/`), the layout is unusual — ask the user where the log should live rather than writing there. `` is the branch name with `/` replaced by `-` (e.g. branch `feat/login-form` → `.workflow-log/feat-login-form.md`). Create the directory if missing. If the file already exists, this run updates it (see ground rules). ## Step 2 — Capture the session pointers `/workflow-inspect` runs in a later, different session that has no way to know which transcript was the feature session — recording the pointer now, while only this session knows it, is the point of this step. Transcripts are pruned after a retention window (Claude Code's `cleanupPeriodDays`, ~30 days by default), so the join must happen within it. Get the current session ID, in this order: 1. The `CLAUDE_CODE_SESSION_ID` environment variable (check with a single `printenv CLAUDE_CODE_SESSION_ID`). Its value is the session ID — the transcript is `.jsonl` somewhere under `~/.claude/projects/`. 2. If the variable is unset, fall back to a heuristic: the most recently modified `.jsonl` anywhere under `~/.claude/projects/` (a single `find`) is *probably* the current session — transcripts are filed under the session's *launch* directory, which is not necessarily the current worktree's, so search globally rather than deriving a directory from a path. If more than one transcript was modified in the last few minutes (concurrent sessions), ask the user which one is this session rather than picking silently. 3. If neither works — the variable is unset and the directory is missing or ambiguous — record `Sessions: unknown` rather than guessing. Both the variable and the on-disk layout are current, undocumented Claude Code behavior, not a stable interface; a wrong-but-plausible session ID silently corrupts the later cost-join, while an honest `unknown` merely skips it. If the feature spanned earlier sessions, record their session IDs too — ask the user if they can identify them (e.g. by date); otherwise record `earlier sessions: unknown`. Also record the **current worktree's absolute path** (the schema's `Project path` field) — context tying the record to the checkout the work ran in. The session ID is the load-bearing pointer: `/workflow-inspect` locates transcripts by a global search for `.jsonl`, never by deriving a directory from the recorded path. ## Step 3 — Fill the record Draft the file with exactly this structure (fixed schema — later tooling aggregates across files, so keep the headings and field labels verbatim): ```markdown # Workflow retro — - Date: - Branch: - PR: - Plugin version: - Sessions: - Project path: ## Steps | Step | Ran? | Notes | |------|------|-------| | 1a planner | yes / skipped / n/a | | | 1b plan-critic | yes / skipped / n/a | | | 1c approval | yes / n/a | plan revisions before approval: | | 2 implement | yes / n/a | deviations: minor, material | | 3 tests | yes / n/a | final full run: tests, | | 4–6 code review | yes / n/a | rounds: ; FAIL items: ; NEEDS_DECISION: | | 7–8 QA | yes / skipped / n/a | ; findings: | | 9 PR | yes / n/a | | ## Findings - plan-critic: findings; adopted into plan: ; discarded: - code-critic FAIL items, one line each: - NEEDS_DECISION items, one line each: - QA findings, one line each: ## Judgment - Did the planner's plan contain anything the implementer would not have found alone? - Which plan-critic findings changed the plan? - Did implementation re-read files the planner had already read? (best-effort — /workflow-inspect computes this exactly) - Did any step produce nothing of value this feature? ## Cost pending — run /workflow-inspect before the session transcripts are pruned ``` The Steps and Findings sections are factual — fill them from the artifacts. The Judgment section is the implementer's honest assessment — answer from what actually happened this session, in a sentence each; `unknown` is an acceptable answer. ## Step 4 — Confirm and write Present the drafted record in one block for the user to confirm or correct — the Judgment answers especially are theirs to override. Then write the file and report its path. Do not commit anything.