Pick your year
Home by Dark
×

When something breaks

⏱ 15 min5 steps

Things break. You've been here before: you blew in the cartridge, put it back in, and tried again. You already know how to troubleshoot. This piece makes it a habit Claude can follow too.

The rule: find the before you fix anything. A quick fix to the wrong cause makes two problems out of one.

If Claude's first guess at the cause is wrong, that's ordinary. The step where you check the fix shows what to do.

cause The real reason something broke, not the first thing you noticed. All words

Before this, you'll want:

×

Steps

Step 1 of 50 done · about 15 min left

Steps for
  1. Step 1 of 5, not done yet
  2. Step 2 of 5, not done yet
  3. Step 3 of 5, not done yet
  4. Step 4 of 5, not done yet
  5. Step 5 of 5, not done yet

  1. Start Claude Code in your my-idea folder

    1. Open (Cmd+SpaceWindows key, type Terminal, press Enter).

    2. Go to your my-idea . Type this and press Enter:

      cd ~/Backyard/my-idea

      cd ~\Backyard\my-idea

    3. Check the says my-idea.

    4. Start . Type this and press Enter:

      claude
    Terminal An app on your Mac where you type instructions instead of clicking on things. Claude Code works inside it. All wordsfolder A place on your computer that holds files and other folders, like a drawer in a filing cabinet. All wordsprompt line The line in Terminal that ends with a % sign. The word right before the % is the folder you're in. All wordsClaude Code Claude, working inside Terminal. It can make files and run things on your Mac, with a safety checker watching what it does. All words

    You should see:

    Claude Code's name and version at the top, a line starting with ❯ where you type, and ⏵⏵ on in the bar at the bottom.

    auto mode Claude works without asking, and a separate safety checker blocks anything risky. All words
    That's not what I see
    It says "cd: no such file or directoryCannot find path … because it does not exist".
    The my-idea folder isn't there. It comes from Check the idea first and The three files, so do those first, then come back.
    It says "zsh: command not found: claudeThe term 'claude' is not recognized".
    This Terminal window doesn't know about Claude Code. Close the window with Cmd+WCtrl+Shift+W, open a new one and try again. If it still says that, go back to Claude Code and .install Put a new program on your computer so you can use it. All wordssign in Tell Claude Code which Claude account is yours, so it knows you've paid for it. All words

  2. Capture exactly what you saw

    • An ? Take a screenshot with Cmd+Ctrl+Shift+4Windows+Shift+S, the screenshot ladder from the home page, or copy the text exactly. Ctrl is the key that says control, next to fn.
    • Something looks wrong, with no error? Write down what you did, what you expected, and what happened instead.
    • When did it start? Right after a change, or out of nowhere?
    error message The words a program shows when something goes wrong. Copy them exactly; every word can matter. All words
    That's not what I see
    The error disappeared before I could read it.
    Do the same thing again and have your screenshot keys ready. If it won't happen again, write down what you remember, word for word if you can, and when it happened.

  3. Use the "something broke" prompt

    This asks Claude to find the real cause and suggest the smallest fix, and to wait for your OK before it changes anything. What you saw goes at the end.

    1. Click in Terminal. If you have a screenshot of the error, paste it first with Ctrl+VAlt+V, not Cmd+VCtrl+V. [Image #1] shows up where you type. If you copied the error's words instead, paste them first with Cmd+VCtrl+V.
    2. Copy the prompt below.
    Something's broken. Before you change anything: 1. Find out what actually happened. Read the logs or the error and tell me the real cause in plain words, with the line that shows it. 2. Tell me whether it's still happening or was a one-off. 3. Suggest the smallest fix, and how we'll check it worked. Wait for my OK before fixing. After the fix, check it the way we agreed and show me the proof. Here's what I saw, word for word if there was an error message:
    1. Paste it into Claude Code with Cmd+VCtrl+V.
    2. Type a space, then what you saw, like the sign-up button does nothing when I click it.
    3. Press Enter.
    4. Read the cause. If it doesn't make sense to you yet, ask before you go on.
    prompt What you type to Claude. A good one says what you want, how to work and what never to do. All words

    You should see:

    Claude tells you the cause in plain words, with the line that shows it, whether it's still happening, and the smallest fix. Then it asks before changing anything.

    That's not what I see
    I pressed Cmd+VCtrl+V and my screenshot didn't paste.
    In Terminal, a picture pastes with Ctrl+V, not Cmd+VAlt+V, not Ctrl+V. Ctrl is the key that says control, next to fn in the bottom-left corner.Alt is the key right next to the space bar.
    Claude started fixing things right away.
    Press Esc to stop it. Then type: Stop. Find the cause first and tell me, before you change anything.
    I don't understand the cause it found.
    Ask: Explain that like I'm not a programmer. What went wrong, in one sentence? You should understand the cause before you a fix.approve Say yes when Claude Code asks before it changes something. In manual mode, nothing gets written until you do. All words

  4. Check the fix the way you agreed

    When the cause makes sense, tell Claude to go ahead. This message asks it to make the fix and show you the .

    1. Copy the message below, paste it into Claude Code and press Enter.
    OK, make the fix. Then check it the way we agreed and show me the proof.
    1. Claude said how you'd know it worked. Do exactly that, yourself.

    A fix you haven't seen work is a guess.

    proof Something you or Claude actually saw, like the page loading or the line in the result. Not "it should work". All words

    You should see:

    Claude makes the fix, checks it the way you agreed, and shows you what it saw.

    That's not what I see
    The fix didn't work.
    That happens. Tell Claude what you saw, word for word, and ask it to find the cause again before trying anything else. Two quick guesses in a row usually make things worse.

  5. Add a line to CLAUDE.md so it doesn't happen again

    Every kind of breakage that happens twice gets a line in . This message asks Claude to write that line and show it to you before it saves.

    1. Copy the message below, paste it into Claude Code and press Enter.
    Add a line to CLAUDE.md about what broke today and how to avoid it next time. Show me the line before you save it.

    1. Read the line. If Claude already saved it and the line is wrong, tell Claude what to change.

    2. If it's right and Claude is waiting for you, tell it to save. Type this and press Enter:

      Looks right. Save it.

    Over time, your CLAUDE.md becomes a list of every trap you've already climbed out of.

    CLAUDE.md A note to Claude about how to work in this project. Claude Code reads it at the start of every session in that folder. All words

    You should see:

    Claude shows you the line it wants to add to CLAUDE.md, before it saves it.

    That's not what I see
    It was a one-off and won't happen again.
    Then skip this step. Add a line for every kind of breakage that happens twice.
×

Your challenge

Next time something breaks, don't ask Claude to fix it. Use the "something broke" prompt, and wait for the cause before you say yes to any fix.

Helpful extras

Last checked 2026-10-17

Start