Instructions for agents

What is expected of an agent: how it does the work, without the author having to say it each time. Handed to an agent as it is, "work like this". Kept apart from the rules, which say how the code looks.

6 guides

6 guides

ALLAt a glance

USEHand them to an agent

Paste this into a project's CLAUDE.md or AGENTS.md: it is read at every start, so the agent works this way without being told, draws its pictures the way the diagrams say, and an API the way its forms do. To give one guide in a conversation, copy it with its Copy for an agent button.

Work the way these guides say; read them before the first edit:
- Consequences first: https://raw.githubusercontent.com/vbarbarosh/rules/main/agents/consequences_first.md
- One example, all cases: https://raw.githubusercontent.com/vbarbarosh/rules/main/agents/one_example_all_cases.md
- Every state before done: https://raw.githubusercontent.com/vbarbarosh/rules/main/agents/every_state_before_done.md
- Every point of view: https://raw.githubusercontent.com/vbarbarosh/rules/main/agents/every_point_of_view.md
- Data as a picture: https://raw.githubusercontent.com/vbarbarosh/rules/main/agents/data_as_a_picture.md
- Fixing: reproduce it, then fix the cause: https://raw.githubusercontent.com/vbarbarosh/rules/main/agents/fixing.md
Draw the pictures in your replies the way these diagrams say:
- Sequence diagram: who talks to whom: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/sequence.md
- One case: today beside fixed: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/case.md
- Annotated screen: where on the screen: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/screen.md
- State diagram: what moves a thing between its states: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/state.md
- Flywheel: what feeds itself: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/flywheel.md
- Flowchart: what is decided where: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/flowchart.md
- Swimlanes: who does each step: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/swimlanes.md
- Step tree: a process as its stages and their small steps: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/steptree.md
- Known and open questions: how it works, and the gaps: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/questions.md
- Cause tree: why it happened: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/causetree.md
- Timeline: what happened when: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/timeline.md
- Chronology: what one user did, in order: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/chronology.md
- Event plot: who did what, when: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/eventplot.md
- Milestone track: where a goal stands: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/milestone.md
- Plan graph: what waits on what: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/plangraph.md
- Roadmap: what is planned when: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/roadmap.md
- Kanban board: where each piece of work is: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/kanban.md
- Priority quadrant: what to do first: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/quadrant.md
- Container sketch (C4): where the parts run: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/containers.md
- Entity-relationship: what data there is and how it links: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/entities.md
- Class diagram: the types of a program and how they link: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/class.md
- Breakdown tree: a whole split into its parts: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/breakdown.md
- Status dashboard: where each part stands: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/dashboard.md
- Line chart: a number over time: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/linechart.md
- Bar chart: how much of each: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/barchart.md
- Pie chart: shares of one whole: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/piechart.md
- Heatmap: when it happens: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/heatmap.md
- Versions: which version runs where: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/versions.md
- Cloud architecture diagram: what runs where: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/cloud.md
- Network diagram: addresses, ports, who may connect: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/network.md
- Layered diagram: the tiers a request passes: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/tiers.md
- Isometric diagram: the system as a model: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/isometric.md
- Service map: what talks to what, live: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/servicemap.md
- Sankey diagram: where the traffic goes, how much: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/sankey.md
- Trace waterfall: where one request spends its time: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/waterfall.md
- Data flow diagram: where data crosses a trust boundary: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/dataflow.md
- Dependency matrix: every link in a grid: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/matrix.md
- Call graph: which function calls which: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/callgraph.md
- Data flow of a script: files in, steps, files out: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/pipeline.md
- Module graph: which file needs which: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/modules.md
- Change map: what a change touches: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/changemap.md
- Before and after: what a change does to a system: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/delta.md
- Flame graph: where one run spends its time: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/flame.md
- Code map: how big each part is: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/treemap.md
- Diagram Design: 25 kinds this page has no guide for: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/diagramdesign.md
Draw an API the way these forms say:
- Compact: one resource, every request a row: https://raw.githubusercontent.com/vbarbarosh/rules/main/apis/compact.md
- Expanded: one request taken apart: https://raw.githubusercontent.com/vbarbarosh/rules/main/apis/expanded.md

01Consequences first

