The Returns-Resolution Packet, Worked

Why now

Returns are the second-largest source of support contact volume, and returns volume rises about 40% from mid-November. No support headcount is approved for the season. Doing nothing means the contact queue grows with the returns queue and agents spend the season on status chasing instead of exceptions.

Problem

For signed-in domestic customers returning an unopened item within 30 days, a request waits a median of 72 hours for an agent decision, and 41% of those requests produce at least one support contact. Baseline source: returns queue export joined to the contact log, 1 June – 31 July, n = 4,812 requests; query owned by Priya, re-runnable.

Outcome

Move median time from request submitted to decision communicated for the eligible domestic cohort from 72 hours to under 4 hours, and the support-contact rate for that cohort from 41% to 31% or lower (a 25% relative reduction), with the pilot open to real customers by 30 September.

Guardrails

Fraud loss per 1,000 eligible returns at or below the 2.4 baseline (owner: Risk). Manual review queue at or below 50 requests/day (owner: Nils, support operations). WCAG 2.2 AA on the four critical flows (owner: Marco, design). Carrier cost per resolved return at or below the $3.42 baseline (owner: Priya). Personal data retained no longer than 30 days (owner: Ola, privacy).

First boundary

Signed-in domestic customer, unopened item, delivered 30 days ago or less, refund to the original payment method. Later expansion to opened/damaged items and to guest orders must remain possible without changing the eligibility contract — see contract review.

Non-goals

Exchanges. International shipping. Guest checkout. Redesigning warehouse intake. Replacing the agent tool. Each is here because someone plausibly assumed it was in scope.

Constraints

The order platform stays authoritative for order truth. The carrier contract is fixed for the pilot term. No payment card data enters the returns module. Personal data is retained for 30 days. The team is seven people and does not grow. The 30 September pilot date is fixed by the season, not by preference.

Assumptions

Seven named beliefs with impact, evidence strength, test and owner — see the assumption map. Two have since been falsified and one remains inconclusive.

Risks

R1 automatic decisions raise fraud loss (high × medium; early signal: fraud rate in the exposed cohort versus control; mitigation: hold rule plus staged exposure; owner: Risk; review weekly). R2 the referred cohort reads a referral as a refusal and contacts support anyway, harming the very measure (high × medium; signal: contact rate within the referred segment; owner: Marco). R3 the carrier cannot meet the label latency budget (medium × high before the spike, resolved — see ADR 0003). R4 guest orders are 29% of demand and stay outside the pilot, so the headline outcome overstates the business effect (medium × high; owner: Priya; decision date 15 November).

Decision rights

Outcome, scope and cohort: Priya. Experience: Marco. Architecture and technical risk: Dana. Rollout advance and reversal: Dana with Nils, stop authority to any on-call engineer. Full table in the team charter.

Next evidence

Comprehension retest at n = 12 (Marco, 15 September). Fraud rate in the 1% cohort versus matched control after 120 exposed requests (Risk, from 29 September). Guest-order opportunity sizing (Priya, by 15 November).

Rule

An unopened item bought by the signed-in customer and delivered 30 days ago or less is accepted automatically. The window is evaluated on the delivery date in the store's timezone, not on the submission timestamp.

Happy

Given an unopened domestic item delivered 12 days ago and a signed-in purchaser, when they submit a return, then the decision is accepted, exactly one label intent is recorded in the same transaction, and the decision is visible to the customer within 800 ms at p95.

Boundary

Given the same item delivered 31 days ago, then the decision is refused with reason code outside_return_window, the refusal states the delivery date it used, and an appeal path is offered.

Boundary

Given delivery exactly 30 days ago at 23:50 store time and submission at 00:10 store time the following day, then the decision is accepted: 30 days is inclusive and measured in whole days from the delivery date. This example exists because the first implementation used UTC timestamps and refused it.

Guardrail

A keyboard-only customer can complete the happy path; every refusal reason is announced by a screen reader and never conveyed by colour alone.

Telemetry

