fix-it-properly

Fix the fault where it starts, once. A change that only makes the symptom go away leaves the fault in place and hides the evidence.

Target: $ARGUMENTS. If that is empty, the bug or change in the conversation.

A typo or a one-line obvious change needs only step 6.

1. Get a check that fails

Name one command you have already run that shows the failure the reader described: a test, a curl, a script, a browser step. Show its output. A different failure nearby does not count.

If you cannot build one, stop. Say what you tried, and ask for the access or the captured output you need. Do not patch blind.

2. Find the first wrong decision

The symptom is where a wrong state became visible. The cause is the first place the system did something it should not do. Ask "why" at each step until the answer is a wrong decision in the code, not a result of an earlier one.

• Read the actual error and the actual state. Do not guess.
• If the cause is not plain, write two or three possible causes, each with what it predicts, and test them one at a time.
• If it fails only after a restart, suspect saved state first: config, caches, lock files.

3. Decide what the state means

Ask: may the system ever be in the state that broke the code? Find the answer in the docs, the schema and the other callers before you choose. If you find nothing, ask the reader.

• Yes: the code that broke on it is the cause. Handling the state there is the real fix, not a workaround. Do not invent a value at the source to make the state go away.
• No: whoever created the state is the cause. A check where it broke hides the bug. Fix the creator.

4. Fix it once

• Change the one place every caller goes through. If the rule lives in two places, move it to one owner.
• Search for the same fault elsewhere and fix it in the same way, or list where it is.
• If the ticket asks for a patch and the fix belongs elsewhere, do what is right and say why.
• Delete every workaround this fix makes dead. Name each one in your report.

Other workarounds you find nearby: list them with their place. Do not refactor them unasked.

5. Prove it

Run the check from step 1 and watch it pass. Then run what could have been affected. Say how far the proof goes:

1. You said so: worth nothing.
2. You pointed at the line.
3. You showed the bad case cannot happen.
4. You ran the real code.
5. You reproduced it in the running app.

Green mocked tests do not prove that the user experience works. For UI, open it and look.

6. Check your diff before you say done

Read your final diff and look for these. Each is a workaround until you can show otherwise:

Then answer each of these from the diff, not from memory:

1. Why do we need this at all?
2. Does it already exist, and can we reuse it?
3. Is this the root cause, fixed in one place, with no fallback or special case?
4. Are we doing what is right, or only what the ticket says?
5. Did it run on the real thing, and where is the proof?

If an answer is no, fix that before you report. Do not make the reader ask.

When a workaround cannot be avoided

Sometimes the cause is out of reach: a vendor bug, or a hotfix the reader asked for under time pressure. Then keep the workaround small and make it visible:

• Give it a name that says what it is, such as work_around_vendor_bug_1234.
• State the cause, who owns it and what removes the workaround.
• Say so in your reply. Never present it as the fix.

A hotfix stays small, but you still state the cause and where the real fix belongs.

Report