# Pipeline record schema

One record per open deal. Every field below has to exist on every record before that deal counts as "tracked." A deal with no record is a deal that gets forgotten, and a record missing a field is a record nobody can trust in six weeks.

## Fields

| Field | Type | Required | Rule |
|---|---|---|---|
| `deal_name` | text | yes | The client or project name, exactly as the owner says it. Not a code name, not an abbreviation only you understand. |
| `contact_name` | text | yes | The person who actually replies to messages, not just the company name. |
| `source` | text | yes | Where the deal came in: referral, inbound form, cold outreach, repeat client, event. One word or short phrase is enough. |
| `status` | enum | yes | One of: `prospect`, `proposal sent`, `negotiating`, `won`, `lost`, `stalled`. See "Status definitions" below before you pick one. |
| `last_contact_date` | date (YYYY-MM-DD) | yes | The date of the most recent real exchange that actually took place: a call, an email the client sent or replied to, a meeting. |
| `next_follow_up_date` | date (YYYY-MM-DD) | yes while `status` is open | When the next touch is due. Set this every time you update the record, never leave it pointing at a date that already passed without either touching the deal or setting a new date. |
| `outcome` | text | yes once closed | Blank while open. Filled in only when `status` becomes `won`, `lost`, or `stalled`: one line on what happened and why. |
| `value` | number or range | optional | The deal's rough dollar value, if known. Leave blank rather than guess. |
| `notes` | text | optional | Anything that affects the next touch: a stated objection, a scheduling constraint, a thing the client asked you not to forget. |

## Status definitions

- **prospect**: first contact made, no proposal sent yet.
- **proposal sent**: a proposal or quote is in the client's hands and you are waiting on a response.
- **negotiating**: the client has responded with questions, pushback, or a counter, and the deal is still live.
- **won**: the client said yes and the work is booked or started.
- **lost**: the client said no, or went quiet long enough past the cadence that it counts as dead (see `references/follow-up-cadence.md` for how long is long enough).
- **stalled**: not dead, not moving. The client went quiet mid-conversation but has not actually said no. Stalled deals still need a `next_follow_up_date`; "stalled" is not an excuse to stop tracking a date.

## The one hard rule

Never fill in a status, a date, or an outcome you have not confirmed. If a deal has no record yet and the only source is a memory, a thread, or a call note, draft the record from that source and mark every field you are not sure of as `[confirm]` instead of guessing. Show the owner the draft and get a yes or a correction before the record counts as real. A wrong date is worse than a missing one, because a missing one gets noticed and a wrong one gets trusted.

## When to update a record

- The moment contact happens: update `last_contact_date` and set a new `next_follow_up_date`.
- The moment a deal's status changes: update `status` immediately, don't batch it for later.
- The moment a deal closes: fill in `outcome` the same day, while the reason is still clear in your head.

A record that is one week stale is already starting to lie to whoever reads it next.

# Follow-up cadence

A fixed sequence of touches for any pipeline record that has gone quiet after a proposal or a first contact. The point of writing it down once is that nobody has to decide, from scratch, under pressure, whether "it's only been four days, is it too soon" on every single deal. The cadence decides. The owner only approves the draft.