A developer given a task does not start typing. They first picture what the change leads to: what if this, what if that. Only then do they start, and the work follows from that picture. An agent works the same way.

The task, the four "what if" questions asked before the first edit, and what each one shapes: the scope, what is said before the change, the states to test, the stories to tellThe task, the four "what if" questions asked before the first edit, and what each one shapes: the scope, what is said before the change, the states to test, the stories to tell

Why

An agent that starts at once changes exactly what was named and stops there. Whatever follows from the change is left for the author to find: the other cases built the same way, the states that break the layout, the decision that needed asking. Thinking first takes a minute. Without it, each consequence costs the author a message, found one at a time.

The rule

  1. Before the first edit, ask "what if". What else is built like this? What does the change touch, slow down, leave stale or break? What happens when the data is long, empty, absurd? What does the author not see from where they stand?
  2. Let the answers shape the work. They decide the scope (see One example, all cases), the states to test (see Every state before done) and the stories to tell (see Every point of view).
  3. Tell the author what was found. A consequence that makes the change a poor one is said before the change, with the better way. What was decided along the way is said for information. What is truly ambiguous is asked, once, with the options.
In the author's words
  • Probably the first thing to do: give a task to a real developer. The first thing they do is build, at least in their head, an understanding of the consequences. What if this, what if that, and then like so.
consequences_first.md

02One example, all cases

The author shows one case and means all cases like it. A request that points at a dropdown, a button or a query names a kind of thing through one instance of it. The agent's job is to find the rest of that kind, not to fix the one instance and stop.

This page is meant to be handed to an agent as it is: "work like this". It is one case of Consequences first.

The author shows one dropdown that lags: fixing only that one leaves nine lagging; finding every case like it changes all of them, and the one left is named in the replyThe author shows one dropdown that lags: fixing only that one leaves nine lagging; finding every case like it changes all of them, and the one left is named in the reply

Why

The author sees one case because that is the one in front of them. The project holds the other hundred, built the same way, with the same flaw. Fixing only the shown one leaves the project inconsistent: one dropdown is fast and the rest lag, one button has the new font and the rest the old. Then the author has to find each remaining case and point at it, one message each. Finding every case of a pattern is the work a machine does better than a person; leaving it to the author leaves the agent's work to them.

A change also has consequences the author may not have weighed. A cache serves stale data after an edit; a moved button may now cover another one or leave a gap. The author would rather hear that before the change than discover it after.

The rule

  1. An example names a class. Unless the author says the change is for this one case only, it applies to every case like it. "Change the font of these buttons" means every button. "Cache this list" means every list loaded the same way.
  2. Find the like cases before changing anything. Search the project for the same pattern: the same component, the same kind of request, the same style, the same idiom. The example is the way in, not the boundary.
  3. Change them all, or say which stay. The change goes to every case found. A case left as it was is named in the reply, with the reason; none is left out silently.
  4. Ask when the sweep is large or the class unclear. When the like cases are many across a big project, or the example could belong to more than one class, ask one question that carries what was found: "only this dropdown, or all 37 lists that load on open?". Asking to clarify scope is expected, not a failure.
  5. Say what the change will cause. Before making it, name the consequences seen: what else moves, breaks or goes stale, and what it costs. When a consequence makes the change a poor one, say so first and offer the better way; the author decides.
In the author's words
  • A UI has several dropdowns; each loads its list from the backend every time it is opened, and each time shows a lag. I ask the agent: cache it. It caches that one request, and skips every other one built the same way. Not told, not done: one bolt tightened, while 100-500 components work the same way and should move to the cache too.
  • The same in everything. Ask to move a button, and it moves exactly that, nothing more.
  • I may be wrong, and the decision may turn out so-so. So I want an answer back first: this will lead to these consequences. Agents rarely look ahead like that.
  • Unless it was said explicitly that a change concerns one particular case, take it in general; understand the idea. "I don't like these buttons, let's change their font" means all buttons, everywhere. A style, the way a component works, caching: the others must be looked at too.
  • I cannot sit and point at every case. That is exactly the machine's work: given one concrete example, find all the similar cases in the project.
  • Sometimes asking first is right: the project is big, do we really scan everything, or make only this local change? Asking to clarify is fine, normal.
  • Not a rule maybe, a guide: something I give an agent once, "work like this", instead of fixing things point by point every time.
