---
name: "Churn analysis"
repo: https://github.com/mohitagw15856/pm-claude-skills
source: https://github.com/mohitagw15856/pm-claude-skills/blob/HEAD/skills/churn-analysis/SKILL.md
license: "MIT"
install: "npx skills add mohitagw15856/pm-claude-skills --skill churn-analysis"
page: https://100xlab.com/resources/agent-skills/mohitagw15856-pm-claude-skills--churn-analysis--1wg1n63
---

# Churn Analysis Skill

Produce a structured churn analysis that goes beyond the headline rate — identifying why customers leave, which segments are most at risk, and what interventions will have the highest impact on retention.

## Reads from / Writes to the Brain

If a [`professional-brain`](../professional-brain/SKILL.md) (`brain/`) exists, ground in it instead of re-asking for what you already know:

- **Read first:** `context.md` (metric definitions — what "churn" means here), `knowledge/`, and related segment `entities/`. Run `python3 ../professional-brain/scripts/brain_query.py ./brain "churn"` and carry each fact's provenance tag through.
- **📥 Propose to the Brain:** after producing, propose recording the headline retention finding to `knowledge/` (`[data]`), any retention decision to `decisions/`, and at-risk drivers as `hypotheses/`. Show them, get a yes, then write with `../professional-brain/scripts/brain_write.py … --commit` (append-only, dry-run by default).

## Required Inputs

Ask for these if not already provided:
- **Time period** being analysed (e.g. Q1, last 12 months)
- **Total customers at start of period** and **customers churned**
- **ARR or revenue lost** to churn
- **Churn reasons data** — exit survey results, CSM notes, support data, or sales loss reasons
- **Customer segments** — by tier, industry, cohort, or product line
- **Current retention rate** if known
- **Any recent changes** — pricing, product, support model — that may have affected churn

## Churn Categories

Always classify churn before analysing it:

| Category | Definition |
|---|---|
| **Voluntary — avoidable** | Customer left due to a problem we could have addressed (product gaps, poor onboarding, relationship failures) |
| **Voluntary — unavoidable** | Customer left for reasons outside our control (budget cuts, acquisition, company shutdown) |
| **Involuntary** | Payment failure, contract non-renewal by mistake, admin error |

The interventions for each category are different. Conflating them leads to wrong conclusions.

## Output Format

---

# Churn Analysis: [Product / Segment / Company]
**Period:** [Start date] — [End date]
**Prepared by:** [Name] | **Date:** [Date]

---

## Headline Numbers

| Metric | Value |
|---|---|
| Customers at start of period | [N] |
| Customers churned | [N] |
| **Customer churn rate** | **[X]%** |
| ARR at start of period | £/$/€[X] |
| ARR lost to churn | £/$/€[X] |
| **Revenue churn rate (gross)** | **[X]%** |
| ARR from expansions (same period) | £/$/€[X] |
| **Net revenue retention (NRR)** | **[X]%** |

**Benchmark context:**
- Customer churn rate: [X]% vs. industry benchmark [Y]% — [above / below / in line]
- NRR: [X]% — [What this means: above 100% = expansion offsets churn; below 100% = shrinking base]

---

## Churn Breakdown by Category

| Category | Customers | % of churn | ARR lost |
|---|---|---|---|
| Voluntary — avoidable | [N] | [X]% | £/$/€[X] |
| Voluntary — unavoidable | [N] | [X]% | £/$/€[X] |
| Involuntary | [N] | [X]% | £/$/€[X] |
| **Total** | **[N]** | **100%** | **£/$/€[X]** |

**Avoidable churn as % of total churn:** [X]% — this is the number we can actually influence.

---

## Churn Reasons — Avoidable Churn Only

Rank by frequency. Include ARR weight where data allows.

