bear-note-organizer - Claude MCP Skill

# bear-note-organizer

Triage the user's untagged Bear notes inbox to zero. **Triage-only**; not a general note-management skill. Periodic hygiene (stale `active`, duplicate detection, orphan-tag sweep) is intentionally deferred.

## When to invoke

- User explicitly asks: "triage my Bear notes", "process untagged notes", "organize my Bear inbox", "/bear-note-organizer"
- Do NOT auto-trigger on every Bear-related question

## Pre-flight (mandatory, in order)

1. Verify Bear is running: `pgrep -x Bear`. If not running, **abort and ask the user** — never fall back to direct DB writes without explicit opt-in.
2. Read the **Session Learnings** appendix at the bottom of this file.
3. (Optional) Read `references/tag-conventions.md` for format details.

## Workflow

### Step 1 — Query the inbox

DB path:
```
~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite
```

Untagged-active query (read-only, safe with Bear running):
```sql
SELECT n.Z_PK, n.ZUNIQUEIDENTIFIER, n.ZTITLE,
       SUBSTR(COALESCE(n.ZTEXT,''), 1, 250) AS preview,
       datetime(n.ZMODIFICATIONDATE + 978307200, 'unixepoch', 'localtime') AS modified
FROM ZSFNOTE n
LEFT JOIN Z_5TAGS jt ON jt.Z_5NOTES = n.Z_PK
WHERE n.ZARCHIVED = 0 AND n.ZTRASHED = 0 AND n.ZPERMANENTLYDELETED = 0
  AND jt.Z_13TAGS IS NULL
ORDER BY n.ZMODIFICATIONDATE DESC;
```

Schema essentials are in `references/schema-cheatsheet.md`.

### Step 2 — Categorize

Group untagged notes into bins:
- **Auto-batch candidates**: matches R9 (letter/card) or R10 (empty placeholder)
- **Investigation needed**: matches R11 (image-only), R12 (bare URL), or has ambiguous title
- **Recommend-only**: novel patterns or items needing user judgment

### Step 3 — Investigate

For investigation-needed notes:

- **Image-only notes (R11)**: locate via `find` under `~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/Local Files/Note Images/` (each image lives in its own outer-UUID subdirectory). `Read` the image; reference what's visible in the recommendation.
- **Bare URL notes (R12)**: `WebFetch` the URL — usually returns title; that's enough. `WebSearch` for disambiguation if title is ambiguous.
- **Multiple parallel investigations**: spawn an **agent team** via `TeamCreate` so investigators share findings rather than working blind. See `references/agent-teams-pattern.md`.

### Step 4 — Present and approve

- **Auto-batch candidates**: present grouped, ask for one batch confirmation, then execute.
- **Investigations**: present results + recommendations with rationale, wait for explicit approval.
- **Any `replace_all` on a user-created note** (folding into a list note, retitling): show **exact** new body as a preview before firing (R3, non-negotiable per user feedback memory).

### Step 5 — Execute

Use `scripts/bear_writes.py` helper (or the patterns documented there). All writes go through `bear://x-callback-url/*` — never direct SQLite writes.

The helper auto-snapshots prior body to `/tmp/bear-rollback/{uuid}-{timestamp}.md` before any `replace_all` (R5).

### Step 6 — Verify

Sleep ~3 seconds (Bear processes URL events asynchronously), then re-query the DB. Present a **terse** verification table:

| Op | Target | Expected | Observed |
|----|--------|----------|----------|
| TAG | 94 | +personal/correspondence/2026 | ✅ |
| ARCH | 111 | archived=1 | ✅ |

If all OK, report "all N operations verified." Flag discrepancies only.

### Step 7 — Update self

At end of session, append any new rules / refined heuristics / notable decisions to the **Session Learnings** appendix at the bottom of this file, with a date stamp. Protocol in `references/self-update-protocol.md`.

Also: if a new tag branch was created or a new pinned-list destination emerged, update the `Tag Taxonomy` note in Bear (see "Tag Taxonomy reference note" below).

## Triage rules

### Tag conventions (matching user's existing style)

