# Contact ledger schema

This is the file layout the whole system runs on. Build it once, keep it updated every cycle. A spreadsheet or a CSV both work, as long as the seven fields below exist with these exact names.

## Fields

| Field | Type | Rule |
|---|---|---|
| `client_name` | text | One row per client. If a client has two contracts, keep one row and note the second in `notes`, do not split them. |
| `contract_value_or_tier` | text | Free text, but include the cadence word the client actually runs on: "weekly," "biweekly," "monthly," or "quarterly." Example: `Monthly retainer, $1,200/mo`. This word drives the risk thresholds in `references/risk-scoring.md`. If no cadence word is present, the scoring script assumes monthly. |
| `last_owner_initiated_contact_date` | date, `YYYY-MM-DD`, or the literal `unknown` | The last date the owner sent the first message in a thread: an email, a call, a text, a scheduled check-in. A reply to something the client sent first does not count here, only a message the owner started. |
| `last_client_initiated_contact_date` | date, `YYYY-MM-DD`, or the literal `unknown` | The last date the client reached out first: a question, a reply after a gap, a new request. |
| `next_scheduled_touch_date` | date, `YYYY-MM-DD`, or blank | Set by step 11 of the main procedure to the date of this client's next weekly review, every time a touch is confirmed sent, so the ledger always shows when they are next due for a look. Also used for a specific future-dated touch that is already drafted and approved ahead of the normal cycle, a renewal-adjacent check-in on a known date, for example. Cleared once that date passes and a fresh touch is logged for the new cycle. |
| `risk_tier` | one of `green`, `amber`, `red`, `needs input` | Set automatically by `scripts/compute_initiation_gap.py` each run. If you set it by hand before the script is part of your workflow, treat that value as a placeholder the next run will overwrite. |
| `notes` | text | Free text. Use it for: why a client is on a different cadence than their tier suggests, a record of unanswered touches (see `references/cadence-rules.md` for the exact format), a record of any missed same-day reply (`late-reply: YYYY-MM-DD`, same file), and the reason behind a skip. |

## Setup rules

1. **Only active clients.** A client with no current paid work or open relationship does not belong in the ledger. A finished project with no renewal in sight gets removed from the ledger rather than flagged for review.
2. **Dates come from evidence, not memory.** Pull them from an email thread, a CRM activity log, a calendar entry, an invoice date, or a direct statement from the owner in this conversation. If none of those exist for a client, write `unknown` in that field. Do not default to today's date and do not guess a plausible-sounding date.
3. **`unknown` clients go on a separate short list.** Call it "needs owner input" and work through it with the owner before the first scoring run, one client at a time: when did you last reach out, when did they last reach out. Once both dates are filled, the client moves into the normal ledger.
4. **One date format throughout.** `YYYY-MM-DD` everywhere, no exceptions, so the script can parse every row the same way.
5. **The ledger is a living file.** Every approved touch updates `last_owner_initiated_contact_date` and `next_scheduled_touch_date`. Every client-initiated reply updates `last_client_initiated_contact_date`. Both updates happen the same day the event happens; waiting for the next weekly review to log them is too late.

# Risk scoring

How a ledger row turns into a risk tier. This is the logic `scripts/compute_initiation_gap.py` runs; this file is the reference copy so you can score a row by hand if you ever need to check the script's output.

## Step 1: find the cadence baseline

Read the cadence word out of `contract_value_or_tier` (see `references/contact-ledger-schema.md`):

| Word found | Baseline, in days |
|---|---|
| "weekly" | 7 |
| "biweekly" or "bi-weekly" | 14 |
| "monthly" | 30 |
| "quarterly" | 90 |
| none of the above | 30 (monthly is the default assumption) |

The baseline is specific to this client: how often they personally expect to hear from the owner. It is set per account, not as one company-wide rule. A weekly-touch client who goes two weeks without a word from the owner is in a different spot than a quarterly retainer client at the same two weeks.

## Step 2: find the effective last-contact date

Take the later of `last_owner_initiated_contact_date` and `last_client_initiated_contact_date`. A client who reached out on their own counts as a live, current relationship even if the owner has not yet replied (the separate same-day reply rule in `references/cadence-rules.md` covers that gap). If either date is `unknown`, use whichever date is present; if both are `unknown`, the client cannot be scored (see Step 4).

## Step 3: compute the gap and assign a tier

