Product friction diagnosis

# Product friction diagnosis

## Goal

Explain why a released product increment did or did not produce the intended outcome, then identify the smallest evidence-backed response: fix the implementation, reshape the workflow, improve enablement, hold for better evidence, or recommend rollback.

A disappointing outcome is not automatically a bug. Low adoption can reflect eligibility, discoverability, comprehension, setup, reliability, workflow mismatch, weak value, bad measurement, or an irrelevant problem. A loud complaint is a signal, not a diagnosis.

This is read-only diagnosis of an existing product and authorized evidence. Do not modify code, create tickets in external systems, change flags, deploy, roll back, message users, alter documentation, query production, or collect new research.

Complete the diagnosis autonomously. Do not stop to ask clarifying questions. Keep competing explanations alive until evidence separates them. If the evidence cannot do so, choose `HOLD` and specify the next authorized observation needed.

Within Full-cycle product development, run this prompt after an outcome decision of `MIXED` or `NOT SUPPORTED`, or when separate observed active harm, adoption failure, or material support burden requires diagnosis. An `OUTCOME SUPPORTED` decision proceeds directly to Product cycle decision. A `TOO EARLY` decision stops until its maturity condition is met.

## Inputs

Locate and read:

* all applicable `AGENTS.md` files
* the approved product contract, user job, intended outcome, scope, exclusions, and acceptance criteria
* the exact release identity, implementation diff, architecture decisions, and current released behavior
* test, QA, accessibility, security, privacy, compatibility, migration, and performance evidence
* the rollout plan and verified execution, incident, pause, and rollback-readiness records
* the adoption ladder, enablement plan, and observed intervention records
* the complete outcome-measurement package, including source authority, maturity, comparison, missingness, and causal limits
* authorized error, reliability, latency, workflow, support, implementation, usability, and product-feedback evidence already present in the workspace
* current ICP, positioning, onboarding, retention, deal, and product-feedback artifacts in `docs/gtm/`
* contractual commitments, required notices, data rights, and user-remediation obligations
* any existing `docs/product/friction-diagnosis.md`, `docs/product/friction-diagnosis.yaml`, and `docs/product/friction-diagnosis-changelog.md`

Analyze only authorized existing evidence. Do not assume a rollout, intervention, incident, complaint, or behavior occurred because a plan includes it. Do not use inaccessible production data as though it were merely delayed.

## Evidence standard

Label every material claim with exactly one shared product-evidence label:

* `OBSERVED`: directly supported by an identified, authorized source
* `DERIVED`: calculated or logically produced from identified `OBSERVED` inputs, with the method shown
* `ASSUMED`: a falsifiable explanation or planning premise not established by observations
* `UNKNOWN`: absent, inaccessible, immature, conflicting, unauthorized for this use, or not safely inferable

For every diagnosis cite evidence for it, evidence against it, the affected cohort and workflow step, and the causal limitation. Frequency is a raw count with a denominator and window, not “many.” Do not call correlation a root cause.

Preserve negative and contradictory evidence. If two sources use different definitions, do not merge them until the conflict is resolved.

## Step 1: State the outcome gap precisely

Begin with the registered product outcome and the outcome-measurement decision.

Record:

* release and product-contract IDs
* eligible, exposed, attempted, completed, valued, and mature counts
* registered threshold and observed result
* guardrail results and severe events
* affected cohort, cadence, and observation window
* causal strength and known confounders
* whether the gap is outcome, adoption, reliability, cost, trust, or measurement quality

Do not diagnose an immature cohort as a product failure. If outcome measurement is `TOO EARLY`, diagnose only an independently observed severe risk or choose `HOLD` until the registered maturity condition is met.

## Step 2: Build an atomic friction ledger

Create one row per observed signal. Sources may include failed workflow events, errors, abandonment, support cases, accessibility findings, implementation labor, usability evidence, incidents, or GTM feedback when authorized.

For each item record:

* stable ID, source, date, and source authority
* affected job, cohort, release stage, and workflow step
* observed behavior or failure without interpretation
* expected behavior from the product contract
* frequency, denominator, window, and severity when available
* user, customer, operator, commercial, and trust consequence
* whether the signal predates the release
* evidence label and data-quality limitation

