/post-dev-recap

name: post-dev-recap
description: "Post-development recap wrapper. Use when: AI/Codex just finished implementing a feature and the user wants a guided walkthrough with scope detection + doc generation + follow-up Q&A. Not for: generating only a doc (use /recap-doc), Q&A over an existing recap (use /recap-ask), technical share-out (use /tech-brief), first-principles reasoning of an existing doc (use /fp-brief), general code tracing (use /code-explore). Output: ScopeReport → briefing-recap-<date>.md → interactive Q&A session."
allowed-tools: Read, Grep, Glob, Write, Bash(node:*), Bash(git:*), Skill, AskUserQuestion

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

Trigger

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

When NOT to Use

| Scenario | Alternative | |----------|------------| | Only need a doc (no Q&A) | `/recap-doc` — emits the recap markdown and stops | | Have an existing recap, want to ask questions | `/recap-ask --context <path>` | | Share-out for other developers (not the author) | `/tech-brief` — focuses on knowledge transfer to strangers | | First-principles reasoning of an existing doc | `/fp-brief` — explains *why* decisions hold | | General project Q&A, no recent change | `/ask` — reopens the whole repo as context | | Deep code tracing across modules | `/code-explore` — execution-path walker |

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

| Dimension | `/post-dev-recap` | `/ask` | `/tech-brief` | `/fp-brief` | `/code-explore` | |-----------|-------------------|--------|----------------|-------------|-----------------| | **Trigger** | Right after AI/Codex finishes a feature | Any quick question | Share-out for teammates | Explain an existing doc | Diagnose unknown code | | **Input** | ScopeReport (detected live) | Free-form question | A finished feature | A document | A code question | | **Output** | Recap doc + Q&A session | Answer | Brief artifact | First-principles chain | Execution-path report | | **Bounded?** | Yes — scope of the just-done change | No — whole repo | No — whole feature | Document-scoped | Free search |

Command Signature

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

| Flag | Default | Description | |------|---------|-------------| | `<focus>` | `""` | Natural-language keyword to bias section emphasis, passed to `/recap-doc --focus` | | `--interactive` | false | Enable per-step `AskUserQuestion` — user can choose one of 4 actions between phases: **繼續 (continue)** / **提問 (ask)** / **跳段 (skip)** / **結束 (end)** | | `--depth` | `normal` | Recap depth — `brief` / `normal` / `deep`, passed to `/recap-doc --depth` |

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