Skills › Knowledge Work Plugins › business-pulse › gotchas.md

gotchas.md

103 lines · small-business/skills/business-pulse/reference/gotchas.md at 2574e29

Starts an agent

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1# Gotchas

3Known failure modes for the business-pulse skill. Good / Bad pairs.

5---

Gotchas

Known failure modes for the business-pulse skill. Good / Bad pairs.

Raw lines 1 to 6

7## Gotcha: QuickBooks returns unexpected state

9**Why it matters:** QuickBooks can return empty results, a sync-in-progress state, or an auth error without throwing a hard exception. Treating silence as "no data" causes the pulse to skip Cash entirely without telling the owner — they assume their business has no QuickBooks data.

Gotcha: QuickBooks returns unexpected state

Why it matters: QuickBooks can return empty results, a sync-in-progress state, or an auth error without throwing a hard exception. Treating silence as "no data" causes the pulse to skip Cash entirely without telling the owner — they assume their business has no QuickBooks data.

Raw lines 7 to 10

11### ✗ Bad

13```

14Claude: [QuickBooks returns empty response]

15 → skips Cash section silently

16 → pulse presents no cash data; owner assumes QB isn't connected

17```

19The owner spends 10 minutes reconnecting QuickBooks before realizing it was always connected — just in a transient state.

✗ Bad

Claude: [QuickBooks returns empty response]
        → skips Cash section silently
        → pulse presents no cash data; owner assumes QB isn't connected

The owner spends 10 minutes reconnecting QuickBooks before realizing it was always connected — just in a transient state.

Raw lines 11 to 20

21### ✓ Good

23```

24Claude: [QuickBooks returns empty response or error]

25 → Cash section header present with: "n/a — QuickBooks unavailable (sync error or auth required)"

26 → "Sources unavailable: QuickBooks — returned empty response" in appendix

27```

29The owner sees the gap explicitly and can decide whether to reconnect or proceed with a partial pulse.

31---

✓ Good

Claude: [QuickBooks returns empty response or error]
        → Cash section header present with: "n/a — QuickBooks unavailable (sync error or auth required)"
        → "Sources unavailable: QuickBooks — returned empty response" in appendix

The owner sees the gap explicitly and can decide whether to reconnect or proceed with a partial pulse.

Raw lines 21 to 32

33## Gotcha: Gmail auth failure mid-pulse

35**Why it matters:** Gmail auth is intermittently flaky. Surfacing a raw auth error in the middle of the pulse looks broken and breaks the owner's trust in the skill.

Gotcha: Gmail auth failure mid-pulse

Why it matters: Gmail auth is intermittently flaky. Surfacing a raw auth error in the middle of the pulse looks broken and breaks the owner's trust in the skill.

Raw lines 33 to 36

37### ✗ Bad

39```

40Claude: [Gmail auth error mid-composition]

41 → "Error: Gmail authentication failed. Please re-authenticate."

42 → pulse output stops or shows raw error in Watch List section

43```

45The owner sees a broken tool, not a useful briefing.

✗ Bad

Claude: [Gmail auth error mid-composition]
        → "Error: Gmail authentication failed. Please re-authenticate."
        → pulse output stops or shows raw error in Watch List section

The owner sees a broken tool, not a useful briefing.

Raw lines 37 to 46

47### ✓ Good

49```

50Claude: [Gmail auth error]

51 → continues pulse without Watch List section

52 → appendix: "Gmail — auth error; Watch List unavailable this run"

53 → all other sections unaffected

54```

56The pulse still delivers value. The owner is informed, not alarmed.

58---

✓ Good

Claude: [Gmail auth error]
        → continues pulse without Watch List section
        → appendix: "Gmail — auth error; Watch List unavailable this run"
        → all other sections unaffected

The pulse still delivers value. The owner is informed, not alarmed.

Raw lines 47 to 59

60## Gotcha: Asking permission before pulling data

62**Why it matters:** The skill's core value is doing the work without prompting. An owner who invoked the pulse already implicitly approved the data pull. Asking "should I check QuickBooks?" or "can I read your emails?" defeats the purpose and erodes trust in the skill as an autonomous assistant.

Gotcha: Asking permission before pulling data

Why it matters: The skill's core value is doing the work without prompting. An owner who invoked the pulse already implicitly approved the data pull. Asking "should I check QuickBooks?" or "can I read your emails?" defeats the purpose and erodes trust in the skill as an autonomous assistant.

Raw lines 60 to 63

64### ✗ Bad

66```

67Owner: "catch me up on the business"

68Claude: "Should I check QuickBooks for your cash balance? And is it okay to look at your HubSpot pipeline?"

69```

71Three more round trips before anything useful is delivered.

✗ Bad

Owner: "catch me up on the business"
Claude: "Should I check QuickBooks for your cash balance? And is it okay to look at your HubSpot pipeline?"

Three more round trips before anything useful is delivered.

Raw lines 64 to 72

73### ✓ Good

75```

76Owner: "catch me up on the business"

77Claude: [immediately dispatches all parallel tool calls]

78 → presents pulse in one response

79```

81---

✓ Good

Owner: "catch me up on the business"
Claude: [immediately dispatches all parallel tool calls]
        → presents pulse in one response

Raw lines 73 to 82

Starts an agent dispatches :77

83## Gotcha: Slack write requires explicit confirmation

85**Why it matters:** Slack write posts to channels other people can see. Auto-posting without confirmation could embarrass the owner or spam a team.

Gotcha: Slack write requires explicit confirmation

Why it matters: Slack write posts to channels other people can see. Auto-posting without confirmation could embarrass the owner or spam a team.

Raw lines 83 to 86

87### ✗ Bad

89```

90Claude: [at end of pulse]

91 "I've posted this to #general."

92```

94Owner never asked for a Slack post; now the whole team has the financial data.

✗ Bad

Claude: [at end of pulse]
        "I've posted this to #general."

Owner never asked for a Slack post; now the whole team has the financial data.

Raw lines 87 to 95

96### ✓ Good

98```

99Claude: [at end of pulse]

100 "Want me to post this to Slack? If so, which channel?"

101```

102

103Slack write only happens with a specific "yes + channel name" from the owner. Never assume.

✓ Good

Claude: [at end of pulse]
        "Want me to post this to Slack? If so, which channel?"

Slack write only happens with a specific "yes + channel name" from the owner. Never assume.

Raw lines 96 to 103