/recap-doc

name: recap-doc
description: "Post-development recap document generator. Use when: AI/Codex has implemented a feature and the user needs a guided walkthrough of what changed and why, with blind-spot detection and anticipated questions. Not for: Q&A follow-up (use /recap-ask), technical share-out for teammates (use /tech-brief), or generic code explanation (use /codex-explain). Output: briefing-recap-<YYYY-MM-DD>.md with file-level walkthrough, design intents, spec drift, blind spots (mandatory), and anticipated questions."
allowed-tools: Read, Grep, Glob, Write, Bash(git:*), Bash(node:*), Skill

`/recap-doc` — Recap Document Generator

Trigger

• Keywords: recap-doc, generate recap, 產出導覽文件, walkthrough doc, 本輪導覽

When NOT to Use

| Scenario | Alternative | |----------|------------| | Interactive Q&A over an existing recap | `/recap-ask` | | Full flow (detect + doc + Q&A) | `/post-dev-recap` wrapper | | Technical share-out for other developers | `/tech-brief` | | Single function explanation | `/codex-explain` | | First-principles reasoning of an existing doc | `/fp-brief` |

Command Signature

/recap-doc --scope <json-path-or-inline> [--focus <str>] [--depth brief|normal|deep] [--output <path>]

| Flag | Default | Description | |------|---------|-------------| | `--scope` | required | Path to ScopeReport JSON or inline JSON string (from `scripts/detect-scope.js`) | | `--focus` | `""` | Natural-language keyword to bias section emphasis (e.g. `"auth middleware"`) | | `--depth` | `normal` | Output depth — affects top-N, section verbosity, and optional sections | | `--output` | auto | Output file path (see Save Behavior) |

Workflow

sequenceDiagram
    participant U as Caller (user or /post-dev-recap)
    participant D as /recap-doc
    participant S as scripts/detect-scope.js
    participant T as tech-brief-style collection
    participant CE as /codex-explain (Skill)
    participant SR as scripts/security-redact.js
    participant F as Output file

    U->>D: /recap-doc --scope <json> [--depth]
    D->>D: Phase 1: Load & validate ScopeReport
    D->>T: Phase 2: Collect git evidence for scope.files (reuse tech-brief Stage 2)
    D->>D: Phase 3: Cross-reference tech-spec (if feature_context.has_tech_spec)
    D->>CE: Phase 4a: Explain top-N changed files
    D->>D: Phase 4b: Synthesize sections + Blind Spots (Must) + Anticipated Questions
    D->>SR: Phase 5a: Scan output for high/medium-confidence secrets
    SR-->>D: Redacted or AbortError
    D->>F: Phase 5b: Write briefing-recap-<date>.md
    D-->>U: Emit output path + summary

Phase 1 — Scope Load

1. Parse `--scope` argument: accept file path, `-` for stdin, or inline JSON (detected by leading `{`). 2. Validate ScopeReport v1 required fields: `version === 1`, `source`, `files[]`, `feature_context`, `fallback_trace`. 3. If `source === null` or `files.length === 0` → exit non-zero with message directing user to rerun `scripts/detect-scope.js`.

Phase 1b — `scan_error` gate

**`scan_error` gate.** `scan_error !== false` ⇒ the source sets are **unknown, not empty** — report it and take the ⚠️ Need Human exit rather than composing a recap from sources you could not enumerate. Gate on `!== false`, not `=== true`: a `{}` payload from a shell fallback 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.

This skill reaches the source sets through `@skills/tech-brief/references/source-guide.md`, which it loads as its own Phase 2 strategy. Loading a reference is loading what it instructs: there is no reading of that link under which the sets are described but not consumed, so the gate is owed here exactly as it is in the skill that owns the file.

Phase 2 — Evidence Collection (reuse tech-brief Stage 2)

See `references/source-guide.md` for the full strategy. Summary:

• Run `git log --oneline -20 -- <path>` per scope file (capped at `top-N` by depth)
• Run `git diff --stat <base-ref>..HEAD -- <path>` for magnitude
• Read top-N changed files (100 lines each, source files only; exclude docs/test)

Top-N by depth: **brief=5, normal=10, deep=15**.

Phase 3 — Spec Cross-reference

When `scope.feature_context.has_tech_spec === true`:

1. Read `<docs_path>/2-tech-spec.md` 2. Extract section headings + Work Breakdown items 3. Prepare drift-check input: list each tech-spec work item + implementation evidence (changed files overlap)

Phase 4 — AI Synthesis

See `references/prompt-template.md` for the full prompt. Key behaviors:

1. **Per-file explanations (Phase 4a)**: for each top-N file, invoke `/codex-explain` (Skill tool call) with `--lines` scoped to changed hunks. **Reuse, not reimplement** — this satisfies NFR-5. 2. **Section synthesis (Phase 4b)**: compose §1 Overview through §7 Evidence using the output template (see `references/output-template.md`). 3. **Blind Spots (FR-9, Must — any depth)**: even if no obvious blind spots are found, emit the §5 heading with the fallback wording `「本輪未偵測到明顯盲點」+ 推論依據`. 4. **Anticipated Questions (FR-11)**: present ≥ 3 questions at `normal`/`deep`; omit at `brief`.

Phase 5 — Redaction + Write

1. Load `scripts/security-redact.js` and invoke `redact(text)` on the complete markdown output. 2. If `AbortError` is thrown → do **not** write; emit stderr with fingerprint and exit non-zero. 3. If redacted successfully → validate output path via `fs.realpathSync` on the first existing ancestor (must resolve inside repo root **or** `<tmp>`; no `..` / external symlink). 4. Write file with trailing newline.

Depth Levels

See the full matrix in `references/output-template.md`. Summary:

| Level | Top-N | §5 Blind Spots | §6 Anticipated Q | Code snippets | |-------|-------|----------------|-------------------|---------------| | brief | 5 | Top-3 only | Omitted | No | | normal | 10 | Full list | ≥ 3 | No | | deep | 15 | Full list | ≥ 3 | Inline |

Save Behavior

Recap ou