An AI explanation calls a component a "worker" in one paragraph, an "agent" in the next, and an "executor" after that. You pause to work out whether it means one component or three.
That was the problem I focused on in my original post on X. Models sometimes invent terms or rotate through jargon, and the explanation becomes harder to follow than it needs to be.
Andrej Karpathy's post caught my eye because it starts with a useful observation: as models do more work, we spend more time understanding their output. His first suggestion was to ask for explanations in ASD-STE100.
It gives us a specific set of writing constraints to try when "explain this clearly" produces another dense paragraph.
What ASD-STE100 does
ASD-STE100, or Simplified Technical English, is a controlled language developed for maintenance documentation in aviation. Its purpose is to make technical instructions easier to understand, including for readers who do not speak English as their first language.
The specification has two parts: writing rules and a dictionary of approved words. It limits how words are used and generally favors one word for one meaning. It also permits technical names and technical verbs for a particular project or industry.
The sentence limits are concrete. The official specification sets a maximum of 20 words for procedural sentences and 25 for descriptive sentences. Descriptive paragraphs have one topic and no more than six sentences.
The overview image above is a quick reference. Use the official specification when you need the full rules.
For AI explanations, the useful starting point is the same concern: can the reader identify the action, the actor, and the thing being discussed without guessing?
Four habits worth borrowing
1. Keep sentences short
A sentence becomes difficult to follow when it mixes a normal operation, a condition, an exception, and a recovery action.
Split it where the logic changes. Keep the condition attached to the action it controls.
For example, consider this hypothetical instruction:
After the service starts, check its health endpoint and restart it if the check fails, unless a deployment is still running.
A clearer version:
- Wait for the service to start.
- Check the service's health endpoint.
- If the check fails, check whether a deployment is still running.
- If a deployment is still running, do not restart the service.
- If the health check fails and no deployment is running, restart the service.
The extra lines make the exception visible. Cutting the exception would make the instruction shorter and change its meaning.
2. Put one action in each step
"Update the config, restart the server, and check the logs" hides three actions in one step.
Separate them. A reader can then see where the procedure failed and which action comes next. This matters when you are following a setup guide or reading an agent's proposed plan.
3. Say who does what
"The result is validated before deployment" leaves the actor unclear.
Does the coding agent validate it? Does CI run a test? Does a person review it?
Name the actor that the source actually specifies. For example, "CI runs the integration tests before deployment" is useful when that is how the system works. If the source does not identify the actor, ask the model to flag the gap.
A polished sentence should not hide missing information.
4. Give each thing one name
This is the rule that matters most to me.
If "worker," "agent," and "executor" refer to the same component, pick one term and use it throughout. If they refer to different components, define the difference.
Do not ask the model to merge those names automatically. It could erase a real architectural distinction. Ask it to check the source and tell you when the relationship is unclear.
For a longer explanation, a small glossary helps:
| Term | Meaning in this explanation |
|---|---|
| Coding agent | The component that edits files |
| Test runner | The component that executes tests |
| Reviewer | The person who checks the proposed change |
Those definitions are an example. Use the names and responsibilities from your actual system.
Start with a prompt
Karpathy suggests asking for "80% of the way to ASD-STE100" because the full specification is stringent. That is a useful way to frame everyday explanations. The percentage is an informal style request, not a compliance score.
Here is a prompt to try:
Explain this using the writing principles of ASD-STE100.
Aim for 80% of the way, while preserving technical precision.
Use short sentences and active voice.
Put one action in each procedural step.
Name the actor responsible for each action.
Use the same name for the same component throughout.
Define technical terms when they first appear.
Preserve every condition, exception, number, and uncertainty.
Do not turn "may" into "will" or "should" into "must".
If the source is ambiguous, flag the ambiguity instead of guessing.
If a shorter sentence would change the meaning, keep the precision.You can use it on an answer you already have. Keep the original beside the rewrite so you can compare them.
For architecture explanations, add:
List the components and their responsibilities first.
Then explain how information moves between them.
If two names might refer to the same component, flag that explicitly.The open-source skill from my post
The repository I linked is danyuchn/asd-ste100-skill. It packages these principles as a Claude Code skill for ambiguous agent-facing English, including tool descriptions, error messages, and instructions between agents.
Its README documents this installation command:
npx skills add danyuchn/asd-ste100-skillExample requests:
Rewrite this tool description so an agent cannot misread it.
Preserve all conditions and limits. Show the before/after diff.Apply STE100 writing principles to this error message.
Keep the uncertainty about the cause.The project does not reproduce the official approved-word dictionary. Its structural linter can flag writing patterns, but it cannot prove that a rewrite preserves meaning or complies with the full standard. Treat it as an aid to review.
Check what the rewrite changed
Clearer writing can still describe the wrong behavior. My interest here is whether these constraints help with terminology and readability. A readable answer still needs verification against its source.
When comparing an original and a rewrite, check the parts that control behavior:
- Did "may retry" become "will retry"?
- Did an exception disappear?
- Did the model invent an actor to fill a gap?
- Did two different components become one?
- Did a suspected cause become a confirmed cause?
Keep the original explanation available when the details matter. Verify claims about code against the code, tests, or documentation.
Take an AI explanation that made you reread the same paragraph. Try the prompt above. Start by checking whether it now uses one consistent name for each component.
