Agent feedback workflow

Motivation Form gives coding agents a structured feedback surface outside the chat thread. The agent drafts a short questionnaire, publishes a hosted page, retrieves the responses, and carries the findings back into product and engineering work.

Use a form instead of chat when

Do not publish a form to avoid a useful conversation. Publish one when structure, repeatability, or asynchronous participation improves the decision.

Choose the collection mode

• Survey: collect preferences, priorities, confidence, constraints, and qualitative evidence. Omit mode and use page for a one-question-per-page flow.
• Quiz: test knowledge or readiness with scored questions. Set mode: quiz; add answer and score only to scored fields.
• Mixed: combine scored checks with unscored rationale or feedback fields. Use mode: quiz; fields without answer remain unscored.

Start with the smallest questionnaire that can change the decision. Ask only for context the agent cannot infer from the PRD, repository, or existing issue.

The feedback loop

1. Draft: state the decision, audience, and action that the responses will inform. Draft the minimum useful questions and review the Markdown file in the repository.
2. Publish: call deploy_form with the complete Markdown file. Share the returned public URL with the intended respondents.
3. Retrieve: use get_form_stats to check participation, get_response_report for an analysis-ready summary, and list_responses or export_responses when individual or raw records matter.
4. Synthesize: separate observations from interpretations. Report response count, distributions, recurring themes, disagreements, outliers, and sampling limits. Do not present a small convenience sample as consensus.
5. Update: convert findings into named changes to the PRD, Linear issues, implementation plan, or code. Preserve the evidence link and note what remains uncertain.

The loop can repeat. A first survey may narrow the direction; a second can test the revised decision with a smaller set of questions.

Example: founder direction review

An agent is preparing an onboarding PRD and finds two viable implementation directions.

1. The agent reads the current PRD and asks the founder only for the decision audience, deadline, and the consequence of choosing incorrectly.
2. It adapts apps/motivation-form/forms/agent-feedback-survey.md, replacing the generic outcomes with the two real directions and their constraints.
3. It validates and deploys the file, then gives the founder and product owner the public URL.
4. After responses arrive, it retrieves the report and writes a synthesis: preferred direction, priority order, confidence, supporting evidence, objections, and sample size.
5. It updates the PRD decision and acceptance criteria, adds the evidence to the relevant Linear issues, and changes the implementation plan. Conflicting or weak evidence becomes an explicit follow-up, not a hidden assumption.

Synthesis contract

Use this compact structure when feeding responses back into work:

## Evidence
- 8 responses from founders and product owners
- 6 preferred the smaller release; 2 preferred a broader rework
- Reliability ranked first in 7 responses

## Interpretation
- The current scope is acceptable only if reliability work remains in the release.
- Confidence is moderate; the sample excludes support and sales.

## Recommended updates
- PRD: make reliability the primary outcome and move reporting to follow-up scope.
- Linear: revise ML-123 acceptance criteria; add a support validation task.
- Code: keep the existing integration boundary; add failure-state coverage.

## Open questions
- Validate the revised scope with support before final approval.

Recommendations should be concrete enough to edit, assign, or test. Keep minority views and uncertainty visible.

Before publishing

• Review the survey design checklist or quiz design checklist.
• Validate the Markdown with the same parser used by Motivation Form.
• Remove questions already answered by repository or issue context.
• Confirm the audience, closing point, and owner of the follow-up action.
• Avoid collecting sensitive or identifying data unless the decision genuinely needs it.

See the agent feedback examples and the agent guide for syntax and deployment tools.