Questionnaire docs
Agent workflow
Ask one firm question at a time and update artifacts after every answer.
Questionnaire is agent-led. The browser helps draft and inspect state, but the agent keeps the run honest and durable.
Before asking
- Inspect the project when local files can answer part of the question.
- Rewrite the starter question for the user's actual task.
- Choose the smallest question that can move the decision forward.
- Include a recommended answer and why the question matters.
After each answer
- Update state.json immediately.
- Append the question, recommendation, answer, and decision to transcript.md.
- Update CONTEXT.md only for reusable terms.
- Add research notes for external facts, standards, APIs, compliance issues, competitors, or changing dependencies.
- Write an ADR when the answer creates an architecture, data model, privacy, vendor, deployment, pricing, or UX-flow decision that is expensive to unwind.
Question quality
Do not ask what the project already reveals. Do not accept vague answers when implementation depends on specificity. Press until the answer can become a decision, constraint, option, or next question.
Validation loop
validate
python3 scripts/validate-questionnaire-state.py .questionnaire/<timestamp>/state.json