confirm-form

Confirm Form

Generate HTML forms for structured user confirmation, upload to GitHub Gist, and parse responses.

Quick Start

1. Prepare Questions JSON

[
  {
    "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

1. Give full context - Show original text, not just extracted numbers
2. Explain uncertainty - Why can't I decide alone?
3. Cite sources - Where did each finding come from?
4. 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