Skill Tracer
Skills › Knowledge Work Plugins › report-builder › gotchas.md

gotchas.md

155 lines · small-business/skills/report-builder/reference/gotchas.md at 2574e29

Open on GitHub
1# Gotchas
2
3Failure modes that produce a report that looks right and is quietly wrong. Those are the dangerous ones — owners forward these reports to banks, boards, and accountants.
4
5---
6

Gotchas

Failure modes that produce a report that looks right and is quietly wrong. Those are the dangerous ones — owners forward these reports to banks, boards, and accountants.

Raw lines 1 to 6
7## Gotcha: partial period compared against a full one
8
9**Why it matters:** On July 27, month-to-date sales versus last full month looks like a 20% collapse. It isn't. Owners have made staffing decisions off this mistake.

Gotcha: partial period compared against a full one

Why it matters: On July 27, month-to-date sales versus last full month looks like a 20% collapse. It isn't. Owners have made staffing decisions off this mistake.

Raw lines 7 to 10
11### Bad
13```
14Sales — USD 21,400, down 19% vs. June
15```
17June was a full month. July is three days short. The comparison is meaningless and the owner reads it as a crisis.

Bad

Sales — USD 21,400, down 19% vs. June

June was a full month. July is three days short. The comparison is meaningless and the owner reads it as a crisis.

Raw lines 11 to 18
19### Good
21```
22Sales — USD 21,400 month-to-date through Jul 27
23 (June through the 27th: USD 19,800, up 8%)
24```
26Same data, honest comparison, opposite conclusion.
28---

Good

Sales — USD 21,400 month-to-date through Jul 27
        (June through the 27th: USD 19,800, up 8%)

Same data, honest comparison, opposite conclusion.

Raw lines 19 to 29
30## Gotcha: the same sale counted twice
32**Why it matters:** A Shopify order settled through Stripe and recorded in QuickBooks exists in three systems. Summing across connected sources inflates revenue, sometimes by double.

Gotcha: the same sale counted twice

Why it matters: A Shopify order settled through Stripe and recorded in QuickBooks exists in three systems. Summing across connected sources inflates revenue, sometimes by double.

Raw lines 30 to 33
34### Bad
36```
37Pull revenue from QuickBooks + Shopify + Stripe, sum all three.
38Report shows USD 129,000. Actual revenue was USD 43,000.
39```

Bad

Pull revenue from QuickBooks + Shopify + Stripe, sum all three.
Report shows USD 129,000. Actual revenue was USD 43,000.
Raw lines 34 to 40
41### Good
43```
44Pick one system as the revenue source. Say which:
46Revenue — USD 43,000 (source: QuickBooks; Shopify and Stripe used for
47 fulfillment and fee detail only)
48```
50Rule of thumb: the books are the revenue source when connected. Processors supply fees and timing. Storefronts supply product-level splits.
52---

Good

Pick one system as the revenue source. Say which:

Revenue — USD 43,000 (source: QuickBooks; Shopify and Stripe used for
          fulfillment and fee detail only)

Rule of thumb: the books are the revenue source when connected. Processors supply fees and timing. Storefronts supply product-level splits.

Raw lines 41 to 53
54## Gotcha: a group disappears instead of showing zero
56**Why it matters:** If Portland sold nothing this week and the row vanishes, the owner assumes the data is broken and goes looking. A zero is information; a missing row is noise.

Gotcha: a group disappears instead of showing zero

Why it matters: If Portland sold nothing this week and the row vanishes, the owner assumes the data is broken and goes looking. A zero is information; a missing row is noise.

Raw lines 54 to 57
58### Bad
60```
61Sales by location:
62 Salem USD 18,200
63 Eugene USD 19,000
64```
66Portland existed last week. Where did it go?

Bad

Sales by location:
  Salem      USD 18,200
  Eugene     USD 19,000

Portland existed last week. Where did it go?

Raw lines 58 to 67
68### Good
70```
71Sales by location:
72 Salem USD 18,200
73 Eugene USD 19,000
74 Portland USD 0 (no sales recorded this period)
75```
77---

Good

