Breakthrough Whatsapp Read

---
name: breakthrough-whatsapp-read
description: "Read the owner's own WhatsApp to answer a question, read only, from the WhatsApp Desktop database on their Mac: \"what did X say this week\", \"did anyone reply about the invoice\", \"what happened in the group today\", \"read my WhatsApp\", \"看看 X 这几天讲了什么\". Pulls a reading pack of the last 3 days (or one chat) with voice notes transcribed and media paths listed, looks up related notes in the owner's vault, then answers. Use only when the owner asks. NOT live triage, reply drafts or the board (the WhatsApp Live daemon), NOT writing person notes (breakthrough-person-dossier). Never sends a message and never writes to the vault."
---

# breakthrough-whatsapp-read

Read only. Two scripts turn the local WhatsApp Desktop database into a reading pack and a list of related vault notes; this session reads both and answers the owner's question. ⛔ It never sends a message, never puts a draft on the board, and never writes into the vault.

## Where things are

| What | Where |
|---|---|
| Work dir: reader config, `sweeps/`, the shared `transcripts-cache/` | live config `paths.home`, default `~/WhatsApp-Live`. Its `config.json` is generated by `wa_setup.py sync-reader-config`; do not hand edit it |
| The owner's phone and names, whisper model, ignored chats | that reader config: `my_phone`, `my_names`, `owner_label`, `whisper_model`, `ignored_jids` |
| Vault and people folders for the lookup | reader config `vault`, `person_dirs`, `stop_words` (or pass `--vault`) |
| Flags, outputs, exit codes, what gets indexed | `--help` of each script and the docstring at the top of each file |
| Judgment rules for triage (worlds, stages, drafts) | the owner's vault copy of the whatsapp-live-triage playbook; not needed to answer a question |

`$SKILL` is this skill's folder: `~/.claude/skills/breakthrough-whatsapp-read` for a global install, `<project>/.claude/skills/breakthrough-whatsapp-read` for one installed into a project. Run with `/usr/bin/python3`; the terminal needs Full Disk Access to read the WhatsApp folder.

## How to run

1. **Read.** `/usr/bin/python3 $SKILL/scripts/wa_sweep.py --work-dir <paths.home>` reads every chat of the last 3 days into `<paths.home>`. Always pass `--work-dir` with the install's own home (its progress file header names it): without it the script falls back to `$WA_LIVE_CONFIG`, then to the default folder, which on a Mac with two installs is the other one. For one person or group add `--only-jid <jid>`; either form of a person's jid works. ⛔ Widen the window (`--days N`) or pull an older chat (`--include-jid <jid>`) only when the owner asks, and say first how much more it pulls. The last stdout line is JSON with the `md` and `json` paths.
2. **Look up the vault.** `/usr/bin/python3 $SKILL/scripts/wa_context.py --sweep <json path> --config <paths.home>/config.json`. Its `md` lists candidate notes per chat; ⭐ marks hard matches.
3. **Read, then answer.** Read the pack whole, then the candidates; open the ⭐ notes and any media that carries weight (quotes, screenshots, documents: the pack gives absolute paths). Voice transcripts are raw and uncorrected. Say the gaps out loud: the warnings at the top of the pack, missing media, voice notes that could not be read. A chat with no vault hits means the vault has no record of it; do not fill that in.
4. **If the owner wants to reply**, point them to the board (a one-to-one chat opens WhatsApp prefilled, a group copies the draft) or write the text for them to paste. Claude never sends.

## Good to know

- Everything read here lands in this session's transcript on this Mac, private conversations included. Say so if the owner asks about privacy.
- Database snapshots are deleted after each read unless the reader config sets `keep_snapshot: true`.
- If this session runs on another Mac than the one with WhatsApp Desktop, run both commands on that Mac over ssh and copy the md files back before reading. If that Mac cannot be reached, stop and say so; never answer from a stale local copy.