116 lines
4.1 KiB
Markdown
116 lines
4.1 KiB
Markdown
---
|
|
name: decision-questionnaire
|
|
description: "Turn an unanswerable decision into a questionnaire doc."
|
|
version: 1.0.0
|
|
author: "Matt Pocock (mattpocock/skills, to-questionnaire) + Hermes Agent"
|
|
license: MIT
|
|
platforms: [linux, macos, windows]
|
|
metadata:
|
|
hermes:
|
|
tags: [questionnaire, decision, async, stakeholder, discovery, communication]
|
|
related_skills: [meeting-action-items, document-to-action-items]
|
|
---
|
|
|
|
# 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.
|
|
2. **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:
|
|
|
|
```markdown
|
|
# <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.
|
|
2. **Compound questions.** One idea per question; split "and/or" questions.
|
|
3. **Burying the critical question.** Most-important-first; async
|
|
recipients fade.
|
|
4. **Context dump.** One orienting paragraph, not the whole history.
|
|
5. **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
|