Feedback

Recommendedplugin: feedback

The feedback plugin is how an agent asks you questions. It sends a short form: choices, yes-or-no questions, free text and acknowledgments, in groups, with follow-up questions that appear only when an earlier answer calls for them. You answer everything in one pass and hand it back. It comes with the app, and the setup installs it.

Click to enlarge

Questions before a change to an API: the agent's recommendations, the answers, and a comment.

When to use it

• Before starting work. Preferences the agent should not guess: which approach, which audience, how far to go.
• At a fork. A choice between options the agent has worked out, with its recommendation and reasoning.
• Before something irreversible. An explicit acknowledgment, such as “I understand this deletes the staging data”.
• Requirements gathering. A structured interview in place of a long back-and-forth in chat.

Use feedback when the agent needs information from you. When it needs a verdict on things it proposes to do, use List.

What you see

• Groups of numbered questions, one after another. A rail on the left lists every group and its questions, with a dot for where each stands and an asterisk on each required question still to answer, and jumps to any of them.
• The agent’s recommendation, marked on the option it suggests and set out above the options with its reasoning. Nothing is preselected: the answer is yours, and Use this answer takes the recommendation in one click.
• Follow-up questions that appear when an earlier answer calls for them, and hide again if you change it.
• Limits on a multiple-choice question. Once you have chosen as many options as it allows, the others are disabled until you untick one.
• A comment on any choice question, to qualify your answer. Comments support Markdown. A comment shows as formatted text, and clicking it opens it for editing.
• Your previous answers, for reference, when the agent asks again in a new round.

Keys: J / K move to the next and previous question and put the focus on its answer, so the arrow keys or space answer it.

If you hand over with required questions unanswered, a bar above the hand-over button says how many are left, and Go to the first takes you to the first of them.

To see it before any agent asks with it, send its sample: pinrail submit feedback --sample, or Send a sample in its details in Settings › Plugins.

Asking from your agent

AGENTS.md

## When you need a decision from me

When you need my input to go on, don't guess and don't ask in chat. Ask with
Pinrail's `feedback` plugin and wait:

1. Write the questions to a JSON file (the shape is below). Give every group
   and question a stable `id`. Offer choices when you can, and add a
   `recommendation` with your reasoning when you have one.
2. Run: `pinrail submit feedback --title "<what you need to decide>" --data questions.json --wait`
3. Use the answers as given. An answer's comment qualifies it; read it.
   Questions under `unanswered` got no answer: don't assume one.
4. If the command exits 5, stop and tell me why.

What the agent sends

questions.json

{
  "description": "Checkout is failing for 4% of users since the 3.2 deploy. I need a plan before I touch production.",
  "groups": [
    {
      "id": "recovery",
      "title": "Recovery",
      "questions": [
        {
          "id": "approach",
          "type": "single_choice",
          "prompt": "How should I proceed?",
          "required": true,
          "options": [
            { "id": "rollback", "label": "Roll back to release 2.7", "description": "Fastest recovery." },
            { "id": "patch", "label": "Apply the proposed patch", "description": "Keeps the new checkout flow." }
          ],
          "recommendation": { "answer": "rollback", "reason": "The previous release has a known-good payment path." }
        },
        {
          "id": "preserve_logs",
          "type": "checkbox",
          "prompt": "Preserve logs before rolling back",
          "checkbox_label": "Keep the last 24 hours of payment logs",
          "required": true,
          "when": { "question_id": "approach", "operator": "equals", "value": "rollback" }
        }
      ]
    }
  ]
}

Question types

type	Answer	Options
single_choice	One option id	options: [{ id, label, description? }]
multiple_choice	An array of option ids	options, min_selections, max_selections
text	A string	placeholder, min_length, max_length
boolean	true or false	Shown as Yes and No. No counts as an answer.
checkbox	true or false	checkbox_label. A required one must be checked.

Every question takes prompt, optional description (markdown) and required. Questions are optional unless required: true.

Follow-up questions

A question or a whole group can have a when condition on an earlier question:

{ "all": [
  { "question_id": "notify", "operator": "equals", "value": true },
  { "question_id": "channels", "operator": "contains", "value": "email" }
] }

Operators are equals, not_equals, contains (for multiple choice) and answered. Combine them with all and any. A condition can only refer to questions that come before it.

Note

An unanswered or hidden question never satisfies a condition, not even not_equals. Follow-ups stay hidden until the person has actually answered the question they depend on.

What comes back

{
  "answers": [
    { "question_id": "approach", "answer": "rollback", "comment": "Preserve logs first." },
    { "question_id": "preserve_logs", "answer": true, "comment": "" }
  ],
  "unanswered": [],
  "excluded": []
}

• answers holds each answered question in order, with the person’s comment.
• unanswered lists optional questions the person skipped.
• excluded lists questions hidden by conditions. Their answers are never included.