| Reason | Count | % of avoidable churn | ARR lost | Representative quote |
|---|---|---|---|---|
| [Reason 1 — e.g. "Product missing key feature"] | [N] | [X]% | £/$/€[X] | "[Quote]" |
| [Reason 2] | [N] | [X]% | £/$/€[X] | "[Quote]" |
| [Reason 3] | [N] | [X]% | £/$/€[X] | "[Quote]" |
| [Reason 4] | [N] | [X]% | £/$/€[X] | "[Quote]" |
| Other | [N] | [X]% | £/$/€[X] | — |

**Theme synthesis:** [2–3 sentences grouping the top reasons into 2–3 themes. E.g. "The top three reasons cluster around two themes: product gaps in [area] (affecting X% of avoidable churn) and onboarding failures where customers never achieved value (Y%)."]

---

## Churn by Segment

Identify which segments over- or under-index for churn.

### By Tier

| Tier | Churn rate | vs. Overall | Notes |
|---|---|---|---|
| Enterprise | [X]% | +/-[X]pp | |
| Mid-Market | [X]% | +/-[X]pp | |
| SMB | [X]% | +/-[X]pp | |

### By Cohort (Acquisition Year)

| Cohort | Churn rate | Notes |
|---|---|---|
| [Year 1] | [X]% | |
| [Year 2] | [X]% | |
| [Year 3] | [X]% | |

### By Industry / Use Case (if data available)

| Segment | Churn rate | Notes |
|---|---|---|
| [Segment 1] | [X]% | |
| [Segment 2] | [X]% | |

**Key pattern:** [Which segment has the highest churn rate and what likely explains it]

---

## Timing Analysis

- **Average contract length before churn:** [X months]
- **Highest-risk moment:** [e.g. "Month 3 — when trial value has worn off but full adoption hasn't happened"]
- **Churn timing distribution:**

| When churn occurred | % of churned accounts |
|---|---|
| 0–3 months | [X]% |
| 3–6 months | [X]% |
| 6–12 months | [X]% |
| 12+ months | [X]% |

---

## Early Warning Signals

Based on the churned accounts, identify the signals that preceded churn (and could have triggered earlier intervention):

| Signal | Lead time before churn | How to detect |
|---|---|---|
| [Signal 1 — e.g. "DAU/MAU dropped below 15%"] | [~X weeks] | [Usage dashboard / alert] |
| [Signal 2 — e.g. "No QBR in 90+ days"] | [~X weeks] | [CRM flag] |
| [Signal 3 — e.g. "Champion left the account"] | [~X weeks] | [LinkedIn alert / CSM tracking] |
| [Signal 4] | [~X weeks] | [Detection method] |

---

## Intervention Recommendations

Ranked by estimated impact × feasibility.

| Intervention | Addresses | Est. churn reduction | Effort | Owner |
|---|---|---|---|---|
| [Intervention 1 — e.g. "Improve onboarding for [segment] with dedicated 30-day check-in"] | [Reason 1] | [X accounts / £X ARR] | Low / Med / High | [Team] |
| [Intervention 2] | [Reason 2] | [X accounts / £X ARR] | Low / Med / High | [Team] |
| [Intervention 3] | [Reason 3] | [X accounts / £X ARR] | Low / Med / High | [Team] |

**Priority call:** [Which one intervention, if implemented this quarter, would have the biggest impact and why]

---

## What We Don't Know (Data Gaps)

- [Data gap 1 — e.g. "Exit survey response rate is only 30% — the reasons data may not be representative"]
- [Data gap 2 — e.g. "No product usage data for SMB tier — can't confirm usage signal correlation"]
- [Data gap 3]

---

## Anti-Patterns

- [ ] Do not mix avoidable and unavoidable churn in intervention plans — recommending product fixes for customers who churned due to company shutdown wastes resources
- [ ] Do not calculate churn rate using end-of-period customer count as the denominator — this understates churn; always divide churned customers by the starting cohort
- [ ] Do not rely solely on exit survey data for churn reasons — response rates are typically low and self-selection biases the sample toward customers who are engaged enough to complete a survey
- [ ] Do not recommend interventions without linking them to a specific churn reason — interventions disconnected from root causes will not move retention
- [ ] Do not report only gross revenue churn — without net revenue retention (NRR), a healthy-looking retention number can hide a shrinking revenue base

