clarifying-assumptions（澄清假设）

Clarifying Assumptions

This skill is the conversation layer for workflow orchestration. It accepts a TICKET_KEY that can be a Jira ticket key (JNS-6065) or a GitHub issue slug (acme-app-42). The orchestrator does exactly three things: think about the current question and the developer's reasoning, decide what to ask or defer next, and dispatch subagents for artifact reading, critique generation, manifest assembly, and file updates. critique-analyzer writes its full report to a workflow artifact before manifest assembly so the orchestrator carries only summaries, manifest rows, and artifact paths instead of raw planning content.

Inputs

<KEY> in path examples below is the same value as TICKET_KEY.

The main task plan must already exist at docs/<TICKET_KEY>-tasks.md. The required plan sections and artifact contracts are part of this skill's preconditions and are defined below.

When MODE=critique, these per-task artifacts must also exist:

• docs/<KEY>-task-<N>-brief.md
• docs/<KEY>-task-<N>-execution-plan.md
• docs/<KEY>-task-<N>-test-spec.md
• docs/<KEY>-task-<N>-refactoring-plan.md

The skill derives these additional subagent handoff inputs from the top-level inputs:

Input and Output Contracts

Input contract

The main plan file at docs/<TICKET_KEY>-tasks.md must contain these sections:

Additional upstream artifacts:

• MODE=upfront: docs/<KEY>-stage-1-detailed.md, docs/<KEY>-stage-2-prioritized.md
• MODE=critique: task brief, execution plan, test spec, and refactoring plan

These sections and upstream artifacts are required input preconditions for the skill. This skill requires only the paths above plus readable markdown at those locations.

Output contract

This skill updates orchestration artifacts only. It does not produce implementation code.

These are orchestration artifacts. Keep them out of version control.

Final summary contract

Every successful run ends with a concise final summary that includes at minimum these fields in a stable shape:

• Critique artifact: <path>
• Files updated: <path list or ->
• RE_PLAN_NEEDED: <true|false>
• BLOCKERS_PRESENT: <true|false>

If clarification stops early because a subagent returned BLOCKED, FAIL, or ERROR, still emit the same minimum fields with Files updated: - plus the blocking verdict and reason.

Canonical Pipeline Stages

Use the same stage names and ordering regardless of whether the caller is a Jira workflow or a GitHub workflow.

Manifest preview belongs inside Stage 4. Final user-facing recap belongs inside Stage 5 after the recorder returns. Do not invent extra pipeline stages for those two presentation steps.

Pipeline / Workflow Overview

Subagent Registry

How This Skill Works

Keep only these items inline while the skill is running:

• The current manifest item
• The developer's response
• The accumulated decision list
• The RE_PLAN_NEEDED flag
• The BLOCKERS_PRESENT flag
• The active critique artifact path

Everything else comes from delegated subagents through concise verdicts, manifest rows, and artifact paths. The manifest is the source of truth for what gets asked once execution starts, but critique-analyzer is the source of truth for whether a concern still needs to be raised at all in the current run.

MODE=upfront is the plan-wide clarification pass and MODE=critique is the per-task clarification pass just before execution. The mode names, inputs, and artifact paths are the runtime contract; any parent-workflow phase numbers are outside this skill's contract.

On retries or later iterations, re-dispatch each subagent with the current artifact paths and inputs. Do not treat prior subagent output as authoritative state once the underlying artifacts or decisions have changed.

Manifest IDs and wording can drift between iterations. Because of that, critique-analyzer must re-read the Decisions Log every run and decide by substance whether a candidate question has already been answered. Do not leave that judgment to Stage 3.

Run the workflow in this order:

1. Stage 1 Load guidance: load the design-thinking reference and the current mode's playbook.
2. Stage 2 Analyze artifacts: dispatch critique-analyzer to read artifacts, consult the current Decisions Log, inspect the codebase, search the web, and write the critique artifact. Always include PRIOR_DECISIONS_FILE and PRIOR_DECISIONS_KIND, even on ITERATION=1.
3. Stage 3 Build manifest: dispatch question-manifest-builder with the critique artifact path and the plan path to build the ordered manifest. In MODE=critique, also include TASK_NUMBER and CURRENT_TASK_ARTIFACTS. If the manifest returns Questions now: 0, treat that as a valid no-op and skip directly to Stage 5 without emitting a placeholder prompt.
4. Stage 4 Clarify inline: walk the manifest one question at a time inline, deciding what to confirm, revise, defer, or block. Carry each manifest Item ID unchanged into the decision list so later recording and plan annotations stay traceable.
5. Stage 5 Record decisions: dispatch decision-recorder with the resolved decisions and let it update the workflow artifacts plus validate the result. Include ITERATION and IMPLEMENTATION_UPDATES when present. In MODE=upfront, also include DEFERRED_QUESTIONS. In MODE=critique, also include TASK_NUMBER, TASK_TITLE, RESOLVED_IRRELEVANT, and any new DEFERRED_QUESTIONS created during the discussion.

