Post Dev Recap

/post-dev-recap — Guided Post-Development Recap

Trigger

• Keywords: post-dev-recap, 開發後導覽, walkthrough after dev, recap workflow, 本輪回顧

When NOT to Use

Positioning vs /ask, /tech-brief, /fp-brief, /code-explore (AS-5)

Command Signature

/post-dev-recap [<focus>] [--interactive] [--depth brief|normal|deep]

FR-4 Must — Q&A is mandatory. This wrapper has no --no-qa flag. Callers that only want the markdown must invoke /recap-doc directly. See the Q&A Gate (FR-4 Must) section below for the design rationale.

Prohibited Actions (AS-6)

❌ git add | git commit | git push | git stash | git reset — all git mutations are forbidden

This wrapper reads git state (git status, git diff, git log) for scope detection only. It never creates commits, pushes, or alters the working tree. See @rules/git-workflow.md.

Workflow

sequenceDiagram
    participant U as User
    participant W as /post-dev-recap
    participant S as scripts/detect-scope.js
    participant D as /recap-doc
    participant A as /recap-ask

    U->>W: /post-dev-recap [<focus>] [--interactive] [--depth ...]
    W->>W: Phase 0: Parse args + resolve CWD = git repo root
    W->>S: Phase 1: node scripts/detect-scope.js (no args)
    alt source === null (scope detection failed)
        S-->>W: ScopeReport with source: null + fallback_trace[]
        W-->>U: ⚠️ Need Human + fallback_trace + suggest manual /recap-doc --scope
        Note over W: exit non-zero — do NOT invoke sub-skills
    else source resolved
        S-->>W: ScopeReport v1 JSON
        opt --interactive
            W->>U: AskUserQuestion — "Scope detected (<N> files). 繼續 (continue) / 提問 (ask) / 跳段 (skip) / 結束 (end)?"
            U-->>W: 繼續 (continue) | 提問 (ask) | 跳段 (skip) | 結束 (end)
            Note over W: ask=prompt the user to phrase a clarifying question about the scope, echo answer, then re-prompt. skip=skip /recap-doc, jump to Phase 3 with user-supplied recap path. end=stop.
        end
        W->>D: Phase 2: /recap-doc --scope <json> [--focus <focus>] [--depth <d>]
        D-->>W: briefing-recap-<date>.md path (ephemeral default = <tmp>/sd0x-dev-flow-recap/)
        opt --interactive
            W->>U: AskUserQuestion — "Recap ready at <path>. 繼續 (continue) / 提問 (ask) / 跳段 (skip-qa-end) / 結束 (end)?"
            U-->>W: 繼續 (continue) | 提問 (ask) | 跳段 (skip-qa-end) | 結束 (end)
            Note over W: "skip-qa-end" is the only documented FR-4 bypass — explicit user consent, logged.
        end
        W->>A: Phase 3: /recap-ask --context <recap-path>  (FR-4 Must — non-interactive flow)
        loop Q&A turns (until user ends)
            U->>A: <question>
            A-->>U: answer + Sources + Thread
        end
        A-->>W: Thread id + promote outcome
        W-->>U: Summary: recap path, thread id, promote status
    end

Phase 0 — Arg Parsing

1. Treat the first positional non-flag argument as <focus>; subsequent positional args are a warning (extra args ignored with stderr note).
2. Resolve CWD to the git repo root via git rev-parse --show-toplevel. If the command is not run inside a git repo, emit ⚠️ Need Human — /post-dev-recap must run inside a git repository. and stop.
3. Validate --depth ∈ {brief, normal, deep}. Reject unknown values.

Phase 1 — Scope Detection (T1 reuse)

1. Invoke node scripts/detect-scope.js with no additional args (it auto-detects source: uncommitted → branch → session → null).

2. Parse stdout as JSON (ScopeReport v1). Validate version === 1.

3. Scope-fail path (AS-6 exit): if source === null OR files.length === 0, emit:

   • ⚠️ Need Human — scope detection inconclusive
   • The full fallback_trace array (why each heuristic failed)
   • Suggested manual command: /recap-doc --scope <explicit-json>
   • Exit before invoking Phase 2. 3b. scan_error gate: feature_context.scan_error !== false ⇒ the source sets behind the scope are unknown, not empty — report it and take the ⚠️ Need Human exit rather than recapping a change whose feature corpus could not be enumerated. detect-scope.js projects the field onto feature_context for exactly this check. Gate on !== false, not === true: a payload from a shell fallback or an older producer carries no such field at all, and a non-null key is not evidence the sets are complete — scan_error rides alongside a resolved key.

4. Interactive hook (opt-in): when --interactive is set and scope resolved, call AskUserQuestion with the scope summary (<N> files, source=<s>, confidence=<c>) and the 4-option set {繼續 (continue), 提問 (ask), 跳段 (skip), 結束 (end)}. ask = prompt the user for a clarifying question about the detected scope, echo the answer, then re-prompt the 4-option set. skip = skip /recap-doc and jump to Phase 3 (requires the user to supply an existing recap path). end = stop cleanly without invoking sub-skills.

Phase 2 — Recap Doc (T2 reuse)

1. Serialise the ScopeReport to a temp file (or pipe via stdin) and invoke /recap-doc --scope <path> [--focus <focus>] [--depth <depth>] via the Skill tool.
2. Capture the output recap path. The default is ephemeral under <tmp>/sd0x-dev-flow-recap/briefing-recap-<YYYY-MM-DD>.md (see @skills/recap-doc/SKILL.md ## Save Behavior).
3. On /recap-doc failure, surface its stderr verbatim and exit — do not silently fall through.
4. Interactive hook: when --interactive, call AskUserQuestion with the recap path and the 4-option set {繼續 (continue), 提問 (ask), 跳段 (skip-qa-end), 結束 (end)}. ask = prompt the user for a clarifying question about the recap doc itself (not a Q&A turn — that belongs in Phase 3), echo the answer, re-prompt. skip-qa-end is the only documented FR-4 bypass — explicit user consent, flagged in session log. end closes the session immediately after the doc is written.