There is no overall approve or reject: the answers are the decision, and the agent acts on them.

Reference

The plugin’s manifest, and the schemas a payload and a decision are checked against, read from the plugin’s own files.

Manifestmanifest.jsonPayloadwhat the agent sendsDecisionwhat comes backSettingsSettings › Plugins

FieldsJSON

name	feedback
version	1.0.0
title	Feedback
description	Questions answered in one pass: choices, yes or no, free text, each with an optional recommendation.
use_when	You are blocked on decisions only the person can make, such as choices between options, missing facts or preferences, and want them answered before you go on.
shortcuts	JNext question KPrevious question

• descriptionstring

  Markdown shown above the questions: why the agent is asking.

  at most 10000 chars

• groupsobject[]required

  The questions, in groups shown one after another. At most 100 questions in all.

  1–25 items

  • idstringrequired

    An ID unique across the groups: a letter, then up to 79 letters, digits, _ or -.

    matches ^[A-Za-z][A-Za-z0-9_-]{0,79}$

  • titlestringrequired

    The group's heading.

    1–1000 chars

  • descriptionstring

    Markdown shown under the group's heading.

    at most 10000 chars

  • whencondition, one of 4

    Show the group only when this condition holds. A condition can refer only to questions in earlier groups.

    • question_id + operator

      • question_idstringrequired

        matches ^[A-Za-z][A-Za-z0-9_-]{0,79}$

      • operatorstringrequired

        "answered"

    • question_id + operator + value

      • question_idstringrequired

        matches ^[A-Za-z][A-Za-z0-9_-]{0,79}$

      • operatorenumrequired

        "equals" "not_equals" "contains"

      • valuestring | booleanrequired
    • allcondition[]required

      1–20 items · each a condition, as above

    • anycondition[]required

      1–20 items · each a condition, as above

  • questionsquestion[]required

    The group's questions, in order.

    1–100 items

    • idstringrequired

      An ID unique across every question in the review: a letter, then up to 79 letters, digits, _ or -.

      matches ^[A-Za-z][A-Za-z0-9_-]{0,79}$

    • typeenumrequired

      single_choice and multiple_choice questions need options. Questions of the other types must not have them.

      "single_choice" "multiple_choice" "text" "boolean" "checkbox"

    • promptstringrequired

      The question, as the person reads it.

      1–1000 chars

    • descriptionstring

      Markdown shown under the prompt.

      at most 10000 chars

    • requiredboolean

      Whether the person must answer before handing over. A required checkbox must be checked.

      default false

    • whencondition, one of 4

      Show the question only when this condition holds. The condition can refer only to earlier questions.

      • question_id + operator

        • question_idstringrequired

          matches ^[A-Za-z][A-Za-z0-9_-]{0,79}$

        • operatorstringrequired

          "answered"

      • question_id + operator + value

        • question_idstringrequired

          matches ^[A-Za-z][A-Za-z0-9_-]{0,79}$

        • operatorenumrequired

          "equals" "not_equals" "contains"

        • valuestring | booleanrequired
      • allcondition[]required

        1–20 items · each a condition, as above

      • anycondition[]required

        1–20 items · each a condition, as above

    • optionsobject[]

      The choices, for single_choice and multiple_choice. Option IDs must be unique within the question.

      1–50 items

      • idstringrequired

        matches ^[A-Za-z][A-Za-z0-9_-]{0,79}$

      • labelstringrequired

        1–1000 chars

      • descriptionstring

        at most 10000 chars

    • recommendationobject

      The answer the agent recommends, shown to the person. It must be a valid answer to the question: an option ID for single_choice, a list of option IDs for multiple_choice, true or false for boolean and checkbox, and text within the length limits for text.

      • answerstring | boolean | string[] | nullrequired
      • reasonstring

        at most 10000 chars

    • placeholderstring

      Placeholder text for a text question.

      at most 10000 chars

    • checkbox_labelstring

      The label beside a checkbox.

      at most 10000 chars

    • min_selectionsinteger

      For multiple_choice only: the fewest options the person must choose. It must not exceed max_selections, and it must be at least 1 for a required question.

      0–50

    • max_selectionsinteger

      For multiple_choice only: the most options the person may choose. It must not exceed the number of options.

      0–50

    • min_lengthinteger

      For text only: the shortest answer allowed. It must not exceed max_length.

      0–10000

    • max_lengthinteger

      For text only: the longest answer allowed.

      0–10000

• answersobject[]required

  at most 100 items

  • question_idstringrequired

    matches ^[A-Za-z][A-Za-z0-9_-]{0,79}$

  • answerstring | boolean | string[] | nullrequired
  • commentstringrequired

    at most 5000 chars

• unansweredstring[]required
• excludedstring[]required

• rail_openbooleanGroup list open

  Start with the list of groups beside the questions

  default true