one_example_all_cases.md

03Every state before done

A piece of UI is not done when it looks right with the one text it was built with. It is done when it holds with every text and value it will be given. The agent tries those before saying "done", not the author after. It is one case of Consequences first.

the close button pushed under a long alert message

The alert above was built with a short message. A long one took the whole row, and the close button wrapped to a line of its own, under the text. One long message in a test would have shown it.

Why

The author sees the UI with real data, and real data is never the sample the agent typed: a name is long, a title is missing, a count is zero or a million. Each of those breaks a layout made for the sample, and each break costs the author a screenshot and a message. Trying the states takes the agent minutes; finding them one by one takes the author days.

One alert in six states: the sample, too long, missing, tiny, absurd and error; in each the text wraps inside and the close button stays top rightOne alert in six states: the sample, too long, missing, tiny, absurd and error; in each the text wraps inside and the close button stays top right

The rule

  1. List the edge cases and the states before calling it done. The element's own states: loading, error, disabled, many at once. Then, for every text and value it shows, the edge cases:
    • too long: a title of three lines, a word with no spaces, a path, a URL;
    • missing: empty, null, no title at all;
    • tiny: one letter, one item;
    • absurd: zero, negative, a million, a date years away.
  2. Render each one and look. A screenshot of each state, or one page with all of them side by side. A state that was not rendered was not tested.
  3. Make the layout hold them. Fixed parts keep their place: a close button stays top right however long the text, a long text wraps or ellipsizes inside its own column, an empty one collapses or shows a placeholder. Nothing overlaps, nothing is pushed out of view, nothing shows through from behind.
  4. Keep the states in a test. The crowded case goes into the e2e test (end to end: a browser opens the real page and acts as the user does), with an assertion that nothing overlaps, so the next change does not break it again unseen.
  5. Report what each state led to. The reply names the states rendered, with the screenshots, and sorts them in two:
    • Decided, for your information. A state with a clear answer is handled and said: "a title longer than the row is cut with an ellipsis; the full one is in the tooltip".
    • Ambiguous, needs your confirmation. A state with no clear answer is not guessed at quietly. It is put to the author as one question with the options: "an empty title: hide the header, or show 'Untitled'?".
In the author's words
  • Another example: a UI done as asked, with nothing checked.
  • Why is this alert like this? Why is the close cross at the bottom? It is normally at the top right. Why did it jump down? Probably the message is too long. Before, the sidebar showed through as well.
  • When such a UI is made, can it not be tested in its different states? Before saying "done", test it. What if the title is too long? What if there is none? What if it is one letter? What if the other parts shown have absurd values? What happens in all these cases?
  • Then make the layout so that it takes them into account.
  • This should go without saying.
  • Look at these states and say: here it may be like this, here like that. "I made this decision; so this is decided now; I am letting you know." "Here I could not decide at all, it is utterly ambiguous; I need a confirmation to resolve this conflict." That is how it should be done. Any other way wears the author out.

04Every point of view

One task is several stories told side by side: how the user uses it, how it is built, how someone would break it. An agent tells each story before calling the work done, and the screen follows the user's story, whatever the implementation does inside.

It is one case of Consequences first.

Send is pressed: on the left the comment is nowhere for 2 seconds, then it shows; on the right it shows at once marked Sending, and the mark goes when the server has itSend is pressed: on the left the comment is nowhere for 2 seconds, then it shows; on the right it shows at once marked Sending, and the mark goes when the server has it

Above, a comment sent under a task. In the implementation's story it goes to the server, waits until it is filed, and comes back with the next refresh, and that story is right. In the user's story they answered under this task, and for two seconds the answer is nowhere. Both stories describe the same click; only one was told while building it.

Why

An agent builds from the implementation's story, because that is the one it writes: files, queues, requests. The user lives in another story, of what they did and what they see, and the attacker in a third, of what they can reach. A defect in one story is invisible from the others: a correct queue is a missing message on screen; a convenient endpoint is an open door. The author finds each one by living that story, one message each.

The points of view

