I Stopped Making Cowork Read My Whole Troubleshooting Notes — Pulling One Section by Number Cut 105 KB to 1.5 KB

My troubleshooting notes had quietly grown to 1,549 lines.

Every time I told Cowork, "I think I've hit this symptom before," I handed over the whole file. One symptom, and nearly 105 KB along with it. One day, watching it load, I stopped and wondered why I was doing this.

So I changed it: say a number, get back one section. My first script, though, couldn't find most of the numbers. I'm keeping that failure in the record, with the measurements.

The short version: sections are small, and the real problem was numbers I couldn't reach

Measured results first. The file is a single Markdown document of problems I've run into while operating web sites.

Passing the whole file versus pulling one section differs by roughly 60x to 260x in bytes. I hadn't expected the median section to be only 356 bytes until I measured it.

Notes are something you query, not something you make the assistant read. I drew that line only after I saw the numbers.

My first extraction script reached a quarter of the numbers

The first awk I wrote picked up only headings that carried a number like #119.

# First version: only matches "### #119 ..." style headings
awk -v n="$2" '
/^#{2,3} / { on = ($0 ~ ("^#{2,3} #" n "([^0-9]|$)")) }
on { print }
' "$1"

#119 worked. It returned 1,567 bytes, and for a moment everything looked fine.

Then I asked for #70, a section I look up all the time. It returned 0 bytes. No error, just nothing.

Recounting the headings explained it:

• Headings with a #-style number, like ### #119 ...: 30 distinct numbers
• Headings with a plain chapter number and no #, like ## 70. ...: most of the rest

The notes had grown over months, so only the later sections used the #number style while the early ones used chapter numbers. The script reached 30 numbers; 120 were actually addressable (within 1 to 134). A quarter.

What worried me most was that, from Cowork's side, "0 bytes" looks identical to "no match." A symptom could be written down in the notes and still be judged "no precedent."

The fixed version, and what it returns

For chapter-style sections (## 70.) the script now returns everything up to the next ## , children included. For #number sections it returns just that section.

#!/bin/bash
# kb.sh FILE NUMBER
# "## N." runs to the next "## " (children included); "### #N" returns that section only
awk -v n="$2" '
/^## /  { on = ($0 ~ ("^## " n "\\.")); top = on; if (on) print; next }
/^### / { if ($0 ~ ("^### #" n "([^0-9]|$)")) { on = 1; top = 0; print; next }
          else if (!top) { on = 0 } }
on { print }
' "$1"

Measured after the fix:

Ten consecutive runs took 0.057 seconds in total, so speed is a non-issue.

The last row is the one that matters. Zero bytes for a number that doesn't exist is correct behavior. Zero bytes for a number that does exist means the tool is broken. To tell those apart, I added the check in the next section.

Don't let "0 bytes" pass quietly — cross-check against the index

I build the list of numbers that exist first, then pull every one of them and complain about any that return nothing.

#!/bin/bash
# kb-check.sh FILE — pull every number in the index and count the 0-byte results
F="$1"
nums=$( { grep -oE '^## [0-9]+\.' "$F" | grep -oE '[0-9]+'
          grep -oE '^### #[0-9]+' "$F" | grep -oE '[0-9]+'; } | sort -nu )
bad=0
for n in $nums; do
  size=$(./kb.sh "$F" "$n" | wc -c)
  [ "$size" -eq 0 ] && { echo "0 bytes: #$n"; bad=$((bad+1)); }
done
echo "checked=$(echo "$nums" | wc -w) zero=$bad"

I run it once after adding a section. On my file it prints checked=120 zero=0 and finishes in 0.8 seconds. If zero is anything else, it means a new heading style has crept in.

I also chose not to build the index on line numbers. They shift every time a section is added. Querying by heading text and number keeps the script working as the notes keep growing.

Rewriting the instruction I give Cowork

With the tooling in place, I rewrote the instruction too.

Before:

My troubleshooting notes are in STUMBLING_POINTS.md. Look for the relevant parts.

After:

My troubleshooting notes are in STUMBLING_POINTS.md. Don't read the whole file. First pull one section with kb.sh by number. If you don't know the number, look at the index (the list of headings) and pick the likely one. If any number comes back with 0 bytes, tell me instead of moving on.

The last sentence comes straight from the failure above. Not letting "nothing came back" slide by gives me one more place to notice a miss.

Where this leaves me

In numbers, roughly 105 KB per lookup became a 0.4 to 1.6 KB section. What stayed with me, though, was something else: decide how a lookup behaves when it fails before you decide how it behaves when it works.

If you keep a notes file like this, a first step could be counting whether your heading numbers follow a single style. Mine didn't, and that was where the whole approach began to be useful.