`gap = (today's date) - (effective last-contact date)`, in days.

| Gap, compared to baseline | Tier |
|---|---|
| gap is at or under the baseline | `green` |
| gap is over the baseline, up to and including two times the baseline | `amber` |
| gap is over two times the baseline | `red` |

Example: a monthly-cadence client (baseline 30) with a 45-day gap is `amber`. The same 45-day gap on a weekly-cadence client (baseline 7) is well past two times the baseline and is `red`.

## Step 4: the `needs input` tier

If both contact dates are `unknown`, the tier is `needs input`. The script never guesses a tier here and never defaults to `green`. A client sitting in `needs input` is simply unscored, and that alone says nothing about whether the account is actually at risk. Get real dates from the owner before the next review cycle.

## Recalibrating the thresholds

The 1x / 2x multiplier above is a starting point. Adjust it once a quarter (Phase 3 of the main procedure): walk the ledger with the owner and check which flags turned into real conversations or saved accounts, and which were noise, a client who was simply busy rather than pulling away. If a client's real-world cadence does not match their stated tier (a "monthly" client who in practice talks to the owner every six weeks without ever being at risk), either correct the cadence word in `contract_value_or_tier` or note a client-specific override in `notes`, for example: `cadence override: 45 days, not 30, confirmed with owner 2026-10-01`. The script does not read overrides automatically; apply them by adjusting the cadence word or by treating that client's score as advisory until the schema is extended.

# Cadence rules

The timing rules the whole system runs on: how fast the owner replies, how often a touch goes out, when a gap resets, and when the system stops drafting on its own.

## 1. Response-time rule

Any message a client sends gets a reply from the owner the same business day. This is separate from proactive outreach; it is the floor for reactive response.

Default window: by the end of the business day the message arrives. If a narrower window fits the owner's schedule better (within four hours, before end of morning), set that instead and record it here as the working definition for this owner:

> Current rule: reply by ______ on the same business day a client message arrives.

This rule is checked at the start of every weekly review (main procedure, step 7): any client message from the past week that did not get a same-day reply gets logged in that client's `notes` field as `late-reply: YYYY-MM-DD`, the same format as the no-reply log in §4 below. The log turns a one-week observation into a visible history for that client. Walk the log during the quarterly cadence audit (main procedure, step 17) to see whether a client's late replies are a one-off slip or a recurring pattern worth changing the window itself.

## 2. Touch intervals

Any client sitting at `amber` or `red` after a review gets a drafted touch that same cycle (see the main procedure, Phase 2). The weekly review cadence itself sets the interval, so there is no extra wait-and-see period layered on top of it. A client does not get touched more than once between reviews unless the owner asks for it directly.

## 3. Reset rule

A client-initiated contact (an email, a reply, a call, any message where the client spoke first) resets the gap clock the day it happens. Update `last_client_initiated_contact_date` to that date immediately, the same day it happens, rather than waiting for the next weekly review. This removes the client from the current cycle's flagged list even if the owner has not yet replied to that message (the same-day response rule above still applies on its own).

An owner-initiated touch that goes out and gets approved also resets the clock. Update `last_owner_initiated_contact_date` only on the day it is actually sent, once it has actually gone out, and set `next_scheduled_touch_date` to the date of the client's next weekly review at the same time (main procedure, step 11).

## 4. Stop condition: two unanswered touches

Track unanswered touches in the ledger's `notes` field using this exact format so it is easy to scan:

```
no-reply: 2026-09-12, 2026-10-03
```

Each date is a touch that was sent and approved but got no client reply by the next weekly review. Once a client has two such dates logged with no reply in between, stop drafting further proactive touches for that account automatically. Flag the client for the owner's manual review instead:

> [Client name] has had two proactive touches with no reply (dates in notes). This may be normal (a slow season, an out-of-office) or it may mean the relationship needs a different approach than another check-in. What do you want to do here?

Do not resume automatic drafting for that client until the owner says to, and record their decision in `notes`.

## 5. What does not reset or stop the clock

- A touch that was drafted but not approved by the owner does not count as contact and does not update any date.
- A touch that bounced, was never sent, or sat in a queue does not count.
- The quarterly cadence audit (Phase 3 of the main procedure) can change a client's cadence baseline going forward, but it does not retroactively erase a logged unanswered touch.

# Touch templates

