# Pathrule Pattern: Dunning and Churn Recovery (1.0.0)
# ::pathrule:package:dunning-churn-recovery

### [RULE] Drive dunning from idempotent billing events  (path: /src/webhooks)
<!-- scope: folder | priority: high | strict -->

Provider events advance a stored recovery state machine and duplicate or out-of-order delivery cannot repeat effects. A webhook handler that sends mail, changes access, and schedules work directly will duplicate side effects and regress state when events retry or arrive late. Enforce this boundary in /src/webhooks so invalid work stops before it reaches another subsystem or creates an externally visible side effect.

- Persist the provider event identifier and normalized invoice or subscription version before dispatching effects.
- Compare the incoming provider state with the local transition table and ignore stale transitions while retaining them for audit.
- Use stable idempotency keys for notices, retry jobs, access changes, and provider mutations.
- Re-fetch authoritative billing state when event ordering is ambiguous instead of guessing from delivery time.

Verification: Replay, reorder, and concurrently deliver failure, update, paid, and canceled events; confirm each state and side effect occurs exactly once.

---

### [MEMORY] Failure reason selects the recovery path  (path: /src/billing/dunning)

A temporary issuer decline, expired credential, missing method, required customer action, and terminal account state do not benefit from the same retry cadence. Normalize provider details into a small internal failure taxonomy without exposing sensitive payment data.

Use automatic retries only for categories the provider and payment method can recover without new customer input. Send customers to a short-lived authenticated update or action flow when intervention is required. Stop futile retries and switch messaging when the provider marks a hard decline or no usable method exists. Keep the decision explicit at /src/billing/dunning; moving it into an incidental caller makes behavior depend on which route happened to execute first.

See /src/jobs for retry scheduling and /src/webhooks for authoritative state transitions. That related boundary consumes this decision and carries the evidence that proves it still holds.

---

### [SKILL] design-dunning-journey  (path: /)

---
name: design-dunning-journey
description: Design a failed-payment journey with retry, communication, access, and recovery states for each failure class.
---

# Design Dunning Journey

Run this procedure whenever the governed surface changes or its operational evidence becomes stale.

1. Map provider invoice and subscription states into the product's recovery states, including temporary, action-required, hard-failure, recovered, and terminal outcomes.
2. Choose retry ownership and cadence per payment method and failure class; never run an application scheduler on top of provider-managed retries unintentionally.
3. Define notice timing, channel, authenticated recovery action, grace behavior, access changes, and support escalation for each transition.
4. Test event reordering, duplicate delivery, customer update during retry, late payment, cancellation, and payment after access restriction.

Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.

---

### [SKILL] audit-dunning-performance  (path: /src/billing/dunning)

---
name: audit-dunning-performance
description: Audit recovery performance by failure reason, cohort, retry path, message, and customer outcome.
---

# Audit Dunning Performance

Run this procedure whenever the governed surface changes or its operational evidence becomes stale.

1. Select a closed cohort and reconcile failed invoices, attempts, customer actions, payments, cancellations, credits, and access outcomes against provider records.
2. Segment temporary versus hard failures, payment method, tenure, plan, geography where permitted, and the exact recovery journey received.
3. Measure recovered revenue and customers without counting late duplicates, write-offs, or payments unrelated to the failed invoice.
4. Identify harmful or futile steps, document an experiment with guardrails, and monitor complaints, opt-outs, and support load alongside recovery.

Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.