The inline questioning loop uses two reasoning patterns:

• Model A — Socratic. Used only for Tier 3 problem-framing hard gates. The developer answers first, then sees the critique.
• Model B — evaluate the reasoning. Used for all other items. Present the original decision, the critique, and ask the developer whether the reasoning holds up.

Reference Loading

Read ./references/design-thinking-mindset.md first for both modes.

Then load only the mode-specific playbook for the active run:

Behavioral Guardrails

1. Ask one question per message.
2. Ask only from the manifest; if a new item emerges, add it before asking it.
3. Defer future-task questions instead of speculating about them now.
4. Be direct about shallow thinking on Tier 3 items, but keep the tone mentor-like.
5. Present every critique item; do not silently accept a subagent recommendation.
6. Respect skip only for Tier 2 items. Tier 3 hard gates cannot be skipped. Tier definitions come from ./subagents/critique-analyzer-rubric.md.
7. When the interface supports structured choices, use them for discrete options; otherwise use numbered options.
8. Keep question blocks scannable. Use tables or diagrams only when they clarify a real trade-off.

Escalation

Expect parseable verdicts from subagents and route them like this:

Example

<example>
Input: TICKET_KEY=JNS-6065, MODE=upfront, ITERATION=1

1. Read `./references/design-thinking-mindset.md`
2. Read `./references/upfront-mode.md`
3. Dispatch `critique-analyzer` with the plan file, stage artifacts, and
   `docs/JNS-6065-upfront-critique.md`, plus `docs/JNS-6065-tasks.md` as
   `PRIOR_DECISIONS_FILE` and `PRIOR_DECISIONS_KIND=main-log`
4. Receive:
   CRITIQUE: PASS
   Ticket: JNS-6065 | Mode: upfront | Task: -
   Artifact: docs/JNS-6065-upfront-critique.md

   ## Critique Summary

   - Problem-framing items: 2
   - Technology critique items: 3
   - User-impact items: 0
5. Dispatch `question-manifest-builder` with
   `docs/JNS-6065-upfront-critique.md` and `docs/JNS-6065-tasks.md`
6. Receive:
   MANIFEST: PASS
   Ticket: JNS-6065 | Mode: upfront | Task: -
   Task title: -
   Questions now: 8 | Deferred: 4 | Irrelevant: 1
7. Walk the 8 questions one at a time
8. Dispatch `decision-recorder` with resolved decisions and deferred items
9. Receive:
   RECORDING: PASS
   Ticket: JNS-6065 | Mode: upfront | Task: -

   ## Recording Summary

   ### Files Updated

   - `docs/JNS-6065-tasks.md`

   ### Counts

   - Decisions recorded: 8
   - Deferred questions tagged: 4
   - Questions marked irrelevant: 0
   - Implementation notes updated: 1

   ### Validation

   - PASS
10. Present final summary:
    Critique artifact: docs/JNS-6065-upfront-critique.md
    Files updated: docs/JNS-6065-tasks.md
    RE_PLAN_NEEDED: true
    BLOCKERS_PRESENT: false
</example>

<example>
Input: TICKET_KEY=acme-app-42, MODE=critique, TASK_NUMBER=3, ITERATION=2

1. Read `./references/design-thinking-mindset.md`
2. Read `./references/critique-mode.md`
3. Dispatch `critique-analyzer` with the task artifacts and
   `docs/acme-app-42-task-3-critique.md`, plus
   `docs/acme-app-42-task-3-decisions.md` as `PRIOR_DECISIONS_FILE` and
   `PRIOR_DECISIONS_KIND=per-task`
4. Receive:
   CRITIQUE: PASS
   Ticket: acme-app-42 | Mode: critique | Task: 3
   Artifact: docs/acme-app-42-task-3-critique.md
5. Dispatch `question-manifest-builder` with
   `docs/acme-app-42-task-3-critique.md`,
   `docs/acme-app-42-tasks.md`, and `CURRENT_TASK_ARTIFACTS`
6. Receive:
   MANIFEST: BLOCKED
   Reason: docs/acme-app-42-task-3-test-spec.md is missing
7. Stop clarification and present final summary:
   Critique artifact: docs/acme-app-42-task-3-critique.md
   Files updated: -
   RE_PLAN_NEEDED: false
   BLOCKERS_PRESENT: true
   Blocking verdict: MANIFEST: BLOCKED
   Reason: docs/acme-app-42-task-3-test-spec.md is missing
</example>