Four drafts, one per trigger type. Pick the one that matches what is actually true about the client right now. Fill only with details that exist in the ledger, the owner's notes, or what the owner supplies in the current conversation. Never invent a result, an event, or a renewal date.

Every draft follows the same rule: check-in, not a pitch. No upsell, no ask, unless the owner specifically wants one folded in for this client.

## Template A: routine check-in (no particular news)

Use when nothing specific has happened since the last contact, the gap has simply grown past the client's cadence baseline.

```
Subject: Checking in

Hi [client name],

It's been a few weeks since we last talked, wanted to check in and see how things are going on your end with [project/account detail from the ledger].

Anything come up I should know about, or anything you need from me right now?

[owner name]
```

## Template B: a result to share

Use when there is a concrete, finished deliverable, metric, or milestone to point to. This is the strongest version of a check-in because it hands the client something concrete to respond to.

```
Subject: [specific result] is done

Hi [client name],

Wanted to flag that [specific result: a deliverable name, a number, a milestone] is finished. [one sentence on what it means for them, concrete, no filler].

Let me know if you want to walk through it or if anything needs adjusting.

[owner name]
```

## Template C: response to a confirmed life or business event

Use only when the owner has independently confirmed a real event (a hire, a move, a product launch the client mentioned, a public announcement). Never invent or infer this from silence; "they have gone quiet" is not itself an event to reference.

```
Subject: Saw the news about [confirmed event]

Hi [client name],

Saw [confirmed event, stated plainly, no guessing at details not confirmed]. Congratulations, that's a big one.

Wanted to check in and see if anything on our side needs to shift because of it, or if you just wanted a quiet week, either way works.

[owner name]
```

## Template D: renewal-adjacent check-in

Use when the client's contract or engagement is approaching a natural renewal point (pull the date from the ledger or ask the owner if it is not recorded).

```
Subject: Checking in ahead of [renewal period]

Hi [client name],

With [renewal period, e.g. "the end of the quarter" or an actual date] coming up, wanted to check in before then rather than have it be a surprise conversation.

How are you feeling about how things have been going? Anything you'd want different going forward?

[owner name]
```

## Filling rules (apply to all four)

1. Pull `[client name]` and any project detail straight from `client_name` and `contract_value_or_tier` in the ledger, or from the owner's own words this turn.
2. Never state a result, number, or event the owner has not confirmed is true and finished.
3. Keep the subject line plain and literal. No urgency language, no exclamation points.
4. If the owner wants an ask folded in (a renewal pitch, an upsell) for a specific client, add it as its own short paragraph at the end, kept separate from the check-in.

# Contact ledger, worked example

A filled ledger as of 2026-10-27, for a one-person consulting shop with seven active clients across three cadence tiers. Use this as the pattern when you build a real one; the field order and date format match `references/contact-ledger-schema.md` exactly.

| client_name | contract_value_or_tier | last_owner_initiated_contact_date | last_client_initiated_contact_date | next_scheduled_touch_date | risk_tier | notes |
|---|---|---|---|---|---|---|
| Dana Whitfield | Monthly retainer, $1,200/mo | 2026-09-10 | 2026-09-02 | | amber | gap computed 2026-10-27 run |
| Marcus Oduya | Weekly retainer, $2,000/mo | 2026-10-20 | 2026-10-22 | | green | replies fast, easy client |
| Priya Chandrasekaran | Quarterly project, $6,500 | 2026-04-10 | unknown | | red | last big deliverable shipped in April, no word since |
| Hal Jennison | Monthly retainer, $950/mo | 2026-08-01 | 2026-08-01 | | red | no-reply: 2026-09-08, 2026-10-01 (flagged for manual review per cadence-rules.md) |
| Sofia Reyes | Biweekly retainer, $1,800/mo | 2026-10-24 | 2026-10-24 | | green | new client, onboarded September |
| Tom Okafor | Monthly retainer, $1,100/mo | unknown | unknown | | needs input | inherited from a referral, no history logged yet, ask Tom directly or check old email |
| Lindsey Marr | Quarterly project, $4,000 | 2026-09-05 | 2026-09-30 | 2026-12-01 | green | renewal conversation set for early December |

# Worked example: one client, start to finish

This walks one row from `examples/contact-ledger-example.md` through a full weekly review cycle: scoring, template selection, drafting, approval, and the ledger update afterward.

