T-0XV0-orchestrated-sub-agent-design-call-gap

Status: closed/superseded · Impact: medium · Complexity: medium

Goal

A /sdlc:task-work sub-agent dispatched by /sdlc:orchestrate (or any other parent agent driving via the verdict-line contract) cannot call AskUserQuestion — it has no available channel to surface a real design decision the spec didn’t pin down. The sub-agent’s only choices are: guess, or BLOCK. Guessing risks shipping the wrong implementation; blocking burns a context-switch and an orchestrator tick. A pre-implementation pass that surfaces open design questions to the user before the sub-agent commits to a path would catch these cheaply.

Today

/sdlc:task-work Step 6 briefs an implementation sub-agent and turns it loose. The sub-agent reads the spec and implements. If the spec is silent on a real design choice — e.g. “introduce lefthook” when lefthook isn’t installed and the operator could equally choose a plain .git/hooks/pre-commit script — the sub-agent has to pick unilaterally. When the parent dispatching /sdlc:task-work is /sdlc:orchestrate (or any other autonomous flow), there is no AskUserQuestion path back to the human.

Surfaced by post-mortem of T-1CL4-worktree-scope-guard-pre-commit: the task said “introduce lefthook”, lefthook wasn’t installed, and the sub-agent had to commit to “ship the lefthook.yml anyway and document the install requirement” without being able to ask whether a plainer .git/hooks/ script would have been preferred.

/sdlc:task-ensure-ready already runs against the spec before implementation starts, but it checks structural completeness (sections present, paths cited, ACs objective) — it does NOT surface “here are the implementation choices the spec leaves open” to the operator.

Proposed

A pre-implementation pass — a new /sdlc:task-work Step 5c, after Step 5b’s start-commit and before Step 6 briefs the implementing sub-agent — that reads the spec, identifies open design choices, and presents them to the operator via AskUserQuestion BEFORE launching the implementing sub-agent. The pass runs in the parent session (which still has AskUserQuestion); the captured decisions become part of the brief handed to the sub-agent. When the parent is itself orchestrated and has no AskUserQuestion, the pass is a no-op (the orchestrated path accepts the sub-agent’s best guess as the cost of unattended operation).

The pass’s output is appended to the task body as a ## Pre-flight decisions section so it’s auditable in the PR diff and so re-runs of the same task can skip the question.

Approach

1. Add a hidden task surface-design-questions registry op in the task entity package (deterministic helpers land as registry ops, per D-H7FS-op-substrate-surface) that reads a task file and emits a JSON array of {question, options[]} objects derived from prose heuristics: “introduce X”, “either A or B”, “the implementer should decide” phrasings. Conservative — false positives are worse than misses since each one becomes an AskUserQuestion the operator has to answer.
2. Wire it into /sdlc:task-work as a new Step 5c, between Step 5b’s start-commit and Step 6’s sub-agent brief. When the op emits any questions AND AskUserQuestion is available, call it; append the chosen options to the spec under a new ## Pre-flight decisions H2; commit on the task branch with subject docs(tasks): pre-flight decisions for <basename>.
3. When AskUserQuestion is unavailable (orchestrated dispatch), log the surfaced questions to stderr but proceed; the sub-agent’s post-mortem will record any guess it had to make.
4. Document the contract in apps/sdlc/skills/task-work/SKILL.md and the op’s descriptor summary.

Files to touch

Location	Kind	Change
apps/sdlc/lib/model/entities/task/ops/surface-design-questions.ts	new	hidden op: heuristic scan of a task body emitting {question, options[]} JSON
apps/sdlc/skills/task-work/SKILL.md	modify	insert the new Step 5c between Step 5b and Step 6
apps/sdlc/lib/model/entities/task/body-template.eta	modify	add the optional ## Pre-flight decisions H2 to the documented body shape

Acceptance criteria

• AC-1: sdlc task surface-design-questions against a task spec containing “introduce lefthook” emits a question whose options include both “lefthook” and “plain git hook”.
• AC-2: /sdlc:task-work invoked interactively against a task that triggers AC-1 prompts the operator via AskUserQuestion before launching the implementing sub-agent.
• AC-3: /sdlc:task-work invoked from /sdlc:orchestrate against the same task does NOT prompt (no AskUserQuestion available) and logs the surfaced questions on stderr.

Out of scope

• A full design-doc generator. This is a lightweight heuristic, not a planning assistant.
• Retroactive prompts for in-flight tasks; the pass only fires on fresh starts.

Dependencies

• none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-1CL4-worktree-scope-guard-pre-commit on 2026-05-21.

---

← Back to Tasks