## Deeper Materials

This skill ships with support files — use them when they are available:

- **`references/avoidability-calls.md`** — Avoidable or Not? The Judgment Calls in Churn Classification. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
- **`templates/churn-report.md`** — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.

## Scoring Rubric (0–40)

Score any output of this skill before handing it over; 32+ is ship-quality.

| Dimension | 0 | 5 | 10 |
|---|---|---|---|
| Rate math integrity | Churn computed on end-of-period count; no NRR | Correct denominator but gross churn only | Correct denominator, gross and net side by side, benchmark context that interprets rather than decorates |
| Avoidability separation | All churn treated as one pool | Categories tabulated but interventions still address the full pool | Avoidable/unavoidable/involuntary split carried through every downstream section; interventions touch only the avoidable share |
| Segment & timing insight | Averages only | Segment table present but no over-index reading | Names the specific over-indexing cell (tier × cohort) and the highest-risk moment, with the "why" |
| Intervention linkage | Recommendations float free of causes | Each intervention names a reason but impact is unsized | Every intervention maps to a ranked reason with estimated accounts/ARR recovered, and the priority call justifies its sequencing |

## Quality Checks

- [ ] Churn rate is correctly calculated (churned ÷ starting cohort, not end-of-period total)
- [ ] Avoidable and unavoidable churn are separated — interventions target avoidable churn only
- [ ] Churn reasons are customer-reported, not internally assumed
- [ ] Segment analysis identifies which segments over-index — not just averages
- [ ] Early warning signals are specific and detectable, not generic ("low engagement")
- [ ] Interventions link directly to the top churn reasons — no recommendations without a root cause match

---

## Supporting file: references/avoidability-calls.md

# Avoidable or Not? The Judgment Calls in Churn Classification

The whole value of churn analysis lives in one column: avoidable vs unavoidable. Get it wrong in either direction and the interventions are wrong — over-classify as unavoidable and you absolve the product; over-classify as avoidable and you chase ghosts. These are the calls.

## The honest taxonomy

| Stated reason | Usually means | Classification |
|---|---|---|
| "Went out of business / acquired" | true exogenous loss | Unavoidable — but verify; "restructuring" often means the champion lost the budget fight, which is avoidable-adjacent |
| "Too expensive" | value story failed, not price | Avoidable until proven — price complaints from customers using <30% of features are adoption failures wearing a price costume |
| "Missing feature X" | sometimes true, often exit politeness | Check usage: were they power users blocked by X, or barely active? The latter churned from low value; X is the excuse |
| "Switched to competitor" | you lost a comparison | Avoidable — get the real comparison via a churned-customer interview; the reason sales heard is rarely the reason |
| "No longer need it" | job disappeared OR was never real | Split: seasonal/project use (semi-avoidable via pause plans) vs bad-fit acquisition (avoidable at MARKETING, not product) |
| Silent non-renewal | drifted — the deadliest kind | Avoidable, and your health score missed it; audit what "green" meant for this account |

## The three-signal verification

Never classify on the exit survey alone. Triangulate: **stated reason** × **usage trajectory** (when did engagement actually die — usually 60-90 days before the cancel) × **support/commercial history**. When the signals disagree, the usage trajectory is the honest one.

## Bad-fit churn is an acquisition finding

A cohort that churns in month 2 having never activated didn't fail at retention — they were sold something they didn't need. Route it to marketing/sales targeting with the segment named, or the analysis punishes the wrong team.

## The intervention mapping rule

Every avoidable cluster must map to an intervention *at the moment the signal appeared*, not at the cancellation: the day usage dipped, the day the champion left, the day the third P1 hit. Interventions at the exit interview are condolence cards.

---

## Supporting file: references/worked-example.md

# Worked Example — Churn Analysis

## The brief