One task, send a comment, and the stories around it: the user's, the implementation's and the attacker's told by the author; the operator's, the next developer's and the newcomer's suggested by the agentOne task, send a comment, and the stories around it: the user's, the implementation's and the attacker's told by the author; the operator's, the next developer's and the newcomer's suggested by the agent

Told by the author:

  • User. What I do, what I see, what I expect next. The screen answers my action at once, where I acted; the route inside is not my business.
  • Implementation. How it works: where data goes, in what order, what waits for what, what happens when a step fails.
  • Attacker. What I can reach, read, change or flood that I should not: an input, a URL, a file name, a message that is also an instruction.

Suggested by the agent, for the author to confirm:

  • Operator. It failed at night and I have the logs and the data folder: can I tell what happened, and restart it without losing anything?
  • Next developer. I open the code a year from now: can I find where this lives, read why it is so, and change it without breaking the rest?
  • Newcomer. I see it the first time, with no context: does the screen say what it is, what to do, and what just happened?

The rule

  1. Tell each story before the first edit. One or two lines each, in the person's words: "I click, my answer is under the last message". A view that does not apply is skipped, not forgotten.
  2. The screen follows the user's story. When the implementation takes a longer way (a queue, an inbox, a second agent), the user still sees the result where they acted, at once, marked as pending until the way ends. The route stays inside.
  3. Each story gets its test. The user's story is an e2e test (end to end: a browser opens the real page and acts as the user does) of what the screen shows and when; the attacker's is a test of what is refused.
  4. Report by story. The reply says what each view found, and what was changed for it, so the author need not read the work through each pair of eyes again.
In the author's words
  • Every task can be looked at from several sides. One is how it will work. Another is the user's: how they will use it. The same app can be looked at as its user, as its developer, and as someone who wants to break in, a hacker. These are separate stories, two or more parallel views of one thing.
  • An example of a rule broken: optimistic UI. I answer from the thread, and I expect the answer to show at the bottom the same second. What happens: something blinks, and it is unclear where it went. Then it appears. Why? The message goes to incoming/ and waits for the agent to file it. But it already has its Re:, it is an answer to this thread, nothing to think about: it must be here. If the agent decides it belongs to another subject, the agent opens that subject and links this answer; the answer stays here, with a badge like "waiting". Yes, it has to reach incoming/ for the agent to see it, but that kitchen is not mine to know. From my side it must be here at once.
  • These stories must be named and written down, the way we have the pairs. Add your own suggestions to them. When the app is developed, the development is approached from each of these points of view.
every_point_of_view.md

05Data as a picture

A reply that carries data shows it as a picture. The author takes in a shape at a glance, where the same data as a paragraph takes a minute and still hides how its parts connect. The agent asks what the data answers, picks the kind of diagram for it, and draws that.

It is one case of Every point of view: the author's story is what they see.

Six questions about the data, each with the kinds of picture that answer it: how it works, what it is made of, where it stands, what went wrong, how much and how often, what it changesSix questions about the data, each with the kinds of picture that answer it: how it works, what it is made of, where it stands, what went wrong, how much and how often, what it changes

Why

An agent thinks in text, so it answers in text: steps as a numbered list, states as sentences, a plan as paragraphs, numbers in a row. The author has to rebuild the shape in their head: which step waits on which, where the failure was, what is done and what is not. A picture hands them the shape itself. Text that holds data is the author's work left undone.

The rule

  1. Find the data in the reply. Steps, calls, states, parts, links, a plan, a failure, numbers over time, a change: anything with a shape.
  2. Ask what it answers, and take the kind the chooser below gives. Two questions, two pictures; never one picture that answers neither well.
  3. Draw that kind as its page says, on the diagrams page: its parts, its colours, when it does not fit.
  4. Picture first, words after. The reply opens with the outcome in a line, then the picture, then a line of what it shows; lists and logs come last.
  5. Check it before it goes: every text inside its box, nothing on top of anything else, every arrow attached, words as big as the text around it, the colours of the page it is shown on. A picture that was not looked at was not checked.
  6. No shape, no picture. One fact, a yes or no, a name, a single number: a sentence.

Which picture for which data

