Problem Framing

Stage boundary

Contract marker: stage_gate: next_stage == problem-framing. Normative wrong-stage guard: wrong_stage: return=problem-navigator; artifact_writes=0; state_mutations=0. Normative invalid-artifact guard: invalid_artifact: atomic_next_stage=STOPPED; blocking_reason.code=MISSING_OR_INVALID_ARTIFACT.

Run only when the validated workflow has next_stage: problem-framing. If invoked at any other stage, return control to problem-navigator without modifying state.

This stage clarifies and records the problem; it does not inspect MCP configuration, search, design research tasks, evaluate candidates, recommend a solution, or generate evidence. It produces only the current problem-frame.yaml.

Before framing, validate the workflow against ../problem-navigator/references/artifacts.schema.json. If the workflow is missing, unparsable, or inconsistent, do not guess（不得猜测）or invent state. Atomically write:

blocking_reason:
  code: MISSING_OR_INVALID_ARTIFACT
  task_ids: []
next_stage: STOPPED

Then stop and return to the entry Skill.

Decide only the frame

Read ../problem-navigator/references/workflow-control.md. Its current recovery, authorization, mixed-evidence and delivery rules supersede older conflicting rules.

Set analysis_goal once:

• UNDERSTAND for explanation, diagnosis, situation mapping, or an evidence summary.
• DECIDE for choosing, ranking, recommending, approving, or forming an actionable solution.
• 从零开始把产品、软件或其他想法形成完整方案时，默认 DECIDE.

Researching or mapping technical routes without a requested ranking/recommendation is UNDERSTAND. Reuse an already selected research-report goal; the word "route" alone is not a reason to ask the same goal question again.

When this distinction is unclear, 只问 analysis_goal 这一项. Do not open a questionnaire or add another mode system. Draft other fields from the user's supplied meaning and let the confirmation gate expose any correction.

Set content_profile independently:

• General strategy, operations, career, organization, policy, procurement, or other non-product/system questions map to GENERAL.
• Both PRODUCT and SOFTWARE inputs map to the single PRODUCT_SOFTWARE profile. Never persist PRODUCT or SOFTWARE as separate profiles.

The profile does not select a backend and does not enter the workflow YAML.

For PRODUCT_SOFTWARE, read only the "Six inputs, asked only where needed" section of ../research-design-kickoff/references/product-research-guide.md. Reuse supplied product definition, market, competitor/substitute anchors, critical resources, reuse intention and capability/module context. Record accepted scope and constraints in the existing frame fields; do not add a second specification or new frame fields. Ask only for a user-controlled unknown that materially changes the boundary. Public facts and undecided technical alternatives become later research questions. Do not conduct a fixed six-question interview or invent missing user choices. GENERAL does not read this guide or collect the six product inputs; clarify only its own problem, goal, scope and material constraints.

Choose the endpoint from the requested deliverable: UNDERSTAND uses RESEARCH_REPORT; GENERAL or full-product DECIDE defaults to FORMAL_DOCUMENT. A product-needs-only request uses PRD_ONLY. Pure architecture/technical comparison or software diagnosis uses TECHNICAL_SPEC_ONLY; don't impose a PRD. FINAL_SPEC_PACKAGE applies only when requested or when independently reviewable units materially help, confirmed in scope. These are scope trims in the same workflow, not additional profiles. For PRD_ONLY, user capabilities may describe the needed boundary without a technical module map. For TECHNICAL_SPEC_ONLY, reuse the existing system context instead of forcing a market or competitor interview. UNDERSTAND does not require candidates. If the user requires court review, record optional court_required: true in the accepted frame. Multiple candidates later require court regardless; false/omitted only permits DIRECT when at most one candidate remains. Do not ask a redundant method question or weaken an already explicit court instruction.

Confirmation and artifact

After clarification, present one concise requirement summary: problem, intended outcome, research priorities, scope/non-goals, constraints and important assumptions. Explain the endpoint and goal/profile in natural language, not as a form of internal enums. Identify assistant-proposed boundaries. Ask in ordinary text for confirmation or corrections and wait without a deadline. Selecting a report type or authorizing Web access alone does not accept the assembled frame. A general instruction to proceed permits preparation, not acceptance of an unseen summary. Reuse actual acceptance of this same shown version; do not ask again when resuming it unchanged.

While waiting, save frame-draft.yaml beside the eventual frame with user_confirmation_status: DRAFT; record the question/reference in the shared pending.md. Keep next_stage at problem-framing and do not design or dispatch research. After a scope correction update the draft and show the revised summary before asking again.

After explicit acceptance, create this single artifact at .problem-navigator/artifacts/<workflow_id>/problem-frame.yaml:

schema_version: 1
workflow_id: <same workflow UUID>
problem_frame_id: <stable ID for this frame>
problem_frame_version: 1
analysis_goal: UNDERSTAND | DECIDE
content_profile: GENERAL | PRODUCT_SOFTWARE
clarified_problem: <confirmed problem statement>
goal: <what the analysis must enable>
scope: []
non_goals: []
constraints: []
assumptions: []
delivery_endpoint: <confirmed report or specification endpoint>
user_confirmation_status: ACCEPTED
confirmation_basis: <actual affirmative user response to the shown summary>

Use a stable problem_frame_id. A user-confirmed correction increments problem_frame_version and atomically replaces the same stable file; do not keep a version graph.

Atomic handoff order

The only success order is:

Use workflow_control.py accept-frame --frame <relative-draft.yaml> --reviewed-sha256 <draft-byte-hash> --user-response <actual-affirmative-response>. The hash binds the draft underlying the shown summary; the host must truthfully attest that the response accepts that summary. This command performs the following writes; do not hand-edit the accepted flag or workflow to replace it.

1. 原子写入 problem-frame.yaml through a same-directory temporary file and replace.
2. Only after that succeeds, 更新 workflow YAML atomically with the same accepted analysis_goal, the relative artifact_refs.problem_frame path, and next_stage: research-design-kickoff.
3. Hand off to research-design-kickoff and stop this stage.

If artifact writing fails, leave the workflow reference and stage unchanged. Never write the YAML reference first, never store content_profile in the workflow, and never begin research from this Skill.