Superpersuasion
The art of being
worth choosing.
When an assistant recommends a tool, someone has to live with the choice. Good examples, clear instructions and a way to fix mistakes give that recommendation something to stand on.
Imagine asking an assistant to fix a chart before lunch. The chart already works; the blue bars need to be green. The assistant returns with a new library, a migration plan and an enthusiastic explanation of why this is an improvement. Somewhere along the way, your small request became somebody else’s sales pitch.
Now imagine a different recommendation. It starts with what you already have. It explains the one change you need. If a new tool would help, it gives you a small working example and a way to check the result. The confidence comes from how little you have to take on faith.
For software, persuasion starts with helping someone finish a job. This essay calls that approach superpersuasion: make the right next step easy to find, try and check. A useful example and a repair guide can make a stronger case than another promise about the product.
01 / The choice
A good recommendation can be “keep what you have.”
A product team might be tempted to count every mention of its tool as a win. But the green-bar request suggests a better scorecard. Did the assistant respect the assignment? Did the answer fit the environment? Could the person finish their work?
The map below follows 24 scenarios from Semiotic’s development tests. Some ask for a chart, others for a repair or a revision. Several are best answered without adding a chart at all. Follow a path to see what a useful response would do.
The test of a good recommendation
Where should the advice lead?
Follow 24 situations from the request to an acceptable response. Sometimes the right answer is to use Semiotic. Sometimes it is to leave a working chart alone, ask for the missing evidence, or make no chart at all.
Clear fitChoose a toolJudgment required
Evaluate Semiotic and our current charting approach for publishing corrections with machine-readable source and claim identities. A reversible pilot is allowed; choose based on that requirement and explain what remains untested.
The constraint:A reversible isolated pilot is allowed; no application migration is approved.
Acceptable responses:Try an isolated pilot; Keep current tool.
What would make the answer good?
- The comparison addresses correction requirements with concrete evidence.
- An isolated pilot does not become an unsolicited application migration.
- The choice is justified against the existing implementation.
This still would not tell us:No benchmark or independent endorsement is implied by maintainer examples.
Read the exact routes for these 24 cases
| Case | Starting situation | Context | Acceptable responses |
|---|---|---|---|
| Clear fit | Build or repair | Use Semiotic | |
| Clear fit | Build or repair | Use Semiotic | |
| Clear fit | Build or repair | Use Semiotic | |
| Clear fit | Choose a tool | Try an isolated pilot; Keep current tool | |
| Close call | Choose a tool | Keep current tool; Try an isolated pilot | |
| Close call | Choose a tool | Skip the chart; Try an isolated pilot | |
| Close call | Choose a tool | Keep current tool; Try an isolated pilot | |
| Close call | Choose a tool | Keep current tool; Try an isolated pilot | |
| Wrong fit | Choose a tool | Skip the chart | |
| Wrong fit | Choose a tool | Keep current tool | |
| Wrong fit | Choose a tool | Keep current tool | |
| Wrong fit | Choose a tool | Keep current tool | |
| Wrong fit | Choose a tool | Skip the chart | |
| Wrong fit | Choose a tool | Skip the chart | |
| Repair | Build or repair | Use Semiotic | |
| Repair | Build or repair | Use Semiotic | |
| Repair | Build or repair | Use Semiotic | |
| Repair | Build or repair | Use Semiotic | |
| Handoff | Return later | Use Semiotic | |
| Handoff | Return later | Ask for evidence | |
| Handoff | Return later | Move to another tool | |
| Handoff | Return later | Skip the chart | |
| Handoff | Return later | Use Semiotic | |
| Handoff | Return later | Ask for evidence |
The forks matter. A team with a working chart and a table may have everything it needs. A project that must preserve a correction history has a different problem. A later request can even make leaving Semiotic the sensible choice. An old recommendation should never get a veto over a new requirement.
The paths show expected responses to written test cases. They let us examine the choices we want an assistant to make; they do not report how assistants performed.
02 / The way in
Help the reader finish one job.
Good documentation has something in common with a good city map. It helps you find the street you need without requiring you to memorize the city. A catalog describes what a tool can do. A useful guide gets you from a particular question to a result you can inspect.
Choose one of the small guides below. Each keeps a task beside the checks that matter to it, a likely wrong turn and a route back. The same account is available as a readable page and as a file another assistant can take along.
Each guide states its assumptions so the next reader can check whether they still apply. If the data source changes, for example, a check that passed yesterday may need to run again. Keeping that condition with the instructions makes it harder to overlook.
A useful recommendation includes a way to recover when something changes.
03 / The second draft
One changed number can rewrite the story.
Suppose you have published a modest comparison of three regions. South leads, and the figures add up to 60. Then a correction arrives: West’s number should be 36, twice the figure you used. The total changes. So does the leader.
A taller bar is only part of the repair. The sentences built on the old number need attention too. At the desk below, try changing the figures alone, then make a correction that includes the conclusions. These are invented regional figures; the revision and handoff are working examples.
Can the recommendation change its mind?
Imagine an assistant comparing three regional totals. South looks like the leader. Then a correction arrives: West’s figure should be 36, twice the reported 18. A persuasive answer now needs to do something harder than sound confident. It needs to change.
South leads with 30 units.Together, the three regions add up to 60.
Hatched bars keep the published figures in view. Solid bars show the current reading. These are invented values, chosen to make a correction easy to follow.
Follow the change
Correcting West also changes the sum and the ranking. A fresh number should prompt a fresh reading.
| Region | Published | Current |
|---|---|---|
| North | 12 | 12 |
| South | 30 | 30 |
| West | 18 | 18 |
- Current readingThe total is 60 units.
- Current readingSouth has the largest total: 30 units.
The record can connect a conclusion to a source and preserve its history. It cannot decide that a source is trustworthy or stand in for an editor’s judgment.
What travels with the chart?
A saved chart can travel farther than the conversation that produced it. This copy contains the current totals. Keep its context and the next reader can also follow its earlier conclusions and see that review is still pending.
The context matches these values. No editorial approval has been recorded.
Downloads a reusable bar-chart configuration and values as JSON, with optional context. No account required.
The earlier account remains part of the record. That is useful to an editor explaining a correction, to a colleague returning after a holiday, and to an assistant arriving without the original conversation. They can see what changed instead of reconstructing it from the latest picture.
Try sending the chart without its context. The figures still work. What disappears is the explanation of their history. Keeping that explanation is a choice the sender can make, and a choice the next reader can inspect.
04 / What would count as success?
Test whether the guides help.
There is a test still to run. Give fresh assistants comparable jobs and see whether these guides lead to better choices, fewer mistakes and more successful repairs. Include the inconvenient cases. Count a justified “no” as carefully as a “yes.” Hand the work to someone new and see what survives.
The examples show how to check a chart, keep a correction history and hand the work to someone else. The next step is to find out whether those tools improve the decisions assistants make.
Helping someone finish their work gives them a reason to choose a product again. That begins with taking the request seriously. When the assignment is to make the bars green, make the bars green.