eligibility_decision_total{outcome, reason_code}, and eligibility_decision_seconds as a histogram. A shift in the reason-code mix is the earliest signal that a policy change did something unintended.

Traces to

Outcome (latency half) · driver D2 · assumption A1.

Rule

A customer with three or more returns marked “not received” in the trailing 90 days is referred, never auto-refused, and no label is created until an agent releases the hold. The customer is never shown the fraud reason.

Happy (from the guardrail's point of view)

Given a customer with three such returns in the last 90 days, when they submit an eligible return, then the decision is referred with internal reason fraud_review, the customer sees “a specialist is checking this — you'll hear within 4 hours”, and no label intent is recorded.

Boundary

Given a customer whose third such return was 91 days ago, then no hold is applied and the normal decision runs.

Failure

Given a held return that is still unanswered after 4 hours, then an alert routes to Nils and the ageing hold appears on the operations dashboard. An unanswered hold is a customer waiting, not a queue statistic.

Guardrail

No customer-visible text, email, or API response distinguishes a fraud hold from any other referral. A negative test asserts that fraud_review never appears in any customer-facing payload.

Telemetry

fraud_hold_rate by cohort and by exposure stage; fraud_hold_age_seconds max. Both feed the rollout guardrail, not just a dashboard.

Traces to

Guardrail “fraud loss ≤ 2.4/1,000” · risk R1 · assumption A6 · rollout stop threshold.

Rule

The customer's return is accepted independently of the carrier. Exactly one carrier label exists per accepted return, however many times we retry.

Failure

Given an accepted return whose label intent is recorded, when the carrier call times out after 5 seconds, then the return stays in awaiting_parcel with label_state = pending, the customer sees “your label is being prepared”, and the worker retries with the same client reference.

Failure

Given that retry, when the carrier had in fact created a label on the first attempt, then the original label is returned and no second label is created. Asserted directly: exactly one carrier_label_id per return, checked as a database constraint and as a daily reconciliation against the carrier's own list.

Failure

Given the carrier is unavailable for 30 minutes at peak, then eligible requests are still accepted, and 99% of pending labels are created within 15 minutes of recovery.

Operability

Given label failures exceed 2% for five minutes, then an alert fires with the carrier's error breakdown, and on-call can disable label attempts within ten minutes. Disabling label attempts must not refuse new returns, and the worker must stop retrying the existing backlog — see the reversal rehearsal, which is where we discovered it did not.

Telemetry

carrier_call_seconds, carrier_error_total{code}, label_pending_age_seconds max, duplicate_label_total (must stay at zero).

Traces to

Drivers D1 and D5 · assumption A3 · ADR 0003 · rollout stop threshold.

Rule

The returns module requests refunds; it never asserts settlement, and it never reverses one. A settled refund can only be offset by a new fact created by Payments.

Failure

Given a refund authorised on a receipt event, when the warehouse later reverses that receipt (wrong item scanned), then the return moves to settlement_disputed, no compensating charge is issued automatically, and a case is opened with Payments carrying the original correlation id. Rationale: reversing money is Payments' decision and often a human's; a returns module that could do it silently would be a fraud vector.

Boundary

Given an accepted return whose parcel has not arrived within 21 days, then the return moves to expired with reason parcel_not_received, the customer is notified exactly once, and no refund is requested.

Failure

Given a refund request that Payments rejects because the captured amount is lower than the requested amount, then the return moves to settlement_disputed and is queued for an agent. The returns module does not attempt a smaller refund on its own: the invariant “refund ≤ captured” belongs to Payments and is enforced there.

Telemetry

settlement_disputed_total{cause}; the age of any accepted return with no terminal state (feeds the I4 reconciliation sweep).

Traces to

Invariants I3 and I4 · the “settlement” vocabulary entry · driver D3 (nothing crosses a trust boundary silently).

Rule

One intent creates at most one return. A repeated intent is the same return; a genuinely new intent for an already-open line is refused with a link, not silently merged.

Failure

Given a customer double-taps submit, so the same Idempotency-Key arrives twice, when the second request is processed, then the same return id, decision and label are returned with 200, and exactly one return exists.

Boundary

Given the same Idempotency-Key but a different request body, then the response is 409 with code idempotency_key_reuse. Silently returning the first result would hide a client bug; silently processing the second would create two returns.

Boundary

Given a new intent key for an order line that already has an open return, then the request is refused with reason return_already_open and a link to the existing return.

Guardrail

Given a customer edits the order id in the URL to another customer's order, then the response is 404, an authorization event is logged with the actor and the attempted id, and no field of the other order appears in any response, log line or error message.

Telemetry

idempotent_replay_total, idempotency_conflict_total, authz_denied_total{reason}.

Traces to

Driver D3 · invariant I1 · the idempotency section of the contract review.

Command

assess(request: ReturnRequest) -> EligibilityDecision

Promise on success

Exactly one decision, complete: outcome (accepted / refused / referred), a reason code and human text whenever the outcome is not accepted, the policy_version used, the timestamp, and the deciding actor. Deterministic given the same request and policy version.

Forbidden

No network or database I/O. No vendor types in the signature or the result. No knowledge of how the decision will be displayed or stored. Enforced by the import rule in 7.3.

Failure

There is no failure mode. Missing input is a programming error and raises; there is nothing to retry, because there is nothing to fail. This is the payoff of keeping I/O out.

Events emitted after commit

ReturnAccepted, ReturnRefused, ReturnReferred — each carrying return id, decision, reason code, policy version, correlation id. Published from the outbox, never inside the transaction.

Proof

The 200 sampled agent decisions from A1 run as a table-driven test suite against assess. A policy change that alters an existing sampled outcome fails the build and must be signed off by Anya.

Decision blocked

Whether label creation may sit inside the request that accepts a return.

Question (falsifiable)

At the pilot's request rate, is the carrier's label-creation p95 under 500 ms, and does a retry after a timeout create a second label?

Timebox

Four hours, one engineer (Dana). Publish numbers whatever they are.

Method

Carrier sandbox: 200 sequential creates recording p50/p95/p99; then 20 creates with the client socket timeout forced to 1 s, each retried once — ten with a client reference, ten without.

Result

p50 640 ms, p95 1.9 s, p99 11.4 s. With a client reference: 0 duplicates in 10. Without: 2 duplicates in 10. Answer to the question: no, and yes.

Disposal

Harness deleted. The one thing kept was the assertion “exactly one carrier label per intent”, which became a production reconciliation check rather than a script on a laptop.

Caveat recorded

The sandbox is not production. The p99 figure is directionally trusted, not contractually. This is why D1's evidence mechanism is a recurring drill, not a one-off number.

Status

Accepted · 12 September · decider: Dana (tech lead) · advice from Priya, Marco, Nils, Lea, Sam

Supersedes

ADR 0002 (“Create the carrier label inside the request”, accepted 1 September). ADR 0002 remains in the log, unedited, marked superseded — it is a historical fact about what the team believed on 1 September.

Superseded by

None. See “Revisit when”.

Context

The pilot must accept eligible returns and communicate a decision within 4 hours median, at up to 40 rps at seasonal peak, with a p95 decision path of 800 ms. The carrier is a fixed contractual dependency. The A3 spike measured the carrier at p50 640 ms, p95 1.9 s, p99 11.4 s, and observed duplicate labels on 2 of 10 timeout-retries made without a client reference. The team is seven people with one deployable and a fixed 30 September date.

Forces

D1 availability (accept during a 30-minute carrier outage; 99% of labels within 15 minutes of recovery). D2 performance (800 ms p95 decision, excluding label). D5 operability (disable label attempts within 10 minutes). Guardrail: manual review queue ≤ 50/day. Assumption A2 (customer comprehension of a two-step flow) is not yet settled and is the main cost of this decision. Operational simplicity for a seven-person team.

Options considered

A. Synchronous carrier call — rejected: measured p99 exceeds the decision budget by 14×, and a carrier outage would refuse eligible requests, failing D1 outright. C. Agent buys the label — rejected as the everyday mechanism: it adds ~40 manual actions/day at pilot volume and breaks the 50/day guardrail at roughly 30% exposure; retained as the outage fallback. B. Persist intent + worker — chosen.

Decision

The API commits the return, the eligibility decision and a label_intent row in a single transaction, and returns a decision with label_state = pending. A separate worker process in the same deployable drains intents and calls the carrier, passing the intent id as the carrier's client reference so retries are idempotent. A unique constraint on label_intent.return_id makes a second label unstorable. Label attempts sit behind a flag that on-call can disable in under ten minutes, checked inside the worker loop as well as at request time.

Consequences · benefits

Request acceptance survives a carrier outage. The 800 ms budget is achievable and measurable, because the vendor is no longer inside it. Carrier health becomes separately observable and separately disableable, which is what makes D5 reachable.

Consequences · accepted costs

(1) The customer sees two steps — “accepted”, then “label ready” — and A2 says two of five test participants misread the first as a refusal. We accept this cost and pay down the risk with wording work and a retest, not by reversing the decision. (2) A worker process, a backlog, and an ageing metric now exist and must be watched; that is new on-call surface for a team of seven. (3) A pending state is now visible in the API, so removing it later is a contract change, not a refactor. (4) The label flag is temporary machinery with a deletion owner and date (see closeout).

Consequences · follow-up work

Reversal rehearsal of the disable path before each exposure stage (Nils). Daily reconciliation against the carrier's label list (Lea). A2 retest at n = 12 (Marco, 15 September).

Operational ownership

Worker health, backlog age and the disable flag belong to on-call from the staff-accounts stage onward; transferred to the steady-state owner at closeout.

Dissent

Recorded, from Sam (engineer). “For a pilot of about 50 requests a day we are buying a queue, a backlog metric, a flag and an on-call surface to solve a problem that option C solves with a runbook. We should ship C and revisit at 10% exposure.” The concern is legitimate and was not resolved by argument. What would prove it right: if, by the 10% stage, the label worker has produced no incident that the manual path would also have produced, and the manual queue has stayed under 20/day, then the worker was premature and we should say so in the closeout. Outcome at closeout: referrals alone reached 41/day at peak, so option C's extra label purchases would have breached the 50/day guardrail — the dissent was recorded, tested, and not upheld. Sam's second point, that the flag is carrying cost, was upheld: it is on the removal list with a date.

Revisit when

Any one of: sustained volume exceeds the worker's measured drain rate of 12 labels/minute; the carrier publishes a durable asynchronous label API; the label queue misses its 15-minute recovery target twice in one quarter; or the A2 retest shows the two-step flow costs more contacts than the outage risk it avoids.

The sentence

From the main branch, deploy one internal-user return request through the production pipeline; persist its intent, cross the carrier port with a fake adapter, render pending label on the real status page, and find the complete request by correlation id in the real logging stack.

Real

The build, the pipeline, the deployable, the database and its migration, the module boundaries and their import check, the outbox, the worker process, the correlation id, the telemetry pipeline, the status page.

Fake or hard-coded — stated, not implied

Eligibility always returns accepted (no policy at all). The carrier adapter returns a fixed label id after 100 ms. Order lookup returns one fixture order. No notifications. No authorization beyond “is signed in”. Warehouse receipt is a button in an internal page.

What it proved in week 2

Three things nobody had predicted: the storefront's session cookie was not available to the worker process (so correlation ids broke across the boundary), the migration needed a two-step deploy to avoid locking a hot table, and the platform's log retention was 3 days, not 30 — which the privacy review had assumed. All three were cheap in week 2 and would have been expensive in week 9.

Fixed

The 30 September pilot-open date (seasonal). The team of seven. The outcome and its guardrails.

Movable

Scope. With a fixed date and a fixed team, scope is the only control surface, and saying so in week 1 is what makes the week-6 trade a decision rather than a crisis.

Forecast

Pilot open to 1% between 26 September and 3 October, ~70% confidence, based on four completed slices at a measured 4–7 days each. Not “30 September”: a single date at this range is a claim the evidence does not support.

Smallest scope trade that preserves the outcome

Drop the in-product appeal flow to slice 2 and keep “refused, with a reason and a link to contact an agent”. This costs a worse experience for the 11% of requests that are refused and saves about 5 days. It does not touch either outcome measure, which is the test a scope trade has to pass.

What would not be traded

The reversal rehearsal, the authorization negative tests, and the matched control cohort. Trading those buys days by removing the ability to know whether the pilot worked.

Next reforecast

At the “Team uses it” milestone, or immediately if any dependency's escalation trigger fires — not only when the date becomes impossible.

Purpose

Move eligible domestic return resolution from 72 hours to under 4 hours and cut support contacts by a quarter, for signed-in customers with unopened items, with the pilot open by 30 September.

People and accountabilities

Priya — product (outcome, scope, cohort). Marco — product design (experience, research, accessibility). Dana — tech lead (technical integrity, architecture, risk). Sam, Lea, Tomas, Ije — engineers (implementation within agreed boundaries; Lea owns the worker, Sam owns eligibility, Tomas owns the API and adapters, Ije owns telemetry and the pipeline). Consulted, not embedded: Anya (policy), Nils (support operations), Ola (privacy and security), Ravi (payments), Asha (platform).

Missing expertise, named

Nobody on the team has run a fraud guardrail before. Consultation path: Risk, fortnightly, and Risk holds the stop authority on the fraud guardrail rather than the team.

Flow

WIP limit: two slices in progress, full stop. Swarm rule: if a slice has not moved in two days, everyone not on the other slice joins it. Review: every change reviewed, but the tech lead is not a required reviewer — guardrails are published as the import fitness function and the contract tests, so review is distributed rather than queued behind one person.

Sources of truth — one place each

Why: this frame. Scope: the story map. Current flow: the delivery board. Decisions: the ADR log. Uncertainty: the risk and dependency map. Evidence: the initiative dashboard. Nothing is duplicated into slides; a status that exists in two places will disagree within a fortnight.

Cadence

Daily 10 min (flow and blockers, not status). Twice weekly 30 min (shape the next slice with examples, product + design + engineering together). Weekly 30 min (initiative review — see section 13). Weekly 45 min (demo integrated behaviour). As needed, timeboxed (one architecture decision with the required advisers). Fortnightly 45 min (team health; one owned experiment). Any of these is cancelled for the week if it has no decision to make.

Escalation triggers — objective, not emotional

(1) A dependency passes its needed-by date without readiness evidence. (2) A driver cannot be met inside the agreed scope. (3) A decision crosses another team's ownership. (4) Forecast confidence falls below 60%. Each escalation states the decision or resource requested, the options with consequences, and the date by which an answer is needed.

Health

No planned weekend work; the fixed date is protected by scope, not by hours. Every module has a second person who has changed it. One team experiment per fortnight; this initiative's was “no ticket may be assigned to the person who wrote it”, kept after two cycles.

Baselines used by the measures above: eligible domestic demand 130 requests/day, rising to about 160/day from mid-November (source: order platform returns extract, rolling 12 months). Decision mix from the A1 sample and the first exposed week: 63% accepted, 26% referred, 11% refused.

Data and side effects at each reversal: disabling exposure stops new returns entering the new path; returns already in flight continue, because abandoning them would strand customers mid-journey. Labels already bought are not voided. Refunds already requested are not recalled — see E4. Reversal is therefore “stop the intake”, never “undo the week”, and the contract says so rather than leaving the team to discover it.

Scenario

The carrier starts returning timeouts at 09:40 on a weekday. Label errors cross 2% within four minutes. The on-call engineer is someone who did not build the worker.

What the team had to demonstrate

Detect (alert fires, names the carrier), diagnose (runbook link resolves the carrier's error code), limit (disable label attempts), recover (re-enable, backlog drains), explain (a support message the agents can send).

Finding, first rehearsal (18 September)

The disable flag did not do what everyone believed. It was checked when a request created an intent, so it correctly stopped new label attempts — but the worker read the flag once at start-up and kept retrying the 63 intents already in its backlog against a failing carrier. The rehearsal's stopwatch said “disabled in 3 minutes”; the carrier's dashboard said we were still calling it eleven minutes later.

Fix

The flag is read inside the worker loop, once per intent. A test asserts that the worker stops within one iteration of the flag flipping. Added to the operability driver's evidence line, and to E3 as an explicit expectation.

Finding, second rehearsal (22 September)

Disable worked in 90 seconds. The gap was the support message: nobody could say what a customer with a pending label should be told. Written, put in the runbook, and now part of the stage-2 entry condition.

Why it is rehearsed every stage, not once

The disable path is code, and code changes. A rehearsal that happened in September proves nothing about the flag in November.

• ADR 0002 remains superseded, not deleted. A newcomer can still read what the team believed on 1 September and why it stopped being true.
• ADR 0005 (manual receipt) is not superseded, because the decision still stands — the debt entry above records that its removal trigger fired and was not acted on. Superseding it would have hidden the debt.
• Context and container views updated to v4 (worker moved to Kim's ownership; the fake adapter removed from the legend).
• All four fitness functions remain in the build after handover: import rules, log redaction, the “nothing writes refunded” check, and the 200-case policy suite. They are the part of this packet that keeps working when everyone who wrote it has moved on.
• The compatibility policy for the returns API is now published to the two internal consumers that appeared during the pilot. It was written in week 4, before there were any consumers, which is the only time it is cheap to write.

Two improvements owned, not twelve. (1) Every future initiative buys a domain sample before writing an outcome statement — owner Priya, applied to the guest-order initiative in Q1. (2) Every guardrail gets a power check at design time: if the agreed measure cannot detect the change it is meant to catch, it is not a guardrail — owner Risk, due before the Q1 initiative's first exposure.

Decision

Hand over and continue in a new initiative. The returns capability moves to steady-state ownership as of 24 November. Slice 3 (opened and damaged items) and guest orders become a separate Q1 initiative with its own frame, because they need a different fraud model and a different cohort — not because they are “phase two”.

Why not simply continue

The opportunity that remains is a different opportunity. Continuing under this frame would have let the outcome statement drift to cover work it was never evidence for, which is how initiatives become permanent programmes with unfalsifiable goals.

Why not stop

Both measures moved substantially against a held-back control, and every guardrail held. The contact-rate miss is 0.6 points on a measure that moved 9.4 points; it is a miss worth reporting, not a reason to reverse.

What the next lead is told

Read ADR 0003 before touching the label path. The fraud guardrail is under-powered — fix the measure before you widen the cohort. The manual receipt debt has a trigger that has already fired. And the outcome statement covers 71% of demand: quote it with that clause attached or you will mislead someone.

Outcome “median under 4 hours” → assumption A3 “the carrier is fast enough to sit inside the request” → target workflow puts the label after the decision → pilot slice includes a label the customer can actually use → example E3 pins what a timeout means → drivers D1 and D2 give it a number and a failure condition → container view gains a worker process and dynamic view B → state table makes “exactly one label per return” a constraint, not a convention → ADR 0003 chooses the mechanism, records Sam's dissent and its accepted costs → delivery map puts the carrier port in the walking skeleton in week 2 → decision rights say Dana decides it and any on-call engineer may stop it → rollout rehearses the disable path and finds it broken → week-3 review is where the evidence arrived and the decision changed → closeout reports zero duplicate labels in 6,480 returns, hands the worker to Kim, and revisits the dissent.

Now try it on your own packet. Pick your riskiest assumption and walk it forward. The first place the line breaks is either work nobody needed or a risk nobody is carrying.