Client Health Review

Client Health Review

The portfolio sweep. intel-weekly-report does this for competitors; this does it for the client base, which is where the revenue already is.

It exists for a specific reason: everything else in workspace/clients/ is per-client and therefore only runs when someone remembers an account. The account nobody remembers is the one that churns. Small firms carry roughly twice the annual churn of large ones, and the difference is not talent — it is that somebody's job is to look at the whole list on a schedule.

Read First

1. Every workspace/clients/*/!_account.md.
2. Each account's onboarding.md, account-plan.md, qbr/, and notes.md.
3. workspace/firm/proof/ — which records are still empty stubs.
4. workspace/sales/opportunities/*/outcome.md — wins with no client folder.

Start with the mechanical pass; it produces the structural facts without judgment:

scripts/validate-account.sh

When to Use

• Monthly or quarterly portfolio review.
• Before starting new prospecting. This is the renewal review rule in AGENTS.md: a renewal inside 60 days or an account with no QBR in two quarters gets surfaced before the firm spends effort on new logos. Acquisition is the expensive channel; running it while an existing account quietly lapses is the mistake this ordering prevents.
• Anything about retention, churn risk, renewals, or where growth could come from.

Signals

Each row is a fact plus the skill that resolves it. Nothing here is a judgment call.

Stale green is the one to take seriously. A health: green last reviewed seven months ago is worse than no file at all, because a human will act on it. Unlike a competitor snapshot, nothing here refreshes itself — the file is only as true as the last person who touched it. Report stale green as a failure, not an item.

Workflow

1. Run scripts/validate-account.sh for the structural pass.
2. Walk every account folder and collect the signals above with dates.
3. Group by what to do, not by client. A list organized by account produces reading; a list organized by action produces action.
4. Compute the portfolio numbers from frontmatter only (below).
5. Write the report.
6. State the top three actions, with an account and an owner. Not ten.

Portfolio Numbers

Computable from !_account.md frontmatter. Report only what the files support, and mark the rest unknown — an estimated retention rate is worse than an absent one.

Do not compute NRR, churn rate, or logo retention here unless the firm records the inputs. If the firm wants those tracked over time, that is firm-pdca-setup with this report as the source of truth — not a number guessed once inside a report.

Output

workspace/clients/reports/{YYYY-MM-DD}-health.md

---
generated: 2026-12-01
accounts_active: 11
accounts_with_success_definition: 8
accounts_missing_qbr: 3
renewals_90d: 2
in_first_90_days: 1
stale_reviews: 4
stale_greens: 1
unfilled_proof_stubs: 3
referenceable: 5
---

Body: Do this first (three actions), Renewals and reviews, At risk, Referral and proof opportunities, Portfolio numbers, Data quality — the accounts whose files are too stale to trust, which is a finding about the firm's habits rather than about a client.

Rules

1. Report only what the files say. Never infer that an account is healthy because nothing is recorded — that is the absence of data, not a green light.
2. Never guess a renewal date, an MRR band, or a health colour.
3. If most accounts are stale, lead with that. A report built on stale files is itself unreliable, and saying so is more useful than ranking fictional risk.
4. Group by action. Cap "Do this first" at three.
5. Do not write into client folders from here. This report reads and recommends; the per-client skills write.

Testing Requirements

1. Run with no client folders; confirm it says the folder is empty and points to client-onboarding rather than producing an empty report.
2. Create an account with health: green and reviewed_at six months old; confirm stale green is reported as a failure, and that validate-account.sh exits non-zero.
3. Create a won outcome.md with no client folder; confirm it appears as "won, not onboarded".
4. Create a proof record with empty metrics; confirm it appears as an unfilled stub.
5. Confirm no portfolio number is reported that the frontmatter does not support.

Related Skills