match

Given a screenshot of an email (Shortwave, Gmail or Proton), work out which filters.js entries matched it and why, and explain any label the spec does not account for. Use when asked why a message got

SKILL.md

GitHub

Match (screenshot → which filters fired, and why)

Input is a screenshot of one message. Output is a per-entry verdict: which filters.js entries match, on which condition, with which actions — plus an account of every label visible in the screenshot, including the ones no filter explains.

Procedure

1. Read the message off the screenshot

Needed: from address, subject, and — if the message is a mailing list — the List-Id.

  • The sender's address, not the display name. Clients show Allstate where the filter matches *@email.allstate.com. Shortwave and Gmail show the address under the sender name once the message is open; a collapsed row usually does not.
  • The subject as sent, not the client's truncation with ….
  • Note every label chip on the message, and whether the message is in Inbox, Archive or Trash.

If the address or full subject is not legible, fetch it — do not guess. search_threads on the subject returns each hit's sender address and full subject; a List-Id needs get_message with RAW, the only format that carries headers. Say which fields came from the screenshot and which from the API.

2. Run the matcher

node .claude/skills/match/match.js --from <address> --subject "<subject>" [--list <list-id>]

It reads the real spec from the config directory (filters.js, outside the repo — see AGENTS.md → Repo → Files outside git); --filters <path> or FILTERS_FILE overrides. It prints two verdicts per matching entry, because two engines run the same spec:

  • spec — sieve semantics, what ProtonMail runs: from is a case-insensitive glob over the whole address, subject and list are case-insensitive substrings, criteria within one condition are ANDed, conditions within an entry are ORed.
  • gmail — the rendered Gmail query, what actually labeled the mail in Gmail or Shortwave. The queries come from Specs in src/gmail.js, the same function sync.js writes with, so they cannot drift. Term matching is approximate: Gmail matches whole tokens, and the renderer drops short dangling glob fragments, so a Gmail filter can match mail its sieve glob would not.

A spec/gmail disagreement is the interesting result, not a bug in the matcher — report it. A gmail match with no spec match means the live filter is broader than the pattern intends.

Entries that fire nothing are then re-checked for near misses — conditions written for mail like this whose from no longer reaches it. This is how a rule goes dead when a sender changes domain: it matches nothing, reports nothing, and the mail reads as merely unfiltered rather than misfiltered. Two shapes are reported, and a stale rule usually shows both:

  • stale sender — every other criterion matches and only the sender does not, so the condition was written for exactly this mail. A one-word subject fragment does not count; it recurs too widely.
  • sibling domain — the sender shares a distinctive domain label with the message but does not match, e.g. *@acme.co against support@mail.acme.com.

A shared label is not always distinctive. A consumer-mail domain, or a subdomain label common to many senders' notification hosts, raises a near miss against dozens of unrelated conditions at once. Judge by whether the shared label names the sender's organization: a wall of near misses on one generic token is noise, not a wall of dead rules. A label naming a payment or notification intermediary is noise by the same test even though it names a real company — the spec holds one exact address per merchant there, so its conditions are siblings of each other, not of a rule that has gone stale.

Near misses print below the matches in the same entry[N] → … form, under their own heading. A script reading the output — the bulk coverage check in AGENTS.md → Bulk-editing filters.js from a script is one — counts them as coverage unless it splits on that heading first.

A near miss is a finding, not a footnote: the entry names the labels and actions the message was meant to get, so it says what the mail should have done.

3. Account for every label on screen

Three different things can wear the same name (AGENTS.md → Mail setup → Label namespaces), and only one of them comes from this repo:

Chip Source How to tell
Gmail user label a fileinto in filters.js, applied by the Gmail filter the matcher named it
Shortwave built-in Shortwave's classifier — Travel, Calendar, Newsletters, Purchases, Finance, Social, Promotions, Forums, Updates one of those nine names, no matching entry
Shortwave auto-apply rule Shortwave's backend, invisible to Gmail a Gmail label name with no matching entry
Gmail category Gmail's own ML Gmail UI only, never a Shortwave chip

So a screenshot showing Home, Purchases, Updates where only Home matches is fully explained: the other two are built-ins, not missing filters. Never propose a spec change for a built-in — there is no off switch for them; the lever is Settings → Filters → Label skip inbox.

4. When the verdict contradicts the screenshot

The spec is not proof of what is on the account — the account may have drift, or hand-made filters filters.js knows nothing about.

  • Entry matches but the label is absent: the filter may never have been synced, or the mail predates it (Gmail filters are not retroactive). Confirm with a dry run — node src/sync.js --verbose — and check whether that entry's query is in the create list. Set the session title's 🔍 prefix before any live-account check.
  • Nothing matches and the mail looks unfiltered: read the near misses first. A stale from is the likeliest cause, and it is invisible in the plan a dry run prints — a dead rule is still in sync, because the spec and the account agree on a filter that matches nothing.
  • Label present but nothing matches: a hand-made Gmail filter, a Shortwave rule, or a Proton filter. Hand-made Gmail rules populate the API's from/subject fields rather than query — a dry run shows them as deletes. Shortwave rules live in Settings → Filters; the UI has no export, but the rule set is readable from IndexedDB (AGENTS.md → Shortwave → Rules and filters).
  • In Proton, the folder is wrong: filter order decides it — all matching filters run in list order and the last conflicting fileinto wins (AGENTS.md → ProtonMail → Filter order).

5. Report

Render the conditions that matched with the render-filter skill — one row each, in the same table the filter skill states a rule in, so a rule reads the same whether it is being written or explained. Nothing is being written here, so Change and Replaces are empty on every row and drop out.

The table says what the rule matches and does; it has no column for which entry a row came from, or for whether it fired in sieve, in Gmail or neither. Those go in the prose:

  • A spec/gmail disagreement is named on the row it belongs to, with which engine matched — it is the finding, not a footnote.
  • Near misses go in their own table, under a sentence saying they fired nothing. Their Actions column is what the message was meant to get, which is the point of showing them.
  • Then one line per unexplained label, naming its actual source from step 3.

Do not change filters.js or touch an account — this skill diagnoses. If a fix is warranted, render it as its own table with Change filled in, say plainly that nothing has been written, and let the user ask.