aivrar/portable-hermes-agent/decision-questionnaire

Decision Questionnaire

Turns something the user can't answer alone into a questionnaire: a Markdown document they hand to one person to fill in async, or fill out together in a meeting. The recipient holds knowledge the user lacks; the questionnaire pulls it out of them.

Ported from mattpocock/skills' MIT-licensed to-questionnaire skill.

When to Use

• A decision blocks on facts or judgment held by someone else (a domain

expert, a stakeholder, a vendor contact, ops)

• The user says "I need to ask X about this" or keeps deferring a decision

pending someone else's input

• Preparing for a meeting where specific answers must come back

Do NOT use when the answer is discoverable from the environment (codebase, docs, web) — find it yourself first.

Core Principle: Interview the Send, Not the Subject

The user cannot answer the subject-matter questions (that's the point), but they can ALWAYS answer questions about the send. Interview them only about that, in two short exchanges:

1. Who is it going to? Role, expertise, relationship to the user. This

fixes the questionnaire's tone and how much context it must carry. Done when you know who the recipient is and what they know that the user doesn't.

1. What do you need back? The specific decisions or facts the user

can't resolve alone. Done when you have a concrete list of what the user must walk away able to do or decide.

Then write the questionnaire: draft questions aimed at the gap between what the recipient knows and what the user needs, following the structure below. Write it to decision-questionnaire-<slug>.md in the current directory (slug from the topic) and report the absolute path. Done when the file exists and every item from step 2 is covered by a question.

Document Structure

Frame it as a discovery questionnaire: the user lacks context, the recipient holds it. Order questions most-important-first (async means you may only get one pass). Group under ## headings by theme once there are more than a handful.

Template:

# <Questionnaire title>
 
**Purpose:** why this questionnaire exists and the decision riding on it.
 
**From:** <the user> · **To:** <the recipient> ·
**How your answers will be used:** <where they go>
 
## Context
 
One paragraph orienting a recipient who wasn't in the user's head. Enough
to answer well, not a page.
 
## How to answer
 
Deadline and rough effort. Partial answers and "I don't know" are useful:
flag anything you're unsure of rather than skipping it.
 
## <Theme heading>
 
### <One question — a single idea, never compound>
 
_Why this matters: <one line, only where the question could be misread or
invite a throwaway answer>._
 
>
 
## Anything else?
 
A closing catch-all: anything we didn't ask that we should know?

Every question gets an answer stub (>) directly beneath it.

Pitfalls

1. Grilling the user about the subject. They can't answer it — that's

why the document exists. Only interview the send.

1. Compound questions. One idea per question; split "and/or" questions.
2. Burying the critical question. Most-important-first; async

recipients fade.

1. Context dump. One orienting paragraph, not the whole history.
2. Skipping the "why this matters" line on ambiguous questions. It's

what turns a throwaway answer into a useful one — but don't add it to questions that are already unambiguous.

Verification

• [ ] Recipient's role/knowledge and the needed outcomes captured in two

exchanges before drafting

• [ ] Every step-2 item covered by at least one question
• [ ] Questions single-idea, most-important-first, answer stubs present
• [ ] File written and absolute path reported to the user