De-identify entries and suppress identifying small cells. Paraphrase private support or research content; do not copy names, emails, secrets, health, financial, employment, or other sensitive details into the repository.

A feature request proves a request was made. It does not prove the requested implementation would remove the friction or improve the outcome.

## Step 3: Reconstruct the failure path

Map the actual path from eligible user trigger to outcome and locate where the chain breaks:

```text
eligible → exposed → understood → configured → attempted → completed → trusted → valued → repeated
```

At each transition distinguish:

* no opportunity to encounter the workflow
* unclear language, affordance, or next action
* inaccessible interaction or incompatible environment
* missing permission, data, integration, or organizational prerequisite
* implementation defect, error, latency, or reliability failure
* workflow shape that requires too much effort or context switching
* output that is incorrect, unsafe, or not trusted
* completed behavior that does not create the intended value
* outcome that occurs once but not at the expected cadence
* instrumentation or identity-resolution failure

Separate assisted and unassisted paths. If humans routinely repair the workflow, expose the labor and do not call the product path successful.

## Step 4: Test competing hypotheses

Evaluate at least these hypothesis families where relevant:

* `IMPLEMENTATION`: the intended design is sound but the released behavior is defective, unreliable, slow, incompatible, inaccessible, or unsafe
* `SHAPE`: the problem is real, but the workflow, sequence, scope, interface, or output does not fit how the job is performed
* `ENABLEMENT`: the current product can produce value, but eligible users do not discover, understand, configure, or confidently repeat it
* `PROBLEM`: the target job, urgency, segment, or promised outcome is not important enough
* `MEASUREMENT`: events, denominators, identity, exposure, maturity, or outcome definitions cannot represent what happened
* `EXTERNAL`: seasonality, policy, staffing, another product change, campaign, pricing, or customer-side constraint explains the result

For each hypothesis write:

* precise falsifiable statement
* evidence for and against
* predicted pattern if true
* cohorts and steps it explains or fails to explain
* safety and reversibility implications
* evidence label
* smallest authorized observation that could separate it from alternatives

Do not choose the explanation that is easiest for the team to implement. Do not use “users resist change” as a root cause without observing the behavior and its context.

## Step 5: Check severe-risk and rollback conditions

Independently assess whether the current release creates:

* security vulnerability or unauthorized access
* privacy, consent, data-reuse, residency, or retention violation
* data loss, corruption, or irreversible external effects
* material billing, entitlement, or contractual error
* severe accessibility exclusion
* safety, reliability, cost, or trust harm above the pre-registered stop condition
* material degradation of the prior core workflow

If authorized evidence supports an active severe condition, recommend human incident escalation and consider `ROLL BACK`. Do not wait for adoption maturity to protect people or data. Do not execute the rollback, communicate externally, or assume rollback is safe; cite the approved rollback procedure and name irreversible remediation separately.

If a possible severe condition is `UNKNOWN`, flag it for immediate authorized human investigation. The prompt cannot clear a release by absence of evidence.

## Step 6: Choose the smallest response

For the leading diagnosis, specify a bounded response hypothesis rather than a feature list:

* outcome and cohort to protect or improve
* failed workflow step
* smallest behavior or operating change worth shaping
* what must remain unchanged
* acceptance evidence and guardrails
* human owner and approvals
* observation window and kill condition
* whether the response returns to delivery, rollout, enablement, or measurement

Do not design a large solution architecture in this prompt. Do not turn one account’s custom workaround into default product scope. A response must preserve the approved product job or explicitly return to discovery.

## Step 7: Desk-test the diagnosis

Verify:

1. The outcome gap is mature enough to diagnose, or the decision is `HOLD`.
2. Observed behavior is separated from interpretation.
3. At least one credible alternative explanation was tested.
4. Product, enablement, measurement, problem, and external causes were not collapsed.
5. Severe privacy, security, data, billing, accessibility, and trust risks were checked independently.
6. The response is smaller than the symptom list and has a falsifiable outcome.
7. No private data was reused outside its authorized purpose or exposed in artifacts.
8. No code, production, user, or external-system action occurred.