Harborline sells warehouse-operations SaaS to 3PLs and e-commerce brands. FY2025: started the year with 480 customers and $9.6M ARR; 42 accounts churned, taking $684K ARR with them; expansions added $912K over the same period. Exit surveys came back from 16 of the 42 (38%), CSM notes exist for the rest. The CRO wants "the real churn story, not the dashboard number" before renewal-season planning.

## The output

---

# Churn Analysis: Harborline — Full Customer Base
**Period:** 1 Jan 2025 — 31 Dec 2025
**Prepared by:** M. Osei, RevOps | **Date:** 12 Jan 2026

---

## Headline Numbers

| Metric | Value |
|---|---|
| Customers at start of period | 480 |
| Customers churned | 42 |
| **Customer churn rate** | **8.8%** |
| ARR at start of period | $9.60M |
| ARR lost to churn | $684K |
| **Revenue churn rate (gross)** | **7.1%** |
| ARR from expansions (same period) | $912K |
| **Net revenue retention (NRR)** | **102.4%** |

**Benchmark context:**
- Customer churn rate: 8.8% vs. ~10% typical for SMB-heavy B2B SaaS — slightly better than benchmark, but the mix hides a problem (see segments).
- NRR: 102.4% — expansion is just offsetting churn. Above water, but a $228K net gain on a $9.6M base is treading, not compounding.

---

## Churn Breakdown by Category

| Category | Customers | % of churn | ARR lost |
|---|---|---|---|
| Voluntary — avoidable | 24 | 57% | $462K |
| Voluntary — unavoidable | 11 | 26% | $156K |
| Involuntary | 7 | 17% | $66K |
| **Total** | **42** | **100%** | **$684K** |

**Avoidable churn as % of total churn:** 57% — this is the number we can actually influence. The 11 unavoidable losses (two acquisitions, six budget shutdowns of the warehouse function, three company closures) do not belong in the intervention plan.

---

## Churn Reasons — Avoidable Churn Only

| Reason | Count | % of avoidable churn | ARR lost | Representative quote |
|---|---|---|---|---|
| No multi-warehouse support | 9 | 37% | $219K | "We opened a second site in March and had to run it on spreadsheets." |
| Onboarding stalled — never reached live operations | 7 | 29% | $118K | "Four months in, we were still reconciling manually. We stopped believing." |
| Champion left, account unmanaged after | 5 | 21% | $95K | "Our ops lead who chose Harborline moved on; nobody here knew why we had it." |
| Support responsiveness on peak-season issues | 3 | 13% | $30K | "A Black Friday ticket sat for 30 hours." |

**Theme synthesis:** Avoidable churn clusters into two themes: a product ceiling (multi-warehouse, 37% of avoidable ARR) that growing customers hit at exactly the moment they become most valuable, and value-realisation failures (onboarding + champion loss, 50% combined) where the product was never the problem — the account just never got, or lost, its internal reason to exist.

---

## Churn by Segment

### By Tier

| Tier | Churn rate | vs. Overall | Notes |
|---|---|---|---|
| Enterprise (38 accts) | 2.6% | −6.2pp | 1 loss — acquisition |
| Mid-Market (156 accts) | 5.8% | −3.0pp | Product-gap losses concentrate here |
| SMB (286 accts) | 11.2% | +2.4pp | Onboarding and involuntary losses concentrate here |

### By Cohort (Acquisition Year)

| Cohort | Churn rate | Notes |
|---|---|---|
| 2022 and earlier | 4.1% | Survivors are sticky |
| 2023 | 8.3% | |
| 2024 | 12.6% | Worst cohort — acquired during the self-serve push, lightest onboarding |

**Key pattern:** The 2024 SMB cohort is the epicentre: acquired with a low-touch motion, onboarded without a check-in, and churning inside year one. The headline 8.8% is calm; this cell is not.

---

## Timing Analysis