Default cadence (edit the day counts in Phase 1 setup if the owner's sales cycle runs faster or slower than this):

| Touch | When | Goal | Tone |
|---|---|---|---|
| Touch 1 | Day 2 after the proposal or last reply | Confirm it arrived and is readable, nothing more | Light, no pressure |
| Touch 2 | Day 5 after the proposal or last reply | Surface one specific question or offer to walk through it live | A little more direct |
| Touch 3 | Day 10 after the proposal or last reply | Ask for a clear yes, no, or a real timeline, and say this is the last check-in on this | Direct, closes the loop |

If touch 3 gets no reply within 5 more days, move the record's `status` to `lost` and fill in `outcome` as "no response after full cadence." A deal does not get to sit in `negotiating` forever with no date attached to it.

## Touch 1 template (day 2)

> Subject: [proposal name], just checking it landed
>
> Hi [first name],
>
> Wanted to make sure the proposal I sent on [date] came through okay and the pricing and scope made sense. Happy to walk through any part of it if useful.
>
> [your name]

## Touch 2 template (day 5)

> Subject: Re: [proposal name]
>
> Hi [first name],
>
> Circling back on this. One thing I wasn't sure came across clearly: [specific detail from the proposal, filled in from the actual record, never invented]. Want to hop on a quick call to go through it, or is there something specific holding things up?
>
> [your name]

## Touch 3 template (day 10)

> Subject: Re: [proposal name], checking where this stands
>
> Hi [first name],
>
> I know things get busy, so just want to check in one more time. If now isn't the right time, that's completely fine, just let me know and I'll close this out on my end. If you're still interested, happy to adjust anything that would help it work.
>
> [your name]

## Stop conditions (read these before you draft anything)

- The moment the client replies to any part of the sequence, the sequence stops. Do not send the next scheduled touch into a thread the client has already answered, even if it was already queued for approval.
- Every touch, at every step, goes to the owner as a draft first. Nothing in this cadence sends itself. The cadence decides timing and wording; the owner decides whether it actually goes out.
- If the client gave a specific date they'll respond by ("let me check with my partner by Friday"), hold the cadence and use that date as the new `next_follow_up_date` instead of the generic day counts above.

# Weekly admin loop checklist

Run this start to finish, once a week, on a fixed day. This is the one file to reopen each week. It does not require rereading the full skill first.

Block out 30 to 45 minutes. Most weeks it runs faster once the three streams are actually set up and stable.

## Before you start

- [ ] Confirm all three streams are still live: pipeline records exist for every open deal, the board trigger is still turned on, the email rule set is still active. If any of the three got turned off or broken since last week, fix that stream before running the rest of this checklist against it.

## 1. Pipeline follow-ups (10-15 min)

- [ ] Pull every pipeline record where `next_follow_up_date` is today or earlier.
- [ ] For each one, open `references/follow-up-cadence.md`, find the matching touch, and draft it using the record's real details, not placeholders.
- [ ] Present every draft to the owner. Wait for an explicit yes before anything leaves draft state.
- [ ] For any record where the client already replied since last week, stop that record's sequence and skip drafting a touch for it.
- [ ] Set a new `next_follow_up_date` on every record you touched this week.

## 2. Proposal drafts (5-15 min, depends on call volume)

- [ ] List every call or consultation held since last week's run.
- [ ] For each one, pull the call notes or transcript and draft the proposal using `references/proposal-autodraft-template.md`.
- [ ] Leave any price, scope, or term blank if the notes don't state it. Flag the blank for the owner instead of guessing.
- [ ] Present each draft for edit and approval.

## 3. Board check (5 min)

- [ ] Confirm the board trigger fired on every new inquiry and every stage change from this week. Compare the board against what you know actually happened.
- [ ] If an entry is missing or a trigger clearly failed, do not quietly type it in by hand and move on. Write it down as a broken-trigger flag for the owner. A hand-fix this week just means the same entry goes missing again next week.

## 4. Email triage (5-10 min)

- [ ] Run this week's queue of flagged email through the active rule set.
- [ ] For everything in the "client reply needed" bucket, present the pre-drafted reply to the owner before anything sends.
- [ ] Spot-check a handful of items in the "no action needed" bucket to confirm they were sorted correctly.

## 5. Close out the week (5 min)

- [ ] Update the `outcome` field on every pipeline record that closed this week: `won`, `lost`, or `stalled` past its last cadence touch.
- [ ] Note anything that felt off this week (a stream that's getting slower to update, a rule set catching the wrong things) so Phase 3's monthly check has something concrete to look at.

## Done when

Every box above is checked, every draft this week was either approved or explicitly held back by the owner, and no pipeline record was left with a `next_follow_up_date` in the past.

# Stream diagnostic

Three questions that measure how broken each of the three admin streams is. Ask them in Phase 1 before building anything, and ask them again every month in Phase 3 so this month's numbers can be checked against last month's. The questions are the instrument; building the record, the trigger, and the rule set is downstream of what they turn up.

## The three questions

Ask the owner directly, in this order, and write the answer down with the date:

1. **Proposals**: "How many of your open proposals have no next-follow-up date set?" Count every open deal where nobody can say, without checking, when the next touch is due.
2. **Board**: "Is there one single place every deal gets recorded, or does it live across memory, threads, and notebooks?" The answer is either "one place" or a list of where deals actually live.
3. **Email**: "Roughly how many emails land in a working day, and how many of those actually need your reply?" Two numbers: total volume, and the reply-needed subset.

Write the raw answers down verbatim before scoring them. A guess rounded up to sound better defeats the point of asking.

## Scoring and ranking

Score each stream 0 to 3 using this table:

| Score | Proposals | Board | Email |
|---|---|---|---|
| 0 | Every open deal has a next-follow-up date | One single place, confirmed | Owner can clear the inbox same day |
| 1 | A few deals missing a date | Mostly one place, a couple of stragglers elsewhere | A backlog builds but clears within the week |
| 2 | Most deals missing a date | Deals live in two or three different places | A backlog that never fully clears |
| 3 | No deal has a tracked date | Nobody could say where most deals live | The owner stops opening the inbox some days |

Rank the three streams from highest score (most broken) to lowest. Build Phase 1 in that order. Do not start the board or email setup before the highest-scored stream has its record in place, unless the owner explicitly asks to work on a lower-scored stream first.

## Logging for the monthly re-run

Keep a running log, one row per month, so Phase 3 step 14 has something to compare against:

| Month | Proposals (count, no date) | Board (score) | Email (total / reply-needed) |
|---|---|---|---|
| 2026-10 | 4 | 2 | 38 / 11 |

A score moving up from last month's log means a stream is sliding back toward where it started, even if the system looks set up on paper. A score holding steady or dropping means the stream is actually working.

# Board trigger setup

Two ways to make the client board log itself instead of depending on someone to drag a card. Pick one path based on what the owner already runs. Either path ends the same way: a new inquiry or a stage change creates or updates a board entry because an event fired it.

## Decision

- If the owner already pays for a client-management tool with workflow triggers (a Dubsado- or HoneyBook-style tool), use Path A. There is no reason to stand up a second system next to a tool they already run.
- If the owner has no such tool, or wants a board they control directly, use Path B with Twenty or EspoCRM.

## Path A: vendor workflow trigger (Dubsado, HoneyBook, similar)

1. Open the tool's workflow or trigger builder.
2. Create a trigger on "new lead" or "new inquiry form submission." Set its action to "create or update a project/client record" with the inquiry's name, contact details, and source carried over directly.
3. Create a second trigger on "project status changed." Set its action to log the new status and the date of the change on the client's record.
4. Test both triggers with one real inquiry and one real status change before relying on them. Confirm the record updates on its own.
5. If the tool supports it, point a webhook from the same trigger at the pipeline record (`references/pipeline-record-schema.md`) so a new inquiry also creates the matching pipeline record in the same step.

## Path B: self-hosted API wiring (Twenty, EspoCRM)

Both tools expose a REST API that accepts a bearer or API-key token and a JSON payload. The pattern is the same for either; field names differ slightly.

**Auth**: generate an API key from the tool's settings (Twenty: Settings > API & Webhooks; EspoCRM: Administration > API Users). Store the key as an environment variable on whatever runs the call, never typed into a shared document or committed to a repo.

**Creating a record on a new inquiry** (example payload, Twenty-style):

```
POST https://<workspace>.twenty.com/rest/companies
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "name": "Harbor Street kitchen remodel",
  "domainName": "",
  "employees": null,
  "customFields": {
    "source": "referral",
    "stage": "prospect"
  }
}
```

**Updating a stage on a stage change** (example, EspoCRM-style):

```
PUT https://<instance>/api/v1/Opportunity/<record_id>
X-Api-Key: <API_KEY>
Content-Type: application/json

{
  "stage": "Negotiation",
  "lastContactDate": "2026-10-17"
}
```

Wire the call to fire from wherever the new-inquiry or stage-change event actually originates: a form submission webhook, a calendar booking tool's completion hook, or a scheduled poll of an inbox label if no webhook exists. The call fires because the event happened, with no manual step in between.

## Testing either path

1. Run one real test case through the full path: submit a real inquiry, confirm the record appears on its own.
2. Trigger one real stage change and confirm the date and stage update on their own.
3. Confirm with the owner that both tests passed before marking the board stream as live (Phase 1 step 6).

## When it breaks

A trigger that stops firing silently is worse than no trigger at all, because the board looks current while it is actually stale. Phase 2 step 10 and Phase 3 step 15 both check for this. A broken trigger gets rebuilt from this file, not hand-patched for one week at a time.

# Proposal autodraft template

The template a proposal draft fills from a call's notes or transcript. The agent populates every field it can support from the source material and leaves the rest for the owner.

## Setting up the handoff

1. Confirm what the owner already uses to capture calls: a transcription tool (Fathom, Fireflies, or similar) or their own written notes.
2. If a transcription tool is in use, set up its export or webhook so a finished call's transcript reaches wherever the agent drafts from. If the owner only takes written notes, use those directly as the source.
3. Map the source to the template fields below. A transcript rarely states every field outright. Pull only what is actually said.

## Template

```
# Proposal: [client name]

Date: [date of this draft]
Prepared for: [contact name]

## Scope
[What was discussed as the work itself. Pull from the transcript or notes; do not add detail not stated.]

## Deliverables
[What the client will receive, listed as discussed.]

## Timeline
[Start date, duration, or milestones, only if the call stated one.]

## Price
[The number or range discussed, only if stated. If no number was discussed, leave this blank and flag it for the owner instead of estimating one.]

## Payment terms
[Deposit, schedule, or terms, only if discussed. Otherwise blank.]

## Assumptions / exclusions
[Anything the client said is out of scope, or a condition they mentioned.]

## Next steps
[What the call ended on: a signature, a follow-up call, a decision date.]
```

## Field-filling rules

- A field with no supporting line in the transcript or notes stays blank, marked `[confirm with owner]`. It never gets filled with a plausible-sounding guess.
- A price is the field most likely to get invented. If the transcript says "somewhere around" or gives a range, carry the range exactly as said, not a rounded or averaged number.
- Scope and deliverables come from what the client agreed to during the call, not from the agent's own idea of what the job should include.

## Handing off the draft

Present the filled template to the owner for edit and approval before it becomes a sent proposal. Flag any blank field explicitly in that handoff.

# Email triage rules

How to build the plain-English rule set that sorts incoming mail into the three buckets the owner's inbox actually has, and how to audit that rule set later.

## The three buckets

- **Client reply needed**: anything from an existing contact, an open pipeline record, or a new inbound inquiry.
- **Vendor or admin**: suppliers, subcontractors, billing, scheduling confirmations, anything operational that needs filing but not a reply.
- **No action needed**: newsletters, marketing mail, notifications with no reply expected, threads already closed.

## Drafting the first rule set

1. Pull five to ten real emails from the owner's actual inbox, covering a normal week.
2. For each one, ask the owner which bucket it belongs in and why. Write the "why" down; it becomes the rule.
3. Turn each answer into an If/Then rule: a condition (sender, subject keyword, thread status) and the bucket it maps to. `examples/sample-triage-rule-set.md` shows the finished format.
4. For the "client reply needed" bucket, also draft a short pre-written reply for the most common inquiry type, so the owner reviews a draft rather than writing from a blank page.
5. Build the rule set in whatever tool the owner already has: a rules engine like Inbox Zero, or the native filters in their mail client.

## Getting it approved

Present the full rule set to the owner before turning any rule on. A rule set changes what the owner sees every day, so it carries the same approval weight as a drafted message. One clear yes covers the whole set.

## Auditing an existing rule set (Phase 3, monthly)

1. Pull a sample of this month's unsorted or misfiled email: anything that landed in the wrong bucket or in no bucket at all.
2. Look for a pattern: a new sender type, a new subject-line keyword, a new vendor. A one-off miss is not worth a new rule; a repeating pattern is.
3. Draft the new rule the same way as step 3 above, and get the owner's approval before turning it on.
4. Record the misfiled-email rate (misfiled count over total sampled) for the monthly report in `references/monthly-system-health-check.md`.

# Monthly system health check

The once-a-month procedure that re-runs the original diagnostic and catches a stream quietly sliding back toward manual work before it fully breaks. This is the file Phase 3 runs from.

## Why this exists

A system that gets set up once and never checked again decays. A trigger stops firing and nobody notices for three weeks. A rule set stops catching a new vendor's emails. A date field quietly stops getting updated. This check exists to catch that drift on a fixed schedule, before it turns into a visible failure.

## Procedure

1. Re-run the three questions in `references/stream-diagnostic.md` and log this month's answers in its tracking table.
2. Compare this month's scores against last month's row in that same table. A score that went up means that stream is sliding backward.
3. Pull the board-trigger failure log from Phase 2 step 10 of the weekly loop. Count how many silent failures happened this month. More than one or two means the trigger needs a full rebuild using `references/board-trigger-setup.md`.
4. Run the rule-set audit in `references/email-triage-rules.md` against a sample of this month's unsorted or misfiled email. Record the misfiled rate.
5. Assemble the three numbers into one short report: open proposals with no next-follow-up date, board-trigger failures this month, and the misfiled-email rate.

## Thresholds worth flagging to the owner

| Number | Flag it when |
|---|---|
| Open proposals with no date | Any count above zero |
| Board-trigger failures | More than one or two in a month |
| Misfiled-email rate | Rising for two months in a row, even if the raw count is small |

## Reporting

Give the owner the three numbers plainly, with no softening. A flat "proposals: 2, trigger failures: 3, misfiled rate: 14%" tells the owner more than a paragraph about how things are going well. If a number crossed a threshold above, say which stream needs a fix before anything else gets added to the system.

## Copy-paste checklist: the monthly health check

- [ ] Stream-diagnostic questions re-run and logged against last month's row
- [ ] Board-trigger failure log pulled and counted for the month
- [ ] Email rule set audited against a sample of this month's misfiled mail
- [ ] All three numbers reported to the owner, unsoftened
- [ ] Any number past its threshold flagged with the stream that needs fixing

# Filled pipeline record example

Three records, filled in the way `references/pipeline-record-schema.md` expects: real values, not placeholders. Use these as the format to copy, not as content to reuse.

## Record 1: open, mid-cadence

| Field | Value |
|---|---|
| `deal_name` | Harbor Street kitchen remodel |
| `contact_name` | Dana Whitfield |
| `source` | referral (from the Ortiz job) |
| `status` | proposal sent |
| `last_contact_date` | 2026-10-09 |
| `next_follow_up_date` | 2026-10-14 |
| `outcome` | (blank, still open) |
| `value` | $38,000 |
| `notes` | Dana mentioned she's also getting one more quote, wants to decide by end of month. Proposal sent 2026-10-09, touch 1 sent 2026-10-11, no reply yet, touch 2 due 2026-10-14. |

## Record 2: won

| Field | Value |
|---|---|
| `deal_name` | Ridgeline deck build |
| `contact_name` | Marcus Lee |
| `source` | inbound form |
| `status` | won |
| `last_contact_date` | 2026-10-06 |
| `next_follow_up_date` | (blank, closed) |
| `outcome` | Signed 2026-10-06, $14,500, start date set for November. |
| `value` | $14,500 |
| `notes` | Repeat potential, mentioned wanting a fence quote next spring. |

## Record 3: stalled

| Field | Value |
|---|---|
| `deal_name` | Pine Avenue bathroom |
| `contact_name` | Rosa Delgado |
| `source` | cold outreach |
| `status` | stalled |
| `last_contact_date` | 2026-09-22 |
| `next_follow_up_date` | 2026-10-20 |
| `outcome` | (blank, still open, tracked as stalled not lost) |
| `value` | $9,200 |
| `notes` | Went quiet after touch 2, full cadence not yet exhausted. One more touch scheduled before this moves to `lost`. |

Each record sticks to what was actually confirmed. The stalled deal carries no price beyond what was actually discussed, its close date is never guessed, and its status is always one of the six allowed values rather than a label like "probably interested." If a field is genuinely unknown, it stays blank or marked `[confirm]`, never filled with a guess dressed up as a fact.

# Sample email triage rule set

A worked example of a starter rule set, in the plain-English format described in `references/email-triage-rules.md`. Copy the shape, not the specific senders, since every owner's inbox is different. Show the owner a draft built from their own inbox before turning any of it on.

## Bucket 1: client reply needed

Anything from a known client, a thread already in `negotiating` or `proposal sent` status, or a new inbound inquiry.

| If the email... | Then... |
|---|---|
| Comes from a contact listed on an open pipeline record | File under "client reply needed" and pre-draft a short acknowledgment reply |
| Is a new inquiry (subject contains "quote," "estimate," "availability," or similar) with no existing record | File under "client reply needed" and flag it to become a new pipeline record |
| Is a reply inside an active follow-up sequence | File under "client reply needed" and immediately flag the matching pipeline record to stop its sequence |

Pre-drafted reply example for a new inquiry:

> Hi [first name],
>
> Thanks for reaching out. I'd love to learn more about the project, could you share a few details: the rough scope, your timeline, and any budget range you're working with? I'll follow up with next steps once I have that.
>
> [your name]

## Bucket 2: vendor or admin

Anything from a supplier, a subcontractor, a bank or accounting tool, software billing, or scheduling confirmations.

| If the email... | Then... |
|---|---|
| Comes from a known vendor or subcontractor domain | File under "vendor or admin" and skip drafting a reply |
| Is a billing receipt, invoice, or payment confirmation | File under "vendor or admin," forward to bookkeeping folder if one exists |
| Is a scheduling or calendar confirmation | File under "vendor or admin" and leave it alone |

## Bucket 3: no action needed

Newsletters, marketing email, notifications from tools that don't need a response, anything already resolved.

| If the email... | Then... |
|---|---|
| Comes from a mailing list or newsletter sender | File under "no action needed" |
| Is a system notification with no reply expected | File under "no action needed" |
| Is a thread already closed (client said thanks, no open question) | File under "no action needed" |

## Before turning any of this on

- Walk the owner through each bucket using five to ten real emails from their actual inbox, not hypothetical examples.
- Get an explicit yes on the rule set as a whole before any rule goes live. A rule set changes what the owner sees every single day, so treat it with the same approval weight as a drafted message.
- Revisit this file during the monthly check (`references/monthly-system-health-check.md`) and add rules for any new sender or email type that keeps landing outside these three buckets.

Because it depends on someone remembering to drag a card or type an entry. The fix is wiring the board to a trigger, a workflow automation in a tool like Dubsado or HoneyBook, or an API call into a self-hosted board like Twenty or EspoCRM, so a new inquiry or stage change logs itself the moment it happens.

Give every open deal a record with a next-follow-up date, then pull everything due today or earlier at the start of each week and draft the matching touch from a set cadence (day 2, day 5, day 10, or whatever fits your sales cycle) before you send it.

Draft a plain-English rule set that sorts mail into the buckets your inbox actually has, client reply needed, vendor or admin, no action needed, using a tool like Inbox Zero or your mail client's own rules, and review the client-reply bucket's drafted replies each week instead of reading every email cold.

No. Pull a proposal draft straight from your call notes or transcript (tools like Fathom or Fireflies work for this) so the first version is already filled with what was actually said, and your only job is to edit and approve it.

Check it monthly against three questions: how many open proposals have no next-follow-up date, is there one single place every deal gets recorded, and is your inbox volume still manageable. If those numbers aren't improving, a stream's setup needs fixing before you add more to it.

Don't quietly re-enter the missing data by hand and move on. Flag it as a broken trigger and fix the trigger itself, because patching it manually just hides the same failure for next week.