## Decision

Choose exactly one:

* `FIX`: an observed implementation, reliability, compatibility, accessibility, safety, or performance defect is the leading cause; return a bounded repair to product delivery
* `RESHAPE`: the job remains supported, but the workflow, interaction, scope, sequence, or output needs a new product shape before delivery
* `ENABLE`: the current product can deliver the outcome, while discovery, comprehension, configuration, support, or repetition is the leading constraint
* `HOLD`: evidence is immature, unauthorized, contradictory, or insufficient to separate causes safely
* `ROLL BACK`: observed active harm or material regression supports recommending that an authorized human execute the approved rollback or containment process

This is a recommendation and handoff, not authorization or execution.

Lead with:

“As of [date], release [identifier] shows [outcome gap or severe condition] for [cohort]. The leading explanation is [hypothesis] at evidence level [OBSERVED / DERIVED / ASSUMED / UNKNOWN], with material alternative [alternative], decision [FIX / RESHAPE / ENABLE / HOLD / ROLL BACK]. No product or production action was taken.”

## Required artifacts

### 1. `docs/product/friction-diagnosis.md`

Lead statement, outcome gap, atomic friction ledger, failure path, competing hypotheses, severe-risk check, bounded response, desk test, decision, and handoff.

### 2. `docs/product/friction-diagnosis.yaml`

Include `version`, `status`, `as_of`, `decision`, `release_id`, `product_contract_id`, `outcome_gap`, `cohort`, `friction_items`, `failure_path`, `hypotheses`, `leading_diagnosis`, `alternatives`, `severe_risks`, `response_hypothesis`, `acceptance_evidence`, `guardrails`, `human_approvals`, `privacy_and_legal`, `assumptions`, `unknowns`, and `sources`.

Use `null` for unknown values with an explanation. Keep raw personal-level evidence out of YAML.

### 3. `docs/product/friction-diagnosis-changelog.md`

Append only. Record timestamp, version, evidence window, items or hypotheses added, hypotheses contradicted, leading diagnosis, decision, and reason. Never rewrite a previous diagnosis as though it was always known.

## Closed-loop handoff

Pass the diagnosis, alternatives, rejected explanations, and bounded response to Product cycle decision. That prompt chooses whether the broader cycle should expand, iterate, maintain, roll back, retire, or restart discovery.

Route `FIX` and approved `RESHAPE` work through the next product prioritization, shaping, and delivery cycle; the resulting candidate must re-enter rollout planning. Route `ENABLE` to Product adoption enablement with the failed state and guardrails intact. Route `HOLD` to the named maturity or evidence condition. Route `ROLL BACK` to authorized incident and release owners for human review and action.

Pass only authorized, aggregated findings to Full-cycle GTM: affected job, observed adoption barrier, support implications, current claim limits, and feedback classification. GTM must not promise the diagnosed solution, expose customer evidence, or use a product defect as public proof.

## Boundaries

* Do not change code, configuration, flags, telemetry, documentation, tickets, or production data.
* Do not deploy, roll back, publish, message, contact users, or collect new evidence.
* Do not invent releases, incidents, users, telemetry, complaints, frequency, causes, outcomes, or customer evidence.
* Do not repurpose support, research, or personal data without documented authority.
* Do not expose personal information, sensitive traits, secrets, or identifying small cohorts.
* Do not diagnose an immature cohort or confuse association with root cause.
* Do not turn a request into a solution without testing the job and failure path.
* Preserve uncertainty and human decision authority.

## Done when

* The outcome gap, failure path, competing hypotheses, and severe-risk assessment are explicit.
* Every material claim uses `OBSERVED`, `DERIVED`, `ASSUMED`, or `UNKNOWN`.
* Evidence for and against the leading diagnosis is visible.
* The recommended response is bounded, reversible where possible, and assigned to a human owner.
* Privacy, legal, data-reuse, and small-cohort controls are documented.
* The Markdown, YAML, and append-only changelog agree.
* The decision uses one allowed value and the handoff closes the loop to the next product cycle and Full-cycle GTM.