/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).
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.

Phase 3 — Synthesis + Redact + Emit

1. For recap-scoped: dispatch to Codex via mcp__codex__codex (first turn) or mcp__codex__codex-reply (subsequent turns). Prompt must follow @rules/codex-invocation.md — independently research, no leading conclusions. See references/qa-prompt.md.
2. Lazy-fetch is gated: Codex may Read only files listed in the recap §7 Evidence. Out-of-allowlist reads are refused; fall back to emitting a citation-only answer.
3. Run the complete response through scripts/security-redact.js → redact(text). On AbortError (high-confidence secret) emit the fingerprint and refuse to respond.
4. Emit the redacted answer with inline file:line citations. Every claim about code must cite a recap-evidenced location.

Phase 4 — Promote (end of session)

When the user signals session end (e.g. /recap-ask --end or an explicit "結束" / "done"):

1. Prompt via AskUserQuestion: "Promote this Q&A thread to the existing request ticket so the context survives for future sessions?"
2. On Yes: resolve the parent request doc from the recap's feature_context.docs_path. Invoke /create-request --update <request-path> with a Q&A digest appended under a new ## Follow-up Q&A (<date>) heading.
3. On No: emit the thread id so the user can resume later via --continue.

Performance

Target: NFR-3 — Q&A first-token p95 ≤ 10s (excluding external LLM network latency, measured from question receipt to first emitted token). Phase 1 context load should be cached across turns within the same thread.

Path Security

Output Format

Each Q&A turn emits:

### Q: <user question>

**Intent**: recap-scoped | out-of-scope | ambiguous

**Answer**:
<synthesized text with inline `file:line` citations>

**Sources**:
- `<path>:<line>` — <what this ref demonstrates>
- ...

**Thread**: <codex threadId>   <!-- enables --continue -->

On session end, append:

### Promote?

Promote this Q&A thread to `<parent-request-path>` so the context survives future sessions? (y/N)

Verification

• --context path validated against repo-or-tmp allowlist before any read (NFR-8)
• Recap doc loaded in full; §7 Evidence extracted as the lazy-fetch allowlist
• Intent classification emits exactly one of recap-scoped / out-of-scope / ambiguous
• Out-of-scope path emits the fixed redirect block — no Codex call
• security-redact.js run on every outbound response (NFR-7)
• Codex prompt follows @rules/codex-invocation.md (independent research mandate)
• First-token p95 ≤ 10s from receipt (NFR-3)
• Promote prompt at session end; /create-request --update call on Yes (AS-11)