## Client: Dana Whitfield

**Ledger row before this cycle (as of 2026-10-27):**

| Field | Value |
|---|---|
| client_name | Dana Whitfield |
| contract_value_or_tier | Monthly retainer, $1,200/mo |
| last_owner_initiated_contact_date | 2026-09-10 |
| last_client_initiated_contact_date | 2026-09-02 |
| next_scheduled_touch_date | (blank) |
| risk_tier | amber |
| notes | (blank) |

## Step 1: scoring (per `references/risk-scoring.md`)

- Cadence word found: "monthly," baseline is 30 days.
- Effective last contact: the later of the two dates, 2026-09-10.
- Gap as of 2026-10-27: 47 days.
- 47 is over the 30-day baseline but not over 60 (two times baseline), so the tier is `amber`. This matches `scripts/compute_initiation_gap.py`'s output for this row.

## Step 2: template selection (per `references/touch-templates.md`)

No specific finished deliverable is on record for Dana this month, and no confirmed life or business event, and no renewal window is close. This is a plain gap. Template A, routine check-in, is the fit.

## Step 3: drafted touch

```
Subject: Checking in

Hi Dana,

It's been a few weeks since we last talked, wanted to check in and see how things are going on your end with the retainer work.

Anything come up I should know about, or anything you need from me right now?

[owner name]
```

## Step 4: presented to the owner

> **Dana Whitfield, flagged amber (47-day gap, 30-day baseline).** Draft above, routine check-in, no specific news to reference. Send as-is, edit, or skip this cycle?

## Step 5: owner's response (example)

The owner approves the draft without changes.

## Step 6: ledger update after approval

