b1rdmania/outreach-ledger/outreach-ledger

Outreach Ledger

Give a project a nervous system for its in-flight conversations: a ledger of every thread, due-touch flags, and optional read-only inbox polling. The system observes and reminds; humans draft and send.

Reference implementation ships in this folder: outreach.mjs (ledger + CLI), outreach-poll.mjs (read-only IMAP poller with reply AND bounce detection), seed.example.json. Copy and adapt rather than reinvent. Requires node; npm install in this folder pulls the two dependencies (better-sqlite3, imapflow).

Recipe

1. Scope the threads. List every conversation the project has in flight: who, org,

email (if known), channel, current state, what was last sent and when. Ask the user to confirm the list — seeds are facts, not guesses.

1. Ledger table in the project's existing store (SQLite via outreach.mjs, or a

markdown/JSON ledger for code-free projects): target, org, email, thread_subject, channel, status (drafted → sent → replied → in_conversation → terms_sent → signed → dormant → closed, plus bounced as a dead-end — rename states to fit the domain), doctrine, dates, touch_count, notes. Seed idempotently (re-running the seed must add nothing).

1. CLI or checklist: --list (grouped by status), --touch <id> (update state +

next date), --due (rows where next_touch_at ≤ today, each with a suggested action).

1. Due-action wording matters: warm/personal relationships → "human touch due — nudge

the user, no draft"; cold/transactional sends → "day-N follow-up due — draft with approval". Third un-replied touch → suggest marking dormant.

1. Inbox poller (optional, needs mailbox creds in a gitignored .env): IMAP scan since

last-seen UID; store the UID cursor. Two reconciliations, both mandatory:

• Reply: a From match on a watched address → flip to replied, surface an alert.
• Bounce: a delivery-status/NDR from mailer-daemon/postmaster → parse the failed

recipient from the body and flip that row to bounced. Without it, a dead address sits at sent forever, indistinguishable from awaiting-reply — the precise failure this skill exists to kill. A reply-only poller is not "working fully". Read-only per the hard rules below.

Hard rules (do not soften)

• No auto-send code path exists, anywhere. The ledger flags; drafting happens with the

user; the user approves every outbound. Do not build a "send follow-up" function even behind a flag.

• Respect the project's contact doctrine. Some threads must never be nudged (a client

who comes to you; a relationship where chasing costs more than silence). Set doctrine: "no-chase" — tracked in --list, structurally excluded from --due.

• Poller is read-only — open folders read-only, touch no flags, unread stays unread.
• Bounces are a state, not a silence. The poller must detect NDRs and mark the row

bounced; a dead address masquerading as awaiting-reply defeats the whole ledger.

• Credentials live in the project's gitignored env file, never committed, never echoed.

Verify before finishing

Run the seed twice (second run = 0 changes). Run --due and sanity-check the suggested actions against the doctrine rules. If a poller was wired: one --once run against the real inbox, confirm it reports without mutating (a message's unread state must survive), and confirm a bounce flips its row to bounced (send one deliberately-bad-address test, or check a past NDR is caught) — not just that replies flip to replied.