Recap Ask

/recap-ask — Recap-Bounded Q&A

Trigger

• Keywords: recap-ask, ask about recap, 追問 recap, follow-up on recap, 本輪問答

When NOT to Use

Command Signature

/recap-ask <question> --context <recap-doc-path> [--continue <threadId>] [--lazy-fetch]

Workflow

sequenceDiagram
    participant U as Caller (user or /post-dev-recap)
    participant A as /recap-ask
    participant R as Recap doc
    participant C as Codex
    participant SR as scripts/security-redact.js
    participant CR as /create-request

    U->>A: /recap-ask "<q>" --context <path>
    A->>A: Phase 1: Validate path + load recap as primary context
    A->>A: Phase 2: Intent classification → {recap-scoped, out-of-scope, ambiguous}
    alt recap-scoped
        A->>R: Lazy-fetch file:line refs (bounded by recap Evidence)
        A->>C: Codex synthesis with recap as primary
    else out-of-scope
        A->>A: Emit "此問題超出本輪 recap 範圍" + /ask example
    else ambiguous
        A->>U: AskUserQuestion to clarify intent
    end
    A->>SR: Phase 3: Redact response
    SR-->>A: Redacted text (abort on high-confidence secret)
    A->>U: Emit answer with file:line citations
    opt End of session
        A->>U: Prompt: "Promote this Q&A to a request ticket?"
        U-->>A: Yes
        A->>CR: /create-request --update <existing> (append Q&A digest)
    end

Phase 1 — Context Load

1. Validate --context path: resolve relative paths against repo root (git rev-parse --show-toplevel).

2. Enforce path boundary (NFR-8) on --context: resolved real path must satisfy startsWith(repo_root + "/") or live under <tmp> (same allowlist as /recap-doc Path Security — users who moved the recap out of sd0x-dev-flow-recap/ must still land within tmp). Reject .. segments and external symlinks (use fs.realpathSync on the first existing ancestor).

3. Read the recap file in full; this is the primary context. Extract the §7 Evidence file-index as the lazy-fetch allowlist.

4. Validate every Evidence entry before adding to the allowlist: apply the same boundary check to each <path>:<line> in §7 — the canonical (realpath-resolved) target must satisfy startsWith(repo_root + "/") or lie inside <tmp> (i.e. repo-or-<tmp>, identical to step 2), with .. segments and external symlinks rejected. Entries that fail validation are silently dropped from the allowlist (a recap cannot smuggle out-of-repo paths into Phase 3 reads). 4b. scan_error gate: read the recap's > **Corpus scan**: metadata line (written by /recap-doc from feature_context.scan_error). Only the exact value complete proceeds. Every other reading takes the ⚠️ Need Human exit, and each one takes it on its own account:

   Marker	Reading	Consequence
   complete	the recap records scan_error === false	proceed to Phase 2
   unknown	the recap records scan_error !== false — the source sets behind it are unknown, not empty	say so, ⚠️ Need Human exit
   absent	the recap predates the field, so nothing was recorded either way	say so, ⚠️ Need Human exit
   anything else	an unrecognised producer wrote it; the value means nothing here	say so, ⚠️ Need Human exit

   The absent row is the one that reads as pedantic and is not. Silence is the default state of every recap written before the marker existed, so "warn and answer anyway" is not a lenient reading of one edge case — it is the fail-open path for the whole back catalogue, and it is precisely the misreading the marker was added one document upstream to close. An answer built on an evidence index whose corpus completeness is unknown is the failure, whether the recap said unknown or said nothing.

   Gate on !== false, not === true, and on === 'complete' rather than "not unknown": 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.

5. If the recap is older than 7 days, warn the user — recaps are ephemeral by default and the source code may have drifted. The 7-day threshold is a heuristic; callers may override in future versions.

Phase 2 — Intent Classification

Classify the question into one of three classes before synthesis. See references/qa-prompt.md for full prompt + decision rules.

Out-of-scope redirect block (verbatim template — keep concise):

此問題超出本輪 recap 範圍。建議改用 /ask "<原始問題>"，它會從整個專案重新收集上下文。

Follow-up turns on the same thread (--continue <threadId>) re-run classification per new question — the prior turn's class does not carry over. The Codex reply-turn prompt in references/qa-prompt.md enforces this.