- **R6.** Trailing `#` on every tag: `#personal/correspondence/2026#`
- **R7.** Write parent + child explicitly: `#personal/correspondence# #personal/correspondence/2026#` (Bear auto-creates the parent from the leaf, but matching existing notes keeps the user's text consistent)
- **R8.** Multiple tags on one line, space-separated
- **R21.** Tags describe **domains** (`personal/`, `tech/`, `finance/`), not **states** — except `active`, the one orthogonal state tag. Never propose `tech/active/` or similar; combine `category` + `active` instead.
- **R22.** Maximum nesting depth: **3 levels**. If a 4th feels needed, that's a signal to flatten or split horizontally.

### Pattern matching

- **R9.** Title matches `^(Letter|Card) (to|from) ` → propose `personal/correspondence/{current-year}` (auto-batch after one batch confirmation)
- **R10.** Empty placeholder (no title AND body matches `^[#\s]*$`) → propose trash without lengthy preview
- **R11.** Single-image note (body is `![](...png)` only) → read the image first; reference what's visible in the recommendation
- **R12.** Bare URL note (title === body === a single URL) → fetch metadata, propose new title + 1-line description + `active` tag
- **R13.** Identifiable single media (movie / TV / book) → fold into the appropriate pinned list note and **archive the source in the same operation pair**
- **R14.** Address capture (text screenshot containing a mailing address) → tag `personal/correspondence/{year}` + `active` (user transcribes to Apple/Google Contacts later; no consolidation note)
- **R18.** Articles **about** people the user knows → `personal` (or appropriate sub-branch); **not** `personal/correspondence/*` which is reserved for letters

### Person tags (R23, R24)

When a note is about a specific family member or friend by name, add a person leaf tag:
- Family: `#personal/family/{first-last-kebab}#` (e.g., `#personal/family/ian-paglia#`)
- Friends: `#personal/friends/{first-last-kebab}#`

Bear auto-creates the relationship parent (`personal/family` / `personal/friends`).

The 3rd-instance rule (R16′) does **not** apply to adding new person leaves within an existing relationship branch — adding a 1-of-1 person tag is always fine. The rule is about inventing new *category* branches, not new *people*.

### Stewardship

- **R15.** Don't silently create new tag branches. Always propose with rationale.
- **R16′.** Promote an ad-hoc category to a formal sub-branch only on the **3rd** instance (Johnny.Decimal heuristic). Force-fit into the existing parent for the first two.
- **R17.** Don't touch titles unless the user asks. The "Scanned Documents.pdf" suffix in correspondence titles is intentional Bear behavior — leave it alone.

## Safety rules (non-negotiable)

- **R1.** Bear must be running before any writes.
- **R2.** Read-only DB queries are unrestricted (SQLite WAL allows concurrent readers).
- **R3.** Preview every `replace_all` on a user-created note before firing.
- **R4.** Verify every write batch by re-querying the DB.
- **R5.** Save prior body to `/tmp/bear-rollback/{uuid}-{timestamp}.md` before any `replace_all` (helper does this automatically).

## Pinned list notes (fold-and-archive destinations)

| List | Z_PK | UUID | Purpose |
|------|------|------|---------|
| Media Queue | 37 | 22E69F7E-8AD4-44F5-8D27-9263F7F9D12C | TV / Movies / Books to consume |
| Movies for mom | 32 | 2019AB24-D732-441E-8301-CDB6C149C560 | Movies curated specifically for mom |
| Wish List | (re-query) | — | Things wanted |
| Gift Ideas | (re-query) | — | Gifts to give |
| Tech Watch List | 93 | (re-query) | Tech to evaluate |
| Skills to Install | 31 | (re-query) | Claude Code skills to set up |
| People to Visit | 92 | (re-query) | People to see in person |
| Trip Expenses | 30 | (re-query) | Per-trip costs |

Z_PKs may shift over time; UUIDs are stable. Re-query when in doubt:
```sql
SELECT Z_PK, ZUNIQUEIDENTIFIER, ZTITLE FROM ZSFNOTE WHERE ZPINNED=1 AND ZTRASHED=0;
```

When folding a source note into a list, **always** archive the source in the same operation pair. Never leave loose source notes alongside the canonical list.

## Tag Taxonomy reference note

The user has a pinned `Tag Taxonomy` note in Bear (tagged `#lists#`) that documents the live taxonomy. Update it whenever:
- A new tag branch is created
- A new pinned-list destination emerges
- A new convention is agreed

Use `replace_all` with preview, like any other user-created list note.

## Investigation toolbelt

- Read images: `Read` tool on the absolute file path
- Fetch URL metadata: `WebFetch` (often returns just title; usually enough)
- Web research: `WebSearch` for "what is X?" disambiguation
- Multiple parallel investigations: `TeamCreate` agent team (see `references/agent-teams-pattern.md`) — never isolated `Agent` calls when 2+ investigations could share context

## Deferred for future versions

- Periodic hygiene: stale `active` items (>30 days), duplicate detection, orphan-tag sweep (<3 notes)
- Auto-update on schedule (currently strictly on-demand)
- Title cleanup proposals beyond image-only / bare-URL cases

---

## Session Learnings (auto-maintained)

Date-stamped entries appended after each triage session. Add new rules / refined heuristics / notable decisions; do NOT rewrite earlier entries. Append-only — preserve history.

Format:
```
### YYYY-MM-DD — short-session-tag
- Rule / refinement / decision (with brief rationale)
- (Optional) reference to specific note PKs that prompted it
```

### 2026-04-26 — initial-bootstrap
- Skill bootstrapped from a 19-note triage session that drove untagged-active count from 18 → 0
- Confirmed user's existing tag conventions: trailing `#`, parent+child explicit, max 3 levels, `active` is the sole state tag
- Created new branch `personal/family` (1 note: Ian Paglia article)
- Established person-leaf convention `personal/family/{name-kebab}`; first leaf `ian-paglia` linked to 2 notes
- Folded Familiar Touch (2024) into "Movies for mom" list — note this is a separate destination from main Media Queue, specifically for mom-curated picks
- User confirmed: address captures stay per-note (no master Address Book consolidation); user transcribes to Apple/Google Contacts manually
- Agent teams (TeamCreate) authorized for parallel investigation phase

### 2026-05-01 — cunard-cruise-merges
- 27 → 0 untagged-active in one session (largest run to date)
- **New rule R25: Multi-screenshot recipe/article merges.** When 2+ image-only notes are sequential parts of the same source (e.g., scrolling screenshots of one recipe), user prefers a single merged note over individual tagging. Detect via: same source citation visible in multiple images (e.g., "Arnaud's Restaurant +6" badge), shared topic, sequential content. Always preview the merged body (R3) — keeper is the chronologically-first note (lowest content order, not lowest PK). Archive the rest. Cross-note image refs by UUID DO resolve in Bear regardless of source folder; verified working.
- **New rule R26: Cruise-context grouping.** Notes captured during an active trip cluster strongly — itinerary docs, restaurant research, food/drink recipes, dish allergens, search results all belong with the trip tag. When `travel/{trip-slug}-{year}` already exists and a note's content matches the trip's window (date, location, ship/operator named), tag it without prompting. The "Queen's Grill" / Cunard / port-city signals were strong enough to auto-batch this session's 8 cruise notes.
- **Created branch `personal/health`** — first instance: cruise dish allergen requiring trigger-identification follow-up (PK 140). User explicitly authorized; tagged with `active` for follow-up.
- **Gift Ideas restructured** with per-recipient `## {Name}` sections (## Mom, ## The Paglias). Sterling silver subsection under Mom. Adding `#active#` to the list note itself flags pending shopping/follow-up. Recommended over creating a duplicate "gifts for friends and family" pinned list — existing Gift Ideas already serves that purpose per Tag Taxonomy.
- **YouTube comment screenshots are usually trash unless they reference a specific film/title the user wants to remember.** Multiplicity (1996) reference (PK 127) was real → fold into Media Queue. Balls Up (2026) meme thread (PK 123) was humor → trash. When ambiguous, ask — don't guess.
- **Member Statement PDF (PK 141)** force-fit to bare `finance` tag per R16′ (1st instance). Promote to `finance/statements` on 3rd instance.
- Final taxonomy snapshot saved in PK 113 (Tag Taxonomy note).

### 2026-05-01 — active-tag-discussion-triage
- **First "active triage" variant session.** User asked to discuss/process notes tagged `active` (vs. the standard untagged-inbox triage). Same fold-and-archive primitives applied cleanly; no new tooling required. The discussion-first approach (group by likely close action, then drill in) worked well — user confirmed Group B fold + PK 142 tag in one batch.
- **New rule R27: Active-triage close actions.** For each `active` note, the close action is one of: (a) **fold into a list + archive source** (R13 — applies to identifiable media, queued videos, etc.), (b) **complete the action and drop `active`** (e.g., make recipe, schedule visit), (c) **add missing domain tags** if the note has only `active` and no domain (PK 142 had only `active`; fixed by mirroring PK 140's tags), (d) **defer** if still genuinely pending. List notes themselves keep `#active#` until the list is processed.
- **New rule R28: Mirror-tag from a sibling note.** When a note is the deep-dive / research writeup of an event already documented in another tagged note (e.g., PK 142 = Fructan research for the same dish that PK 140 captured), mirror the sibling's domain tags rather than re-deriving. Saves judgment cycles and keeps related notes findable together.
- **Stub notes that turn out to be media titles** still resolve via R13. PK 114 was a 29-char stub ("My one and only", no URL, 12-second create-to-modify window). User confirmed it referenced *My One and Only (2009)* film → folded into Media Queue + archived. Pattern: when an aborted-capture stub's text matches a real media title, ask the user; don't trash on length alone.
- Result: 14 → 10 active notes. Remaining 10 are list notes (5) and genuine pending follow-ups (5).
- **New rule R29: OmniFocus handoff for genuine to-dos.** When an `active` Bear note is really a deferred to-do (not reference material, not a decision-pending list), the close action is: create an OmniFocus inbox task with the actionable verb in the title (e.g., "Plan next cruise", "Make a hummingbird") and put the bear:// URL in the task notes, then archive the source. Bear stays a knowledge store; OmniFocus owns the action queue. Pattern: `bear://x-callback-url/open-note?id={UUID}` is a stable round-trip link.
- **OmniFocus Ruby manager (`omnifocus_manager.rb --create`) failed with `-1700` "Can't convert types"** even when `--project` was omitted (Inbox target). AppleScript fallback worked: `tell application "OmniFocus" / tell default document / make new inbox task with properties {name:"...", note:"..."}`. Document this in the omnifocus skill if it persists.
- **New rule R30: Cross-note links for paired knowledge.** When two notes document the same incident from different angles (e.g., the dish PK 140 + the diagnostic research PK 142), link both directions using `bear://x-callback-url/open-note?id={UUID}` rather than wikilink `[[Title]]`. UUIDs survive renames; titles don't. Preserve first-line title per R17 by placing annotations BELOW any embedded PDF/image.