Learn ยท Authoring
How to write useful feedback for wrong software actions
"Incorrect, try again" teaches nothing. The feedback that changes what a learner does next names the wrong choice, says what it would cause in this situation, and points at the fact that makes the right choice right. Here is the pattern, with examples you can adapt to your own workflow.
Consequence, then reason, then the answer. One or two sentences. Written for the scenario the learner is in, not for the control in general. The learner should finish reading it knowing why their choice was wrong here, and able to say what the right one is without being told to click it.
Where feedback belongs, and where it does not
Most steps in a software task have one possible action: click this, type here. A wrong click on those gets a hint that says where to look, not a lecture. Feedback earns its place on the steps with a real choice: a status, a stage, a priority, a filter, an owner. Those are the steps a person can get wrong on the live system without any error appearing, and they are the reason the training exists.
Seven illustrative examples
These examples use fictional scenarios. Adapt the wording and decisions to your own policies before using them in training.
1. Name the consequence first
"That leaves the ticket in the queue. Pending is for tickets waiting on the customer or another team, and this one is neither. Payments have confirmed the re-issue and Rosalind has been answered, so the right status is Solved."
Work a ticket from open to solved, choosing Pending instead of Solved
The first four words are what the wrong choice does. Then the definition of the wrong option, then the two facts from the scenario that rule it out, then the answer. A new agent who reads this once knows what Pending means forever.
2. Define both wrong options against the facts
"Qualifying is for deals you're still sizing up, and Negotiation is for when terms are being argued. Lena has the quote in hand and hasn't come back yet, that's Proposal."
Add a new deal to the pipeline, choosing the wrong stage
When the dropdown has several plausible wrong answers, one line each. The definitions are the CRM's, but the sentence that decides it is about Lena and her quote, because that is the only thing the learner actually knows about this deal.
3. Explain why the responsible-sounding answer is still wrong
"That priority doesn't match the review's decision. Urgent means drop everything and work it today, and Medium or Low would leave the audit log languishing exactly where it is. The agreed level for open security work is High."
Find every open security issue and raise its priority, choosing Urgent instead of High
The hardest feedback to write is for the choice that feels careful. Urgent for a security bug is what a conscientious person picks. The feedback respects that by defining Urgent honestly, then returns to the rule the team agreed. This is a policy walkthrough, and the feedback teaches the policy.
4. Use the numbers the learner can see
"That priority leaves a billing error competing with routine work. Three customers have already been charged the wrong total, so pick the top level, Urgent."
File a new issue and watch it sort to the top, choosing a lower priority
"Three customers" is in the scenario the learner was given. Feedback that quotes the scenario back proves the choice was decidable from what they knew.
5. Say what the wrong choice would hide
"Picking another rep just swaps one filtered view for another and hides Dana's deals. Choose All owners to hand the full board back to the team."
Add a new deal to the pipeline, resetting the owner filter
The consequence of a wrong filter is invisible: nothing breaks, someone else just cannot find their work later. Feedback for shared tools has to describe the effect on the next person.
6. When the wrong choice would prove nothing
"That order won't tell you whether the priority stuck. Newest and Issue key would put a brand-new issue on top no matter what priority it carries. Choose Priority."
File a new issue and watch it sort to the top, sorting the list
Verification steps have their own wrong answers: the check that would pass whether or not the earlier step worked. Explaining why a check is not a check is how learners start verifying properly.
7. Rule out every alternative in one breath
"That status doesn't match what happened here. The patch is merged and the regression test is in, so the work isn't still in progress, and sending it back to Todo or Backlog would put a shipped fix back in the queue."
Triage the urgent bug and close it out, choosing any status but Done
One line of feedback can cover a whole dropdown if it is anchored on the facts. Merged and tested rules out In progress; a shipped fix rules out Todo and Backlog.
The checklist
- Lead with what the wrong choice does, in the learner's situation. Not "that is incorrect", but "that leaves the ticket in the queue".
- Define the wrong option briefly, so the learner learns the vocabulary as well as the answer.
- Quote the deciding fact from the scenario. If the scenario does not contain a fact that decides the choice, fix the scenario, not the feedback.
- End with the right answer, named. The learner is about to try again; do not make them guess twice.
- Keep it to two sentences. Feedback is read at the moment of a mistake, which is the moment attention is shortest.
- Never write feedback for a step with one possible action. Give it a spatial hint instead: "top-right of the thread header, level with the subject line".
How Shadow Capture writes it, and what you change
Shadow Capture's authoring pass writes a feedback line for every step where the recorded action was a choice, using the scenario it wrote and the options it found on the recorded control. Review the draft against the facts in your own scenario. In our experience the review changes two things most often: a definition that is right for the product but wrong for your team's policy, and a fact that was true in the demonstration data but reads oddly to people who know the real system. Both are one-line edits in the editor, or a sentence to AI assist.