- **Average contract length before churn:** 14 months
- **Highest-risk moment:** Months 3–6 — trial enthusiasm has faded, but live operations (the actual value moment) haven't started for stalled accounts
- **Churn timing distribution:**

| When churn occurred | % of churned accounts |
|---|---|
| 0–3 months | 17% |
| 3–6 months | 31% |
| 6–12 months | 24% |
| 12+ months | 28% |

---

## Early Warning Signals

| Signal | Lead time before churn | How to detect |
|---|---|---|
| No live warehouse connected by day 45 | ~3 months | Onboarding pipeline report |
| Weekly active operators < 3 | ~8 weeks | Usage dashboard threshold alert |
| Champion contact goes dark (no login, no email reply ×3) | ~10 weeks | CRM activity flag |
| Second physical site added without a plan conversation | ~4 months | CSM account-review checklist |

---

## Intervention Recommendations

| Intervention | Addresses | Est. churn reduction | Effort | Owner |
|---|---|---|---|---|
| 30/60/90-day onboarding gates with human check-in for SMB (no account "graduates" without live ops) | Onboarding stalls | ~5 accounts / $85K ARR | Med | CS |
| Multi-warehouse tier on the roadmap with a bridge offer (manual multi-site config + roadmap letter) for accounts opening site #2 | Product ceiling | ~4 accounts / $95K ARR | High | Product |
| Champion-change playbook: detect departure, re-onboard the successor within 30 days | Champion loss | ~3 accounts / $55K ARR | Low | CS |

**Priority call:** The champion-change playbook — lowest effort, immediately deployable, and it protects the *existing* base this quarter while the product ceiling fix (the bigger prize) takes two quarters to ship.

## What We Don't Know (Data Gaps)

- Exit survey response rate is 38% — reasons for 26 of 42 accounts rest on CSM notes, which skew toward relationship explanations over product ones
- No usage telemetry for the 2023-and-earlier cohort (instrumented in Jan 2024) — early-warning thresholds are calibrated on newer accounts only
- Involuntary churn (7 accounts) has no dunning data — we can't yet say how many were recoverable payment failures

---

## Why it's shaped this way

- **The denominator is the starting cohort (480), not year-end count** — the skill's anti-pattern list bans the flattering version of the math.
- **NRR sits beside gross churn in the headline table** because 7.1% gross alone would look healthy while the base quietly treads water; 102.4% tells the truer story.
- **Interventions target only the avoidable 57%** — the acquisitions and shutdowns are reported, then excluded, exactly as the category table demands.
- **Every intervention row names the reason it addresses** — the skill bans recommendations without a root-cause match, so "improve product marketing"-style orphans don't appear.
- **The segment section leads with the over-indexing cell (2024 SMB cohort)**, not tier averages — averages are what the anti-patterns call out as hiding the pattern.
- **The priority call picks the low-effort playbook over the big product fix** — a realistic tension: the largest ARR driver is *not* the first move, and the report says why.
- **Data gaps admit the 38% survey response rate up front**, per the anti-pattern about exit-survey self-selection — the reasons table is presented as evidence, not gospel.

---

## Supporting file: templates/churn-report.md

# Churn report: [period] — [segment scope]

## Headline
Gross churn: [n logos / $x MRR] ([x]%) · Net revenue retention: [x]% · vs last period: [Δ]

## Classification (three-signal verified — references/avoidability-calls.md)
| Cluster | Logos | MRR | Stated vs verified reason | Avoidable? | Signal we missed & when |
|---|---|---|---|---|---|

## The avoidability split
**Avoidable:** [x]% of churned MRR → intervention territory
**Bad-fit at acquisition:** [x]% → routed to [marketing/sales] with segment: […]
**Truly unavoidable:** [x]% → priced into the model, not grieved

## Timing analysis
Engagement death preceded cancellation by median [n] days. The missed window: [what signal, when].

## Early-warning signals (from this cohort's trajectories)
| Signal | Lead time | Detectable today? | If not — instrument: |
|---|---|---|---|