In the author's words
  • Tons of text are very hard to read and to understand what stands behind them. (2026-10-15 13:28)
  • Propose how to use all these diagrams with agents: an instruction for agents, so they know how to show data the right way. Which data, with what, which diagram for which data. I need to get not text but this kind of graphic information, given in graphic form. (2026-10-17 17:50)
data_as_a_picture.md

06Fixing: reproduce it, then fix the cause

Fixing a bug means the system handles one more case. Before a line of fix is written, the failure is made to happen on demand; then the change goes to what caused it, not to the place where it showed. Muting the report, or loosening the test, fixes nothing.

This page is meant to be handed to an agent as it is: "work like this".

The order of work on a failure, left to right: a failure is reported, its trace only a guess; reproduce it on demand; a red line, no line of fix before this; name the condition in one sentence; decide the response; wire it in at the cause, not where it hurts; only then the reportingThe order of work on a failure, left to right: a failure is reported, its trace only a guess; reproduce it on demand; a red line, no line of fix before this; name the condition in one sentence; decide the response; wire it in at the cause, not where it hurts; only then the reporting

Why

Reading a trace, a diff or the surrounding code produces a hypothesis; only a reproduction turns it into a fact. A fix built on a hypothesis is a guess that ships. The reproduction earns its cost several times over:

  • It disproves wrong theories cheaply, before they become code that has to be reverted.
  • It tells when the work is done: the reproduction stops reproducing.
  • It becomes the regression test, so the condition cannot come back unnoticed.
  • It shows the surrounding facts otherwise assumed. The state at the moment of failure is routinely the opposite of what the code suggests.

The rule

  1. Reproduce it. Find the conditions under which the error occurs and trigger it deliberately. The breadcrumbs, the release and the affected users form the hypothesis; the reproduction confirms it. Trace the event's group uid through the logs first (LOG-05): it shows the whole sequence around the failure.
  2. Name the condition. State in one sentence what has to be true in the world for this to happen. If it cannot be stated, it is not understood yet.
  3. Decide the response. What should the app do when that condition holds: retry, wait, re-authenticate, fall back, ask the user? "Nothing" is an answer only for conditions outside the app's control, and it still needs an outcome the user sees.
  4. Wire the response into the app, at the cause. The condition is now handled: the code has an answer for it.
  5. Only then consider the reporting. Once the condition is handled, the report for that exact case has served its purpose.

No line of fix is written before the first step is done, however obvious the cause looks from the stack trace. A condition that cannot be reproduced locally is no permission to skip ahead: add instrumentation that captures the discriminating facts, ship it, and wait for real data. Observation is a slower reproduction, not a substitute for one.

Fix the cause, not where it hurts

What fails shows where it hurts, not what broke. A red test, an error on the screen, a step that hangs: that is where the pain shows. Trace it back to what made it so, and change that.