| Field | Value after update |
|---|---|
| last_owner_initiated_contact_date | 2026-10-27 (the date it was actually sent) |
| next_scheduled_touch_date | 2026-11-03 (the date of Dana's next weekly review, per step 11) |
| risk_tier | will recompute to `green` on the next run, since the gap resets to 0 |
| notes | unchanged, no prior unanswered touches logged for this client |

## If the owner had said "skip this one" instead

The row stays exactly as it was, `risk_tier` stays `amber`, and no penalty or re-flag happens until the next cycle's review, per `references/cadence-rules.md`. Nothing is sent, scheduled, or queued without that explicit yes.

#!/usr/bin/env python3
"""
compute_initiation_gap.py

Reads a contact ledger CSV (fields defined in references/contact-ledger-schema.md)
and prints a risk-scored, sorted report. Optionally writes the computed
risk_tier back into an output CSV.

No network calls, no third-party packages: standard library only.

Usage:
    python3 compute_initiation_gap.py ledger.csv
    python3 compute_initiation_gap.py ledger.csv --as-of 2026-10-27
    python3 compute_initiation_gap.py ledger.csv --write scored_ledger.csv

CSV columns expected (header row required, this exact spelling):
    client_name
    contract_value_or_tier
    last_owner_initiated_contact_date   (YYYY-MM-DD or "unknown")
    last_client_initiated_contact_date  (YYYY-MM-DD or "unknown")
    next_scheduled_touch_date           (YYYY-MM-DD or blank)
    risk_tier                           (overwritten by this script)
    notes

Scoring logic mirrors references/risk-scoring.md exactly. If that file
changes, update the CADENCE_BASELINES and the tier thresholds below to match.
"""

import argparse
import csv
import sys
from datetime import date, datetime

CADENCE_BASELINES = [
    ("biweekly", 14),
    ("bi-weekly", 14),
    ("weekly", 7),
    ("quarterly", 90),
    ("monthly", 30),
]
DEFAULT_BASELINE_DAYS = 30

REQUIRED_FIELDS = [
    "client_name",
    "contract_value_or_tier",
    "last_owner_initiated_contact_date",
    "last_client_initiated_contact_date",
    "next_scheduled_touch_date",
    "risk_tier",
    "notes",
]

TIER_SORT_ORDER = {"red": 0, "amber": 1, "green": 2, "needs input": 3}


def parse_date(value):
    """Return a date object, or None if the value is unknown/blank/unparseable."""
    if value is None:
        return None
    value = value.strip()
    if not value or value.lower() == "unknown":
        return None
    try:
        return datetime.strptime(value, "%Y-%m-%d").date()
    except ValueError:
        print(
            f"warning: could not parse date '{value}', treating as unknown",
            file=sys.stderr,
        )
        return None


def baseline_days(tier_text):
    """Find the cadence baseline, in days, from the free-text tier field."""
    lowered = (tier_text or "").lower()
    for keyword, days in CADENCE_BASELINES:
        if keyword in lowered:
            return days
    return DEFAULT_BASELINE_DAYS


def score_row(row, as_of):
    owner_date = parse_date(row.get("last_owner_initiated_contact_date"))
    client_date = parse_date(row.get("last_client_initiated_contact_date"))

    if owner_date is None and client_date is None:
        return "needs input", None

    effective_dates = [d for d in (owner_date, client_date) if d is not None]
    effective_last_contact = max(effective_dates)
    gap_days = (as_of - effective_last_contact).days

    baseline = baseline_days(row.get("contract_value_or_tier"))
    if gap_days <= baseline:
        tier = "green"
    elif gap_days <= 2 * baseline:
        tier = "amber"
    else:
        tier = "red"
    return tier, gap_days


def load_rows(path):
    with open(path, newline="", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        missing = [field for field in REQUIRED_FIELDS if field not in (reader.fieldnames or [])]
        if missing:
            sys.exit(
                "error: ledger is missing required column(s): "
                + ", ".join(missing)
                + "\nSee references/contact-ledger-schema.md for the exact field list."
            )
        return list(reader), reader.fieldnames


def main():
    parser = argparse.ArgumentParser(description="Score a contact ledger's initiation gaps.")
    parser.add_argument("ledger_csv", help="Path to the contact ledger CSV file.")
    parser.add_argument(
        "--as-of",
        help="Date to score against, YYYY-MM-DD. Defaults to today.",
        default=None,
    )
    parser.add_argument(
        "--write",
        help="Optional path to write a copy of the ledger with risk_tier filled in.",
        default=None,
    )
    args = parser.parse_args()

    as_of = parse_date(args.as_of) if args.as_of else date.today()
    if as_of is None:
        sys.exit(f"error: could not parse --as-of value '{args.as_of}', expected YYYY-MM-DD")

    rows, fieldnames = load_rows(args.ledger_csv)

    scored = []
    for row in rows:
        tier, gap_days = score_row(row, as_of)
        row["risk_tier"] = tier
        scored.append((row, gap_days))

    # Sort: red, amber, green, needs input; within a tier, longest gap first.
    def sort_key(item):
        row, gap_days = item
        tier_rank = TIER_SORT_ORDER.get(row["risk_tier"], 99)
        gap_rank = -(gap_days if gap_days is not None else -1)
        return (tier_rank, gap_rank)

    scored.sort(key=sort_key)

    print(f"Risk report as of {as_of.isoformat()}\n")
    header = f"{'Client':<28} {'Tier':<12} {'Gap (days)':<12} Notes"
    print(header)
    print("-" * len(header))
    for row, gap_days in scored:
        gap_text = str(gap_days) if gap_days is not None else "n/a"
        print(f"{row['client_name']:<28} {row['risk_tier']:<12} {gap_text:<12} {row.get('notes', '')}")

    if args.write:
        with open(args.write, "w", newline="", encoding="utf-8") as f:
            writer = csv.DictWriter(f, fieldnames=fieldnames)
            writer.writeheader()
            for row, _ in scored:
                writer.writerow(row)
        print(f"\nWrote scored ledger to {args.write}")


if __name__ == "__main__":
    main()

Look at who initiated the last few contacts, more than how the client sounded in them. If you've been the only one sending messages for weeks and the gap keeps growing past that client's usual rhythm, that's the warning sign.

It's common, and it's exactly what this skill tracks: if you're always the one reaching out while the other side stays passive, that imbalance is the first readable sign of disengagement, often before the client ever says anything.

Keep it short and no-agenda: a real update or just a plain check-in. Skip anything that reads like a renewal pitch or a sales nudge. If you want to fold in an ask for a specific client, put it in its own short paragraph at the end, separate from the check-in.

Weekly is enough for most owner-run books of business. Daily is noise, monthly is often too late to catch the gap before it becomes permanent silence.

One unanswered check-in just means try again at the next cadence. Two in a row is where the skill stops drafting automatically and hands the account to you for a manual call.

If you can't say when a client last reached out to you first, you're relying on a feeling. Writing the last-contact dates down replaces the feeling with a number.