## Interventions (ranked by saved-MRR estimate ÷ effort)
| # | Intervention | Fires at [signal moment] | Est. MRR protected | Owner | Test |
|---|---|---|---|---|---|

## What we'll know next quarter that we don't now
[the instrumentation/interviews committed]

---

## Supporting file: skills/professional-brain/SKILL.md

# Professional Brain Skill

> 🚀 **New to this? Start with the [5-minute Quickstart](../../BRAIN_QUICKSTART.md)** — a folder + one file, with a worked example. This file is the full reference.

Most skills start cold — you paste the same context every time, and decisions made six weeks
ago lose the *why*. This skill gives the library a **memory**: a plain-markdown `brain/` folder
on disk that skills read before they answer and write to after. No vector DB, no cloud — just
grep-able files you (and Claude) can audit and edit.

This is the **state layer** of an AI teammate. Pair it with the action layer (skills that file
tickets / open PRs) and you get a loop: *recall → do the work → record the decision → review.*

## What This Skill Produces

- A scaffolded **`brain/` folder** with a fixed schema (see below).
- **Provenance-tagged** knowledge — every claim says where it came from and how strong it is.
- Four operations you can invoke: **init**, **ingest**, **recall**, **review**.
- A standing contract other skills follow: *read the relevant brain files first; write durable
  outcomes (decisions, new facts, stakeholder asks) back.*

## Required Inputs

Ask for these only if they aren't already on disk or in the request:

- **Which operation** — `init`, `ingest`, `recall`, or `review` (default: infer from the ask).
- For **ingest**: the artifact (a pasted note, a file path, a transcript) and what it's about.
- For **recall**: the topic or question to answer from memory.
- The **brain location** — default `./brain/` at the project root.

## The Brain Schema

```
brain/
  context.md      # who/what: product, ICP, metrics definitions, voice (supersedes pm-context.md)
  knowledge/      # durable facts — strategy.md, market.md, users.md, org.md
  decisions/      # one file per decision: what, why, alternatives rejected, reopen-when
  hypotheses/     # assumptions: statement, evidence, status (open/validated/invalidated)
  stakeholders/   # one file per person: asks, concerns, comms history
  entities/       # typed objects: features, accounts, experiments — the artifact graph
  source/         # immutable originals (audit trail) — never edited after capture
```

It is Obsidian-vault compatible: open `brain/` as a vault and the links become a graph.

## Provenance Tags (the trust mechanism)

Every fact carries a tag in square brackets so its strength is explicit. Skills must keep the
tag when they reuse a fact, and **downgrade confidence for weak tags**.

| Tag | Means | Strength |
|---|---|---|
| `[data]` | from analytics / a metric / a measured result | strong |
| `[interview]` | from a documented user or customer interview | strong |
| `[external]` | from third-party / market research | medium |
| `[verbal]` | said in a meeting, not independently documented | weak |
| `[hunch]` | informed intuition, no evidence yet | weakest |

Example: `Mobile drives 65% of DAU [data]. Enterprise wants SSO before renewing [verbal].`

## Operations

**init** — Create the folder schema. Migrate an existing `pm-context.md` into `context.md`.
Offer to ingest any artifacts the user already has (Notion export, Jira CSV, notes).

**ingest `<thing>`** — Store the original verbatim in `source/`, then synthesise it into the
right durable file(s) (`knowledge/`, `decisions/`, `hypotheses/`, `stakeholders/`), tagging each
extracted claim with its provenance. Never discard the source.

**recall `<query>`** — Answer from memory. Use the helper script to find matching facts across
the brain, then synthesise an answer that **cites each fact's file and tag**. If memory is thin,
say so rather than inventing.

**record** — The write-back half of the loop (Phase 1). After a skill produces an artifact (or on
demand), extract the **durable outcomes** worth remembering — decisions made, new facts learned,
assumptions surfaced, stakeholder asks — and propose them as a numbered list, each with its
**target section** and **provenance tag**. This is the action surface, so it is **approval-gated
and dry-run by default**:

1. **Propose** — show the records you'd write (section · tag · text). Preview with
   `brain_write.py …` (no `--commit`), which prints exactly what would be appended.
2. **Approve** — the user confirms, edits, or drops items. Never write without a yes.
3. **Append** — write the approved records with `--commit`. Append-only: decisions become a new
   numbered file; everything else appends to its named file. Nothing is overwritten.

Downgrade weak evidence honestly — a conclusion from one call is `[interview]`, a gut call is
`[hunch]`; don't launder it into `[data]`.

**review** — Weekly sweep. Flag: stale hypotheses (open too long with no new evidence),
decisions whose `reopen-when` condition now holds, contradictions between files, and facts that
are only `[hunch]`/`[verbal]` but are being treated as settled. Draft the updates; don't apply
silently.

## Programmatic Helper

`scripts/brain_query.py` (stdlib only) does deterministic recall — it greps the brain for a
query and returns matches with their file and detected provenance tag, so retrieval is
transparent (no embeddings, no guessing).

```bash
# Find what the brain knows about "activation", newest-first, as text
python3 scripts/brain_query.py ./brain "activation"

# JSON for chaining into another step
python3 scripts/brain_query.py ./brain "enterprise SSO" --json
```

Use its output as the grounded evidence set, then synthesise the answer on top — never answer a
recall from outside the brain without saying so.

`scripts/brain_write.py` is the write-back counterpart — it **appends** a provenance-tagged record
(append-only, never overwrites) and is **dry-run by default** so you can preview before committing:

```bash
# Preview what would be written (changes nothing):
python3 scripts/brain_write.py ./brain decisions "Prioritise mobile" --tag data --body "68% of churn is mobile" --source "Q3 analytics"

# Write it after approval:
python3 scripts/brain_write.py ./brain decisions "Prioritise mobile" --tag data --body "…" --source "Q3 analytics" --commit
```

## The contract for other skills

A brain-aware skill adds a short **"Reads from / Writes to the Brain"** section:

- **Reads:** before producing, pull the relevant files (e.g. `prd-template` reads `context.md`,
  `knowledge/strategy.md`, and any related `hypotheses/` + `entities/`).
- **Writes:** after producing, append durable outcomes (e.g. `meeting-notes` writes each
  decision to `decisions/`, new asks to the relevant `stakeholders/` file), each provenance-tagged.

## Output Format

For **ingest**, confirm what was captured:

### Ingested: [artifact]
- **Source saved:** `source/[file]`
- **Knowledge updated:** `knowledge/[file]` — [facts added, each tagged]
- **Decisions logged:** `decisions/[id]` — [if any]
- **Hypotheses touched:** [statement → status]
- **Open follow-ups:** [anything needing a human]

For **recall**, answer then show your grounding:

### Recall: [query]
[Synthesised answer.]

**Grounded in:**
- `decisions/0003-...md` — "..." `[data]`
- `stakeholders/sarah.md` — "..." `[verbal]`

## Quality Checks

- [ ] Every extracted claim carries a provenance tag
- [ ] The verbatim original is saved in `source/` before synthesis
- [ ] Recall answers cite the file + tag for each fact, and flag thin memory instead of inventing
- [ ] Decisions record the rejected alternatives and a `reopen-when` condition
- [ ] `[hunch]`/`[verbal]` facts are never presented with the confidence of `[data]`/`[interview]`

## Anti-Patterns

- [ ] Do not paraphrase a source into the durable layer without keeping the original in `source/` — the audit trail is the point
- [ ] Do not drop provenance tags when reusing a fact — an untagged claim is an unfalsifiable one
- [ ] Do not answer a recall from general knowledge and present it as something the brain "knows" — say when memory is empty
- [ ] Do not overwrite a decision when it changes — append a new dated entry so the history survives
- [ ] Do not build a vector database or hide memory behind embeddings — the brain stays plain, grep-able markdown a human can read and correct