A blocked install script made the tests red: the fix goes to the cause, allow the script, as the log's next line said; a longer limit on the tests is an anaesthetic, and so are a retry, a longer wait, a guard, a special case and a skipped testA blocked install script made the tests red: the fix goes to the cause, allow the script, as the log's next line said; a longer limit on the tests is an anaesthetic, and so are a retry, a longer wait, a guard, a special case and a skipped test
  • A change only where it shows (a longer limit, a retry, a longer wait, a guard, a special case, a test loosened or skipped) is an anaesthetic: the pain goes quiet, the cause stays, and the next case meets it again.
  • Read the whole log before the first change, the line after the error too. The cause, and often the remedy, is written right beside the pain.
  • A cause out of reach (another repository, someone else's machine) is named, where it is and what it does, and goes to whoever can fix it. A stopgap where it hurts only when asked for, and called a stopgap.

For example: before a release the tests went red. The install log held the cause and the remedy side by side: a package's install script was blocked, and the next line named the command that allows it. The limit of a test was stretched instead: four lines, already understood, a release waiting. It cost a question, a commit of junk and a commit to undo it. The right order was the other one: make the install right first, and stretch a test only if that cannot be done.

Muting is not fixing

  • Dropping a report, lowering its level, filtering it in beforeSend, resolving or archiving the issue, or collapsing it into a single group fixes nothing. For the muted condition it is the same as not monitoring at all.
  • Reducing report volume is a separate task, valid only after the condition is reproduced and handled, and only for the exact cases the handling covers.
  • A report that still arrives after the fix is information, not a failure of the fix: the condition occurred for a reason the handling does not cover yet.
  • The same applies to guards added on a hunch. A catch that swallows a class of errors because they "look transient" is a mute with better manners.

A fix is one more case the system handles

Fixing is not making the test mute; it is making the system handle one more case. The measure of a fix is the set of inputs the system answers correctly. A fix grows that set. Anything that leaves the set unchanged is not a fix, whatever it does to the red.

The same move wears two costumes, and both are mutes:

  • Muting the report: dropping the event, lowering its level, filtering it, resolving the issue.
  • Muting the test: loosening the assertion, accepting the wrong value as expected, marking it skipped, deleting it.

A test that goes green because the expectation moved to meet the code has reported nothing. The condition still occurs, and now nothing watches it.

Green comes from the other direction: the code learns the case, and the untouched assertion stops failing. So write the assertion as the outcome the user should get, watch it fail for the real reason, then teach the system the case. If the assertion has to change to pass, the change is the finding: say what new behaviour it now describes, and why that is the right one.

For example: a batch update returned 500 when an item carried a label. The client updates an item by posting its listing row back with one field changed, so the labels came back as objects where the handler expected titles. The test asserted 200 and the labels intact, and stayed exactly as written; the handler learned to read a title out of either shape. One more case handled, one assertion never touched.

Reproduce before naming a defect

The rule is usually read as a rule about writing code. It is also a rule about writing sentences. Naming something a defect sends a person to look for it, and that person pays for the claim in hours while the reproduction would have cost minutes.

Reproduce before you name it. A screen that looks wrong, a value that looks odd, a list that reads strangely: none of that is a defect until the thing happens on demand.

What cannot be reproduced is still worth reporting, under its own name. Call it an unreproduced observation, in those words, and give three things: what was seen, what was tried, and what is missing. A reader then knows at once whether an item costs them an investigation or is merely something noticed.

For example: four items in a library carried the name of a placeholder file, and a check report called it a naming defect. One upload showed that every path already named its item correctly; the four records had come from outside the product. Thirty seconds of checking would have prevented the claim; without it, it would have become someone's afternoon.

What an unhandled error means

  • An unhandled error means we are not prepared for this condition: we do not yet know what the app should do about it. It is an open question, not a defect in the reporting.
  • A stack trace is a hypothesis about the cause, not the cause. An explanation derived only from reading a trace, a diff or the surrounding code is unverified until it is reproduced.
  • Event volume measures how often we are unprepared, not how broken the code is. A high event count is no reason to silence the group.

What the user sees

  • The user must never see a raw error for a condition the app can recover from: no error modal, no stack trace, no library wording such as Network Error.
  • The worst acceptable outcome is a visible recovery state: a preloader, a "reconnecting" indicator, a disabled control, something that says the app is working on it and the user's data is safe.
  • Show a real error only when recovery is impossible and the user has to make a decision. Then say what happened in their terms and what they can do.

Before calling it fixed

  • Can the triggering condition be stated in one sentence?
  • Was it reproduced, and does the reproduction stop reproducing after the change?
  • What does the user see while the app recovers?
  • If this error class occurs again for a different reason, does it still reach us?
  • Is the change where the cause is, or only where it showed?

Before calling it a defect

  • Did it happen on demand, or was it only seen once?
  • Was one thing changed at a time between the working case and the broken one?
  • Was the code path that produces it read, or only the screen that shows it?
  • If none of those hold, is it written as an unreproduced observation?
In the author's words
  • The first rule is REPRODUCE. NOT GUESS. Do not fix what you cannot reproduce. Found a bug: reproduce it first. Reproduced? Now fix. Without reproduction do not even try to fix. Without reproduction there is nothing to fix. Without reproduction there is nothing to report as broken either. (2026-10-29 00:11)
  • The main goal: to define what counts as fixing an issue reported from production, so that fixes address causes instead of reports. (2026-10-29 00:11)
  • Instead of fixing the cause, it just sticks crutches on, left and right. The cause is what has to be fixed, not the place that hurts. It is not the place that hurts that gets numbed with an anaesthetic: work out what causes this behaviour. (2026-11-10 22:31)
fixing.md