[
  {
    "title": "Question title",
    "context": "Background: what I was working on",
    "uncertainty": "What specifically I cannot decide alone",
    "findings": [
      { "content": "Finding 1", "source": "Source A" },
      { "content": "Finding 2", "source": "Source B" }
    ],
    "judgment": "My recommendation and reasoning",
    "options": [
      { "label": "Option A", "basis": "Rationale for A" },
      { "label": "Option B", "basis": "Rationale for B【我的推荐】" },
      { "label": "Need more info", "basis": "If none of the above fits" }
    ]
  }
]

2. Generate Form

node scripts/generate.js questions.json

Output includes:

Local HTML file
GitHub Gist URL
Preview link (htmlpreview.github.io)

3. Send Link to User

Send the preview URL. User fills the form and copies the result JSON back.

4. Parse Response

User response structure:

{
  "formId": "form-20260130-180000",
  "timestamp": "...",
  "globalFeedback": "all_ok|need_more_info|discuss|null",
  "globalComment": "Overall feedback",
  "summary": { "total": 3, "answered": 3, "agreedWithAI": 2 },
  "answers": [
    {
      "question": "Question title",
      "selectedLabel": "Option B",
      "customAnswer": "User's custom input if any",
      "agreedWithMyJudgment": true
    }
  ]
}

Question Design Guidelines

Required Fields

title: Clear, concise question title
options: At least 2 options, each with label

Recommended Fields

context: Background - what was I working on
uncertainty: Why I need to ask - what blocks my decision
findings: Evidence with sources - show original text, not just summaries
judgment: My recommendation with reasoning

Option Design

Add basis (rationale) to each option
Mark recommended option with 【我的推荐】 in basis
Include "Need more information" as fallback option

Quality Principles

Give full context - Show original text, not just extracted numbers
Explain uncertainty - Why can't I decide alone?
Cite sources - Where did each finding come from?
Justify recommendations - Why do I lean this way?

Workflow Integration

CC Task Integration

When CC completes a task that needs user confirmation, include in CC prompt:

如果有需要主人确认的问题，在任务最后生成 questions.json 文件，格式：
[{"title":"问题","context":"背景","uncertainty":"不确定点","findings":[...],"judgment":"判断","options":[...]}]

After CC completes, check for questions.json and generate form if exists.

Response Archiving

After receiving user response, save to archive:

~/clawd/records/confirm-form/YYYY-MM-DD_<formId>.json

Archive format:

{
  "formId": "...",
  "createdAt": "...",
  "respondedAt": "...",
  "questions": [...],
  "response": {...}
}

Use for: reviewing past decisions, tracking confirmation patterns.

Files

scripts/generate.js - Form generator script
assets/template.html - HTML form template (copy-paste mode)
assets/template-v2.html - HTML form template (auto-notify mode, experimental)
assets/examples/sample.json - Example questions

confirm-form

Confirm Form

Quick Start

1. Prepare Questions JSON