commitment_tracker v1.0.0

name: commitment_tracker description: "Sweep email, chat, and meeting notes for commitments made and received, and keep a persistent open/done/overdue ledger that surfaces overdue items first, with source tracing for every entry and a fixed alert cadence. Use when someone asks what was promised, who owes what, what is overdue, to track follow-ups across messages, or to sweep an inbox or meeting notes for action items and promises. Distinct from a one-shot action-item list: this ledger persists across sweeps, dedupes, and never loses the original promise."

Commitment Tracker

Purpose

Promises get made in email threads, chat, and meetings, then buried. This skill turns those scattered promises into one persistent ledger: every commitment made (I owe) and received (they owe), traced to its source, sorted overdue first, and followed up on a cadence until there is evidence it is done. The ledger is the system of record. A fresh list regenerated from memory each time is the failure mode this replaces.

Bundled CLI: bin/commitments.py (JSON ledger, no dependencies). Run it with --ledger <path>; the ledger file lives wherever the user keeps working state, never inside this skill folder.

Workflow

1. Set the sweep scope. Name the sources (inbox, chat channels, meeting notes), the time window, and the ledger file. Record the window start as the sweep watermark. Sweep only material the user is permitted to share with you, and only the window after the last watermark, plus any thread that changed since.
2. Pre-scan for candidates. Run commitments.py scan --text-file <export> --source-date <date of the source, not today> on plain-text exports. The scan flags candidate lines and classifies them; it creates no entries. Read the flagged lines in context yourself, the regex is a net, not a judge.
3. Classify each candidate using speech-act tests.

• Commissive: the speaker commits themselves to a future action ("I will send...", "I'll get you...", an offer that was accepted). This is a commitment, direction made if the user said it, received if someone said it to the user.
• Directive: a request ("can you review..."). Not a commitment until the other side accepts. Look for the acceptance reply in the thread; if there is none, it goes to the confirm queue, not the ledger.
• Suggestion or musing ("we should...", "sometime we ought to..."): not a commitment. Leave it in the notes.
• Conditional ("if legal approves, I'll send it"): a real commitment with a condition. Record the condition in done_when or a history note, do not drop it and do not strip the condition off.

1. Verify each real commitment before adding it. Four checks, all must pass:

• One accountable owner, a person, never "the team".
• An observable outcome: rewrite the what as verb plus deliverable, and set done_when to how anyone can tell it happened.
• A due date or a clear trigger. Resolve relative dates ("by Friday", "tomorrow") against the source message date, never the sweep date, and keep the original phrase in due_phrase. "ASAP" is not a date: entry goes to the confirm queue with a question for the owner.
• A source trace (see Operating Rules). No trace, no entry. Anything failing a check goes to the confirm queue in the report, with the exact question that would resolve it. Never guess an owner or a date to fill the row.

1. Add to the ledger. commitments.py add ... with direction, what, owner, counterparty, due, done_when, confidence (explicit or accepted), and the full source block. The CLI refuses sourceless entries and silently returns "duplicate of C-xxxx" when the same what plus owner plus source ref already exists open. That dedupe is per-source; the same promise repeated in a second thread is a second source worth noting in history, not a second row.
2. Reconcile completions on every sweep. Search the new window for fulfilment evidence (the deliverable arriving, a "done, attached" reply, the file appearing where done_when said it would). Mark done only with evidence: commitments.py done C-xxxx --evidence "...". Partial progress is a history note via renegotiate or block, not done. Blocked entries name who they are waiting on: commitments.py block C-xxxx --waiting-on "...".
3. Handle renegotiations honestly. When a due date moves, use renegotiate, which records old date, new date, and reason, and never overwrites original_due. Days overdue are always counted from the current due date in reports, but the original date stays visible so a twice-moved item reads as twice-moved.
4. Surface, overdue first. Run commitments.py list for the report order (overdue oldest first, then upcoming, then undated, then closed). Run commitments.py alerts on the alert cadence and deliver those nudges in the user's normal channel. Do not send messages to other people about their commitments unless the user has authorized outreach for that entry.
5. Weekly review. Once a week, walk the whole open list: confirm every open entry is still real, chase undated and unowned items out of the confirm queue or cancel them, and cancel (never delete) entries that were withdrawn, with the reason in history. A ledger nobody reviews stops being trusted, and then it stops being used.

Output Contract

Every sweep report has, in this order:

1. Overdue first: ID, what, owner, due date, days overdue, counterparty, last known status. Received commitments lead the section when the user is waiting on others; made commitments lead when the user asked "what do I owe".
2. Due in the next 7 days: same fields, sorted by due date.
3. New this sweep: entries added, each with its source ref.
4. Closed this sweep: done (with the evidence) and cancelled (with the reason).
5. Confirm queue: ambiguous candidates with the one question that resolves each. Directives with no acceptance, undated promises, and ownerless action items live here, never silently in the ledger.
6. Counts: open, overdue, undated, blocked totals, and the new watermark.

Ledger entries always carry: id, what, direction, owner, counterparty, due, due_phrase, original_due, done_when, confidence, source {channel, ref, quote, date}, status, and a history list. IDs are never reused.

Operating Rules

• Source tracing is non-negotiable. Email: use the Message-ID header as the ref (RFC 5322 defines it as the unique identifier for that version of the message). Chat: channel plus message permalink or timestamp plus author. Meeting notes: meeting date plus note title and line or heading. The quote is a short verbatim excerpt of the committing sentence only, kept brief, never a copy of the whole message.
• Relative dates anchor to the source date. Getting this wrong is the most common way these ledgers lie.
• One owner per entry. If two people were named, the owner is whoever accepted; the other is the counterparty or goes in history.
• Never delete an entry. Cancel with a reason, or mark done with evidence. The history is the audit trail.
• Never invent an owner, a date, a done state, or a quote. Unverifiable goes to the confirm queue or gets cut.
• Do not mark anything done because the due date passed. Time passing is not evidence.
• Default alert cadence (a tunable default, not a law): heads-up 2 days before due, a nudge on the due date, escalation at 1, 3, and 7 days overdue, then weekly while overdue. The CLI alerts command implements exactly this. Made commitments nudge the user; received commitments produce a draft follow-up for the user to approve, unless outreach was pre-authorized.
• Privacy: the ledger holds other people's names and promises. Keep it in the user's own storage, share reports only with the user, and quote sources back to third parties only with the user's word.
• If the user already runs a task system, the ledger still owns commitments: export or link rows into that system by ID, and keep status truth here, so the two never disagree silently.

Worked example and the full scan-to-ledger walkthrough are in references/example.md. Cadence tuning, confirm-queue question templates, and edge cases are in references/playbook.md.