Why this matters

In the last chapter, you set up Notion as your business brain. Everything's connected, skills are running, tools are talking to each other. But what happens when something stops working? This chapter has you covered.

Things will break. Connections drop. Updates change how things work. A skill file that worked perfectly yesterday gives weird output today. A connector (MCP) throws an error you've never seen.

This is normal. This happens to us too. The difference between someone who gives up and someone who builds a system that runs their business is this chapter.

What we're doing

Learning how to troubleshoot AI problems without being a developer.

The #1 troubleshooting tool: screenshots

Seriously. This is the most important tip in the whole chapter.

When something goes wrong:

1. Take a screenshot of the error or unexpected output
2. Open a new Claude conversation (or use claude.ai in your browser)
3. Paste the screenshot and say:

I'm trying to [what you were doing]. I got this error. What's wrong and how do I fix it?

Claude can read screenshots. It can usually tell you exactly what went wrong and what to do. You don't need to understand the error yourself.

This works for:

• Error messages in Claude
• Connection failures with tool connectors
• Weird output from a skill
• Things that used to work but stopped
• Settings you can't find

Common problems and plain English fixes

"Claude isn't reading my briefing file (CLAUDE.md)"

Why: Claude isn't pointing to the right working folder.

Fix: Check that your folder is set to your Documents > [Business Name - Claude] folder. Settings > Projects > make sure the right folder is selected.

"My Gmail/Xero connector (MCP) stopped working"

Why: Your sign-in permissions (OAuth) can expire sometimes. Xero's expire every 30 minutes (they auto-refresh, but sometimes the refresh fails). Gmail's last longer but can also drop.

Fix: Disconnect and reconnect the tool in Claude settings. It'll ask you to sign in again. Takes 30 seconds.

"Claude gave me completely wrong information"

Why: Either the skill file is unclear, or Claude doesn't have access to the data it needs.

Fix:

1. Check the skill file - is the rule specific enough? (Chapter 7)
2. Check the tool connection - is it still active?
3. Ask Claude: "Why did you do [wrong thing]? What rule or data were you using?"

"It used to work but now it doesn't"

Why: Either the tool updated, Claude updated, or something in your setup changed.

Fix:

1. Restart Claude (close and reopen)
2. Check your tool connections are still active
3. If a specific tool broke, disconnect and reconnect it
4. Screenshot the error and ask Claude for help

"Claude is making stuff up"

Why: Claude sometimes "hallucinates" - generates information that sounds right but isn't. This usually happens when it doesn't have enough context.

Fix: Add a rule to your CLAUDE.md: Never make up information. If you don't have the data, say 'I don't have that information' and tell me where to find it.

"My skill output is inconsistent"

Why: The skill rules are too vague or there are contradictions.

Fix: Review the skill file. Make rules more specific. Remove contradictions. Add an example of the exact output you want.

Building simple health checks

Once you've got a few workflows running, it's worth doing a quick check each week:

1. Are my connections live? Open Claude, check the tool connections show as connected.
2. Did my skills run correctly? Check a couple of recent outputs. Are they still good?
3. Is my briefing file (CLAUDE.md) up to date? Has anything changed in your business that Claude should know?
4. Are any skills getting stale? Skills you haven't used in months might need updating.

Create a simple skill for this:

# Skill: Weekly System Check

## When to use this
Every Monday morning, or when I say "run a system check."

## Steps
1. List all connected tools and confirm they're active
2. Check my Notion for any tasks that are overdue
3. Check Gmail for any unread emails from clients over 48 hours old
4. Summarise: what's working, what needs attention

When to ask for help vs fix it yourself

Fix it yourself

• Connection dropped (reconnect it)
• Skill output is wrong (update the skill file)
• Claude misunderstood something (rephrase or add context)
• Settings look different after an update (screenshot and ask Claude)

Ask for help

• Error messages that Claude itself can't explain
• Something fundamentally broken after an update
• You've tried three things and nothing worked

What you just learned

• Screenshots are your #1 troubleshooting tool - paste them into Claude
• Most problems are connection drops or vague skill rules
• A weekly system check (5 minutes) catches problems before they become issues
• You can fix most things yourself - you built the system, you understand it

Try it yourself

• Screenshot an error (or simulate one by disconnecting a tool) and ask Claude to diagnose it
• Create the Weekly System Check skill
• Run it and see what it reports
• Fix anything that comes up

Mark chapter as complete