Sales by location:
  Salem      USD 18,200
  Eugene     USD 19,000
  Portland   USD 0        (no sales recorded this period)
Raw lines 68 to 78
79## Gotcha: grouped rows don't tie to the total
81**Why it matters:** An owner who adds your columns and gets a different number stops trusting every report you produce after that.

Gotcha: grouped rows don't tie to the total

Why it matters: An owner who adds your columns and gets a different number stops trusting every report you produce after that.

Raw lines 79 to 82
83### Bad
85Publish the total and the breakdown without checking they agree.

Bad

Publish the total and the breakdown without checking they agree.

Raw lines 83 to 86
87### Good
89Check the sum before delivering. If they genuinely don't tie, say why:
91```
92Sales by location sums to USD 41,900. Total sales is USD 43,200.
93The USD 1,300 gap is unallocated invoices with no location set.
94```
96Naming the gap builds more trust than hiding it.
98---

Good

Check the sum before delivering. If they genuinely don't tie, say why:

Sales by location sums to USD 41,900. Total sales is USD 43,200.
The USD 1,300 gap is unallocated invoices with no location set.

Naming the gap builds more trust than hiding it.

Raw lines 87 to 99
100## Gotcha: re-interviewing about a saved report
102**Why it matters:** The whole promise of this skill is "describe it once." Asking the same five questions every month breaks that promise and the owner stops using it.

Gotcha: re-interviewing about a saved report

Why it matters: The whole promise of this skill is "describe it once." Asking the same five questions every month breaks that promise and the owner stops using it.

Raw lines 100 to 103
104### Bad
106```
107Owner: "Run the Monday report."
108Claude: "Sure — which metrics would you like, and what period should it cover?"
109```

Bad

Owner: "Run the Monday report."
Claude: "Sure — which metrics would you like, and what period should it cover?"
Raw lines 104 to 110
111### Good
113```
114Owner: "Run the Monday report."
115Claude: [reads saved_reports.md, finds it, runs it]
116 "Monday operating pack — week of Jul 20..."
117```
119Always read `saved_reports.md` first.
121---

Good

Owner: "Run the Monday report."
Claude: [reads saved_reports.md, finds it, runs it]
        "Monday operating pack — week of Jul 20..."

Always read saved_reports.md first.

Raw lines 111 to 122
123## Gotcha: a plausible number filled in for a missing one
125**Why it matters:** This is the most serious failure in the skill. A report is a document owners act on and forward. An invented figure that looks reasonable can survive several hands before anyone catches it.

Gotcha: a plausible number filled in for a missing one

Why it matters: This is the most serious failure in the skill. A report is a document owners act on and forward. An invented figure that looks reasonable can survive several hands before anyone catches it.

Raw lines 123 to 126
127### Bad
129```
130Labor — approximately 30% of revenue
131```
133Where did that come from? Nowhere. Payroll accounts didn't return.

Bad

Labor — approximately 30% of revenue

Where did that come from? Nowhere. Payroll accounts didn't return.

Raw lines 127 to 134
135### Good
137```
138Labor — n/a (QuickBooks payroll accounts unavailable this run)
139```
141Never estimate, never round toward a guess, never carry last period's figure forward silently.
143---

Good

Labor — n/a (QuickBooks payroll accounts unavailable this run)

Never estimate, never round toward a guess, never carry last period's figure forward silently.

Raw lines 135 to 144
145## Gotcha: leading with the table
147**Why it matters:** Owners asked for a report because they want a decision. A wall of numbers hands the analysis back to them, which is the job they were trying to hand off.

Gotcha: leading with the table

Why it matters: Owners asked for a report because they want a decision. A wall of numbers hands the analysis back to them, which is the job they were trying to hand off.

Raw lines 145 to 148
149### Bad
151Open with a 40-row table, then a summary underneath it.

Bad

Open with a 40-row table, then a summary underneath it.

Raw lines 149 to 152
153### Good
155Open with the one sentence that matters, three headline metrics, three findings. Everything else goes in the workbook.

Good

Open with the one sentence that matters, three headline metrics, three findings. Everything else goes in the workbook.

Raw lines 153 to 155