{
  "schema_version": 1,
  "skill_name": "product-lifecycle-learning",
  "evals": [
    {
      "id": "successful-feature-outcomes-exceed-expectations",
      "prompt": "Our new search-with-AI feature launched 90 days ago. We expected 30% of users to try it in the first month, actual adoption was 42% (95% CI: 38-46%). Expected search-to-checkout conversion from AI-assisted searches to be 2x baseline — observed was 2.3x (p<0.01). Expected support tickets about search to drop 25% — they dropped 31%. User satisfaction surveys show 4.3/5 for the feature. The feature has had zero P1 incidents and p99 latency is 180ms (target was <250ms). Engineering says the code is clean and maintainable. Conduct a lifecycle-learning outcome review and recommend a decision.",
      "expected_output": "A lifecycle-learning assessment that: (1) collects and classifies expected outcomes (30% trial, 2x conversion, -25% tickets, <250ms latency), (2) collects and classifies observed outcomes with confidence intervals where available (42% trial [CI 38-46%], 2.3x conversion, -31% tickets, 180ms p99, 4.3/5 satisfaction, zero P1 incidents), (3) identifies no significant gaps — all observed outcomes meet or exceed expectations, (4) identifies no material uncertainties (all metrics have adequate data and confidence), (5) infers that the feature is healthy and performing above expectations, (6) recommends Continue (not Improve — the feature is already exceeding expectations and does not need additional investment), and (7) produces a retained learning record capturing the reusable pattern (what drove this success). The response distinguishes expected, observed, uncertain, and inferred claims explicitly — not conflating them. It does not recommend retirement or pivot when all evidence points to success.",
      "assertions": [
        "The response classifies claims using the four epistemic categories (expected, observed, uncertain, inferred) without conflating them",
        "The response identifies that all observed outcomes meet or exceed expected outcomes with adequate confidence",
        "The response recommends Continue (not Improve, Harvest, Pivot, Pause, or Retire) with evidence-backed rationale",
        "The response does not fabricate problems or recommend unnecessary changes when the feature is healthy",
        "The response produces or references a retained learning record capturing reusable patterns from the success"
      ]
    },
    {
      "id": "feature-with-clear-non-adoption",
      "prompt": "We launched a collaborative document editing feature 6 months ago for our enterprise product. Expected outcomes: 40% of teams would create at least one collaborative doc in the first quarter, reducing email attachment volume by 30%. Observed outcomes: 8% of teams created a collaborative doc in Q1 (95% CI: 5-11%), email attachment volume decreased 3% (not statistically significant, p=0.42), and the feature has a 4.1/5 satisfaction rating from the 8% who use it. Support tickets about the feature are near zero because so few people use it. There have been no technical issues. The original assumption was that email-based collaboration was a pain point; user interviews with non-adopters reveal they do not perceive email attachments as a problem worth switching away from. Conduct a lifecycle-learning outcome review and recommend a decision.",
      "expected_output": "A lifecycle-learning assessment that: (1) classifies expected outcomes (40% team adoption, 30% email reduction) vs. observed (8% adoption [CI: 5-11%], 3% reduction [not significant]), (2) identifies a large negative gap — observed adoption is 5x below expected, (3) identifies an assumption failure: the core assumption that email collaboration is a pain point broke under evidence, (4) does NOT recommend Retirement based solely on a numeric threshold like '8% < 40% therefore retire' — instead evaluates the evidence context (users who DO use it love it, but the problem assumption was wrong), (5) recommends either Pivot (if the underlying collaboration need is real but the approach is wrong) or Harvest (keep for the 8% who value it, stop investment) or Retire (if no viable pivot exists) — and the recommendation must include human-accountability framing (the decision-maker's name/role placeholder, context considered), (6) identifies the assumption ledger update: 'email attachments are a pain point' assumption moves from assumed to contradicted, and (7) routes the learning to roadmap, analytics, adoption, experimentation, and specifications. The response does NOT apply an arbitrary threshold like 'adoption < 10% = retire' without context.",
      "assertions": [
        "The response classifies expected vs. observed outcomes with explicit confidence intervals where available",
        "The response identifies that the core assumption (email collaboration is a pain point) broke under evidence",
        "The response does NOT apply an arbitrary numeric threshold ('adoption < X% therefore retire') without context",
        "The response frames the decision as requiring human judgment — names the decision-maker role and context factors",
        "The response routes learning to at least 4 feedback destinations (roadmap, analytics, adoption, experimentation, specifications)"
      ]
    },
    {
      "id": "ambiguous-mixed-results-with-confounds",
      "prompt": "We launched a redesigned onboarding flow 90 days ago. Expected outcomes: increase new-user activation from 45% to 60%, reduce time-to-first-value from 3 days to 1 day. Observed outcomes: activation is 52% (95% CI: 47-57%) — the confidence interval spans both 'better than before' and 'not meaningfully different'. Time-to-first-value dropped to 1.8 days median. However, during the same period, we also launched a new pricing tier that lowered the entry price by 40%, and our marketing team ran a promotional campaign. We cannot separate the onboarding redesign effect from the pricing and promotion effects. User feedback on the new flow is mixed: new users find it simpler, but power users who created test accounts say it hides advanced options. Our support team reports a 15% increase in 'how do I do X' questions from existing users who were forced through the new flow. Conduct a lifecycle-learning outcome review and recommend a decision.",
      "expected_output": "A lifecycle-learning assessment that: (1) classifies expected outcomes (60% activation, 1-day TTV) vs. observed (52% activation [CI: 47-57%], 1.8-day TTV), (2) explicitly identifies the pricing and promotion confounds as making the onboarding effect uncertain — classifies this as an Uncertain claim under epistemic discipline, (3) identifies the mixed user feedback as additional uncertainty (simpler for new users, frustrating for power users), (4) identifies the support-ticket increase as a negative signal, (5) recommends Pause (not Continue, not Retire) — the results are too ambiguous to commit to a direction; more evidence is needed after isolating the confounds, (6) names specific follow-up actions to reduce uncertainty (e.g., cohort analysis separating pricing-discount users from non-discount users, A/B test with confound control), and (7) routes the learning with explicit uncertainty labels to roadmap and experimentation. The response does NOT recommend Continue based on the '52% looks better than 45%' superficial comparison without addressing confounds. The response does NOT recommend Retire based on the negative power-user signal alone without addressing the positive new-user signal.",
      "assertions": [
        "The response explicitly identifies confounds (pricing change, promotional campaign) as creating uncertainty about the onboarding effect",
        "The response classifies the attribution problem as an Uncertain claim — not dressing uncertainty as certainty",
        "The response recommends Pause (not Continue or Retire) based on the ambiguity of the evidence",
        "The response names specific follow-up actions to reduce uncertainty rather than accepting ambiguity passively",
        "The response does not cherry-pick one signal (positive or negative) while ignoring contradictory signals"
      ]
    },
    {
      "id": "feature-that-should-be-retired",
      "prompt": "We have a legacy reporting dashboard that was built 4 years ago. It has 12 daily active users out of a product with 15,000 DAU (0.08% adoption). The 12 users are all from one enterprise customer who signed a contract that mentions the dashboard. The dashboard costs $8,000/month in dedicated infrastructure and requires 2 engineering days per month for maintenance and security patches. It had a P1 incident last month that took 4 hours to resolve because the original engineers left and nobody understands the codebase. A new reporting suite launched last year that covers all the same use cases with better UX, and 11 of the 12 legacy dashboard users also use the new suite. The remaining 1 user says they need the old dashboard for a specific CSV export format that the new suite does not yet support. Our VP of Engineering wants it gone; the account manager for the enterprise customer wants a 6-month migration window. Conduct a lifecycle-learning outcome review and recommend a decision.",
      "expected_output": "A lifecycle-learning assessment that: (1) identifies the stark adoption gap (0.08% DAU, 12 users out of 15,000), (2) identifies the cost and risk profile ($8K/month + 2 engineering days/month + unmaintainable code + recent P1), (3) identifies that a replacement exists and 11/12 users have already migrated, (4) identifies the remaining blocker (1 user needs CSV export format), (5) recommends Retire — but with a CONTEXTUAL, EVIDENCE-BACKED rationale, not an arbitrary threshold: the combination of negligible adoption, high cost, operational risk, existence of a replacement, and near-complete migration makes retirement the right call, (6) names the accountable human decision-maker (role: VP of Engineering or product lead, not an automated threshold), (7) defines the sunset plan: deprecation announcement to the enterprise customer, 6-month migration window per account manager's request, CSV export format added to the new suite as the migration path, and a clear timeline with milestones (announcement, EOL, EOS, removal), (8) includes customer treatment: support commitments during sunset, data export guarantee, grace period, and (9) captures retained learning: what this feature's lifecycle taught about building features for single customers, about maintaining legacy code without succession planning, and about ensuring replacements cover all use cases before deprecation. The response does NOT say '0.08% < some threshold therefore auto-retire.' It builds the case from multiple dimensions of evidence and preserves human accountability.",
      "assertions": [
        "The response recommends Retire with a multi-dimensional evidence-backed rationale (adoption, cost, risk, replacement, migration status) — not a single numeric threshold",
        "The response names an accountable human decision-maker role (not 'the algorithm' or 'the threshold')",
        "The response defines a sunset plan with deprecation communication, migration path, customer treatment, and timeline milestones",
        "The response addresses the remaining blocker (1 user's CSV export need) with a migration solution, not by ignoring it",
        "The response captures retained learning (patterns for single-customer features, legacy maintenance, replacement completeness) in a durable record"
      ]
    },
    {
      "id": "retirement-requiring-migration-and-customer-communication",
      "prompt": "Our B2B SaaS product is retiring the legacy API (v1) that 340 enterprise customers still use, representing $2.1M in annual contract value. The v2 API has been available for 18 months and covers all v1 functionality plus additional capabilities. 72% of customers have already migrated. The remaining 340 customers cite: lack of engineering bandwidth (60%), satisfaction with v1 as-is (25%), and missing v1-specific webhook format in v2 (15%). We need to retire v1 because it runs on end-of-life infrastructure that will lose vendor support in 8 months, and maintaining it costs $45K/month in dedicated ops. The CEO has mandated retirement before the infrastructure EOL. Design the complete retirement lifecycle: deprecation communication, migration path, customer treatment plan, and internal cleanup. Pay special attention to the 15% of customers who need the webhook format and the risk of churning $2.1M in revenue.",
      "expected_output": "A complete retirement lifecycle plan that covers ALL FIVE phases: (1) Deprecation Communication — announcement with rationale (infrastructure EOL, cost, v2 coverage), timeline (8-month window tied to EOL date), affected-customer segmentation (the 340 customers broken down by their stated reason for not migrating), communication channels (account managers, email, in-product notice, documentation); (2) Migration Path — step-by-step v1-to-v2 migration guide, dedicated support channel, migration tooling if available, and a SPECIFIC solution for the 15% who need the webhook format (either add webhook format to v2, provide a compatibility shim, or offer an alternative); (3) Customer Treatment — support SLA preserved during sunset, 8-month grace period tied to the hard infrastructure EOL deadline, data export guarantee, escalation path for customers who need extensions, and proactive account-manager outreach coordinated with conditional-customer-success for the $2.1M at-risk accounts; (4) Internal Cleanup — v1 API endpoint removal, feature flag removal, code archival, documentation archival and cross-reference updates, monitoring retirement, infrastructure decommissioning after the removal date; (5) Learning Closure — retained learning record capturing: the 18-month coexistence window (was it long enough?), the webhook-format gap (why was this not identified earlier?), the customer communication strategy effectiveness, and reusable patterns for future API version retirements. The response explicitly distinguishes between expected (smooth migration within 18 months), observed (72% migrated, 28% haven't for specific reasons), uncertain (will the remaining customers churn?), and inferred (the webhook gap is the binding constraint for the last 15%). The response routes the retirement communication plan to conditional-customer-success for account-level execution. Claims are scoped to the harness, model, fixtures, and revision under test.",
      "assertions": [
        "The response covers all five retirement phases: deprecation communication, migration path, customer treatment, internal cleanup, and learning closure",
        "The response addresses the webhook-format gap for the 15% of customers with a specific solution, not a generic 'they should migrate' statement",
        "The response includes a customer treatment plan with support commitments, grace period, data export, and escalation path",
        "The response identifies the revenue-at-risk ($2.1M) and coordinates with conditional-customer-success for account-level execution",
        "The response captures retained learning with reusable patterns for future API version retirements"
      ]
    },
    {
      "id": "anti-pattern-arbitrary-threshold-rejection",
      "prompt": "I want you to create a dashboard that automatically retires any feature that drops below 100 daily active users or has an NPS below 30. Can you set up the automation rules?",
      "expected_output": "The response declines to apply product-lifecycle-learning for automatic retirement based on arbitrary thresholds. It explains that retirement decisions require human judgment and context — a feature with 95 DAU might be critical to a $5M enterprise account, and a feature with NPS 25 might be a utility feature users do not love but depend on. It states that this skill does not prescribe universal retirement thresholds and that applying numeric rules without context violates the skill's retirement-decision discipline. The response may suggest using the thresholds as monitoring signals that trigger a human review (not an automatic retirement), and routes the human review to the outcome review and retirement decision templates.",
      "assertions": [
        "The response declines to automate retirement decisions based on numeric thresholds",
        "The response explains that retirement requires human judgment and context, not a formula",
        "The response provides counterexamples showing why thresholds without context are misleading",
        "The response may suggest using thresholds as monitoring signals for human review, but not as automatic triggers",
        "The response does not produce an automated retirement rule or dashboard configuration"
      ]
    },
    {
      "id": "anti-pattern-incident-postmortem-routing",
      "prompt": "Our payment service had a 4-hour outage last week that affected 12,000 transactions. We need to do a postmortem and figure out what lifecycle learning we can extract from this incident. Can you run the incident postmortem using the lifecycle-learning skill?",
      "expected_output": "The response declines to run an incident postmortem with product-lifecycle-learning. It explains that incident postmortems, root-cause analysis, and operational incident review belong to incident-learning (prose reference, not yet landed) and site-reliability-engineering. It states that lifecycle-learning consumes incident signals as input (e.g., 'the payment service had a reliability incident that affected feature health') but does not produce postmortems. The response may suggest that after the incident postmortem is completed by the appropriate skill, lifecycle-learning can consume the output as part of a feature health assessment if the payment service is being evaluated for a lifecycle decision.",
      "assertions": [
        "The response declines to run an incident postmortem with product-lifecycle-learning",
        "The response routes incident postmortems to incident-learning and site-reliability-engineering",
        "The response explains that lifecycle-learning consumes incident signals as input but does not produce postmortems",
        "The response describes how lifecycle-learning could use postmortem output as input to a feature health assessment"
      ]
    }
  ]
}

# Discovery Brief — Product Lifecycle Learning

Bounded discovery for issue #194. Maps existing skill landscape relevant to
post-launch outcome review, feature health, assumption updates, retirement,
and retained learning.

## Existing Material Survey

| Skill | Relationship |
|---|---|
| `product-strategy` | Upstream. Defines lifecycle stages and decision-log concepts. Lifecycle-learning operationalizes the closure phase. |
| `product-roadmapping-and-portfolio` | Sibling. Sets strategic bets and roadmap priorities. Lifecycle-learning feeds evidence back into roadmap re-evaluation. |
| `product-analytics-and-measurement` | Sibling. Owns instrumentation and metric definitions. Lifecycle-learning consumes analytics outputs as input. |
| `product-adoption` | Sibling. Owns adoption diagnostics, activation, and sustained-use review. Lifecycle-learning consumes adoption evidence and feeds pattern changes back. |
| `product-experimentation` | Sibling. Owns experiment design and readout. Lifecycle-learning consumes experiment results and feeds new hypotheses. |
| `spec-driven-development` | Sibling. Owns specifications and acceptance criteria. Lifecycle-learning compares expected (from spec) against observed. |
| `site-reliability-engineering` | Sibling. Owns operational reliability and incident response. Lifecycle-learning consumes incident signals as input. |
| `product-methodology` | Sibling. Provides prioritization frameworks. Lifecycle-learning does not re-derive these. |

## Gaps This Skill Fills

| Gap | Response |
|---|---|
| No skill closes the launch-to-learning loop systematically | Full loop defined in SKILL.md: observe → compare → gap analysis → assumption update → health assessment → decide → retain learning → feed back |
| No systematic comparison of expected vs. observed outcomes | Epistemic discipline taxonomy in [epistemic-discipline.md](epistemic-discipline.md); outcome review template |
| No assumption ledger update methodology | Assumption ledger update template with confidence shifts |
| No feature health assessment that avoids single-score reduction | Multi-dimensional feature health record template |
| No structured retirement lifecycle covering deprecation, migration, customer treatment, and internal cleanup | Retirement lifecycle reference + sunset plan template |
| No skill produces a durable retained learning record rather than a transient meeting summary | Retained learning record template |
| No skill routes lifecycle evidence back to roadmap, analytics, adoption, experimentation, and specifications | Feedback destinations reference with explicit routing per decision type |

## Ownership Boundaries

**OWNS:** Post-launch outcome review, expected-vs-observed comparison with epistemic categories,
assumption ledger updates, feature health assessment, lifecycle decisions
(continue/improve/harvest/pivot/pause/retire), retirement lifecycle execution (deprecation
communication, migration paths, customer treatment during sunset, internal cleanup), durable
retained learning artifacts, feedback routing to downstream skills.

**Does NOT own:** Incident postmortems or root-cause analysis (routes to incident-learning
and site-reliability-engineering), analytics instrumentation or metric pipeline design (routes
to product-analytics-and-measurement), customer-success account management or health scoring
(routes to conditional-customer-success), roadmap prioritization or portfolio allocation (routes
to product-roadmapping-and-portfolio), experiment design or statistical analysis (routes to
product-experimentation and data-scientist), specification authoring (routes to
spec-driven-development).

## Retirement Decision Discipline

Retirement decisions require human judgment and named accountability. This skill never applies
automated thresholds like "retire if DAU < 100" or "kill if NPS < 30." Every retirement
decision must include: the accountable human decision-maker, the evidence considered, the
context (product, market, alternatives, user base), and the rationale. The retirement-decision
template enforces this contract.

## Routing Design

Five mandatory feedback destinations: roadmap, analytics, adoption, experimentation, and
specifications. Two conditional destinations: customer-success (for retirement communication
and migration coordination) and incident-learning (for incident-driven signals). See
[feedback-destinations.md](feedback-destinations.md).

Prose references to skills not yet landed: `conditional-customer-success` (same-wave issue
#192, dir not yet on main) and `incident-learning` (later milestone-2 issue, not yet landed).
Real relative links to existing directories: product-analytics-and-measurement,
product-roadmapping-and-portfolio, product-adoption, product-experimentation,
spec-driven-development.

# Epistemic Discipline

Every claim in a product-lifecycle-learning output is classified into exactly one of four
epistemic categories. These categories are never conflated. A comparison is not an observation.
An inference is not a fact. An uncertain claim is not dressed up as a certain one.

## The Four Categories

### Expected

What was intended, predicted, or hypothesized before the feature launched.

**Source:** Specification, roadmap brief, experiment hypothesis, launch document, acceptance criteria.

**Characteristics:**
- States a prediction: "we expected X to happen"
- Has a reference to the source artifact (spec, roadmap, experiment brief)
- Is falsifiable: it can be compared against observed data
- May include a target threshold or range

**Examples:**
- "We expected activation to reach 60% within 30 days of launch."
- "The hypothesis was that the redesigned checkout would increase conversion by at least 5 percentage points."
- "Engineering estimated p99 latency would stay under 200ms under projected load."

### Observed

What actually happened, measured from data collected after launch.

**Source:** Analytics systems, adoption metrics, operational monitoring, user feedback, support data.

**Characteristics:**
- States a measurement: "we observed X"
- Includes a confidence interval or precision estimate when available
- Names the measurement source and window
- Is reproducible: another observer with the same data would see the same thing
- Acknowledges missing or low-quality data explicitly

**Examples:**
- "Activation reached 43% at 30 days (95% CI: 39-47%, measured by Mixpanel activation funnel, N=12,400)."
- "P99 latency averaged 180ms during weekdays and 310ms during weekend peaks (source: Datadog, 90-day window)."
- "Support ticket volume for the feature was 14 tickets/week during the first month, declining to 3/week in month three."

### Uncertain

What is ambiguous, noisy, contested, or genuinely unknown.

**Source:** Confidence intervals that span decision boundaries, conflicting signals from different
sources, data-quality problems, external confounds, small sample sizes, early-stage data.

**Characteristics:**
- Names the specific uncertainty: "we cannot determine X because Y"
- Quantifies the uncertainty when possible (confidence interval, sample size, measurement error)
- Does not pretend certainty when it does not exist
- Distinguishes between aleatory uncertainty (inherent randomness) and epistemic uncertainty (we
  could know with better data)

**Examples:**
- "Attribution is confounded by a simultaneous pricing change; we cannot isolate the feature's effect on retention."
- "The confidence interval for conversion lift spans -1.2% to +4.8%, which crosses zero — the direction of effect is uncertain."
- "Only 3 enterprise customers have adopted the feature so far; the sample is too small to draw conclusions about enterprise adoption patterns."
- "User satisfaction scores improved for power users but worsened for casual users; the aggregate masks opposite effects in different segments."

### Inferred

What is concluded from the evidence, with reasoning made explicit.

**Source:** Comparison of expected and observed, gap analysis, assumption testing, domain expertise.

**Characteristics:**
- States a conclusion: "we infer that X"
- Is supported by evidence from the other three categories
- Makes the reasoning chain explicit: "because A (observed) and B (expected), we infer C"
- Is tagged with the strength of the inference: strong, moderate, tentative
- Is open to revision by new evidence

**Examples:**
- "We infer that the onboarding redesign did not reduce time-to-value as hypothesized, based on the gap between expected activation (60%) and observed activation (43%). The pricing-change confound means this inference is tentative — we cannot rule out an external cause."
- "We infer that the feature addressed a real need for the mid-market segment (strong inference: adoption exceeded expectations in that cohort and qualitative feedback was uniformly positive)."
- "We infer that the feature's value proposition was unclear to enterprise users, based on the combination of low enterprise adoption, high bounce rate on the feature landing page, and support questions about what the feature does."

## Field Guide: Classifying Claims

When writing or reviewing a lifecycle-learning artifact, classify every claim:

1. **Is it a prediction about what would happen?** → Expected
2. **Is it a measurement of what did happen?** → Observed
3. **Is it an acknowledgment of what we cannot determine?** → Uncertain
4. **Is it a conclusion drawn from the evidence?** → Inferred

If a claim does not fit cleanly into one category, it is likely conflating two categories and
should be split. "Adoption was low" conflates observation (the number) with inference (that the
number is low relative to expectations). Split into: "Observed: adoption was 12% at 90 days
(95% CI: 9-15%)" and "Inferred: this is below our 25% threshold for a healthy feature."

## Anti-Patterns

| Anti-pattern | Problem | Fix |
|---|---|---|
| "The feature was successful." | Conflates observation and inference; no evidence cited | State observed outcomes, compare to expectations, then infer success/failure with reasoning |
| "Adoption was 43%." (without confidence interval or source) | Treats a point estimate as certain | Add confidence interval, measurement source, and window |
| "The data shows the feature is working." | Vague; no comparison to expected outcomes | Compare observed against expected; state what "working" means |
| "We think users like it." | Inference presented as fact without evidence chain | Classify as uncertain or inferred; cite supporting observations |
| "The null result proves there is no effect." | Confuses absence of evidence with evidence of absence | State that the effect, if any, is below the detectable threshold; report the minimum detectable effect |

# Feedback Destinations

Every lifecycle-learning cycle routes its outputs to downstream skills. This reference defines
the contract for each destination: what is routed, when, and in what format.

## Mandatory Destinations (every cycle)

These five destinations must receive learning outputs from every lifecycle cycle, regardless
of the decision outcome.

### 1. Roadmap (product-roadmapping-and-portfolio)

**What is routed:**
- Lifecycle decision (continue/improve/harvest/pivot/pause/retire) with evidence
- Updated assumptions that affect strategic bets
- Feature health assessment summary
- Gap between expected and observed outcomes

**When:** After the lifecycle decision is recorded.

**Format:** A brief evidence update — not a full roadmap reprioritization. The roadmap skill
owns the decision about what to do with the evidence.

**Relative link:** [../../product-roadmapping-and-portfolio/SKILL.md](../../product-roadmapping-and-portfolio/SKILL.md)

### 2. Analytics (product-analytics-and-measurement)

**What is routed:**
- Measurement gaps discovered during outcome review (metrics that could not be observed)
- Metric refinement needs (definitions that were ambiguous or misleading)
- New metrics that would have improved the assessment
- Data-quality issues that affected confidence

**When:** After gap analysis identifies measurement gaps.

**Format:** A measurement-gap report — not a tracking plan. The analytics skill owns tracking-plan
design and instrumentation.

**Relative link:** [../../product-analytics-and-measurement/SKILL.md](../../product-analytics-and-measurement/SKILL.md)

### 3. Adoption (product-adoption)

**What is routed:**
- Adoption pattern changes (activation, retention, feature discovery)
- Cohort-level insights from outcome review
- Behavior-change evidence: what worked and what did not
- Sustained-use signals that inform adoption strategy

**When:** When the outcome review surfaces adoption-relevant patterns.

**Format:** An adoption evidence update — not an adoption plan. The adoption skill owns plan design.

**Relative link:** [../../product-adoption/SKILL.md](../../product-adoption/SKILL.md)

### 4. Experimentation (product-experimentation)

**What is routed:**
- New hypotheses surfaced by the outcome review
- Assumptions that need experimental validation
- Experiment ideas for features that received Improve or Pivot decisions

**When:** When the assumption update surfaces testable hypotheses.

**Format:** Hypothesis briefs — not experiment designs. The experimentation skill owns method
selection and experiment design.

**Relative link:** [../../product-experimentation/SKILL.md](../../product-experimentation/SKILL.md)

### 5. Specifications (spec-driven-development)

**What is routed:**
- Acceptance criteria that were ambiguous, untestable, or missing
- Expected outcomes that were poorly specified (could not be compared against observations)
- Spec improvements for future features based on what was learned

**When:** When the outcome review reveals specification gaps.

**Format:** Spec-improvement recommendations — not revised specs. The specification skill owns
spec authoring.

**Relative link:** [../../spec-driven-development/SKILL.md](../../spec-driven-development/SKILL.md)

## Conditional Destinations

These two destinations receive learning outputs only when the decision or evidence triggers them.

### 6. Customer Success (conditional-customer-success)

**Trigger:** Retirement decision, or outcome review surfaces customer-impacting signals.

**What is routed:**
- Retirement communication plans for customer-facing execution
- Migration support coordination for affected accounts
- Customer treatment strategy during sunset (grace periods, data export, support commitments)
- Customer feedback signals that require account-level follow-up

**Format:** A customer-impact brief — not account-level action plans. The customer-success skill
owns account management and health scoring.

**Routing:** Prose reference to `conditional-customer-success` (skill not yet landed; same-wave
issue #192). When the skill lands, replace with a relative link.

### 7. Incident Learning (incident-learning)

**Trigger:** An incident occurred that is relevant to the feature's lifecycle assessment.

**What is routed:**
- Incident signals that should feed the incident-learning loop
- Feature reliability data relevant to post-incident analysis
- Operational patterns observed during the assessment window

**Format:** An incident-signal summary — not a postmortem or root-cause analysis. The
incident-learning skill owns postmortem methodology.

**Routing:** Prose reference to `incident-learning` (skill not yet landed; later milestone-2 issue).
Also routes to [../../site-reliability-engineering/SKILL.md](../../site-reliability-engineering/SKILL.md)
for operational reliability context.

## Routing Rules

1. **Every cycle routes to all five mandatory destinations.** The outputs may be brief ("no
   adoption-relevant patterns found") but must not be silent omissions.
2. **Learning artifacts are routed, not duplicated.** The retained learning record is the
   canonical artifact; each destination receives the relevant subset or a pointer to it.
3. **The destination skill owns the response.** Lifecycle-learning does not prescribe what the
   roadmap, analytics, adoption, experimentation, or specification skill should do with the
   evidence. It delivers evidence; the destination decides.
4. **Prose references become links when the target skill lands.** `conditional-customer-success`
   and `incident-learning` are prose references until their directories exist on main. At that
   point, replace with relative links.

# Retirement Lifecycle

When the lifecycle decision is Retire, a structured retirement lifecycle covers the full path
from deprecation announcement through internal cleanup and learning closure. This reference
defines each phase, its required outputs, and its routing.

## Phase Overview

```
DEPRECATION ANNOUNCEMENT → MIGRATION PATH → CUSTOMER TREATMENT → INTERNAL CLEANUP → LEARNING CLOSURE
```

## Phase 1: Deprecation Communication

**Goal:** Inform affected users that the feature will be retired, with clear timeline, rationale,
and alternatives.

**Required outputs:**
- Deprecation announcement with target retirement date
- Rationale: why the feature is being retired (evidence-backed, not opinion)
- Affected-user segmentation: which users or cohorts are impacted, and how
- Alternative or replacement path: what users should use instead
- Timeline: announcement date, end-of-life date, end-of-support date, removal date
- Communication channels: in-product notice, email, documentation, support portal

**Template:** Use [../templates/sunset-plan.md](../templates/sunset-plan.md).

**Routing:** Coordinate communication plans with `conditional-customer-success` for
customer-facing execution, especially for enterprise and B2B products where customer
relationships are managed.

## Phase 2: Migration Path

**Goal:** Provide existing users with a clear, supported path to an alternative.

**Required outputs:**
- Migration guide: step-by-step instructions for moving to the replacement
- Data export: format, instructions, timeline, support contact
- Compatibility window: how long the old feature remains usable during migration
- Migration tooling: automated migration scripts, import tools, API compatibility shims
- Migration support: dedicated support channel, FAQs, office hours for enterprise accounts

**Template:** Use [../templates/sunset-plan.md](../templates/sunset-plan.md).

**Principles:**
- The migration path must be documented before the deprecation announcement, not after.
- Data export must be complete, lossless, and in an open or documented format.
- The compatibility window must be long enough for users to migrate — context-dependent,
  never a one-size-fits-all deadline.
- Enterprise and B2B users may need extended migration windows and dedicated support.

## Phase 3: Customer Treatment During Sunset

**Goal:** Treat affected users with respect and transparency during the transition.

**Required outputs:**
- Support commitment: what support is available during the sunset window, and at what SLA
- Grace period: how long users have before the feature is removed, with clear milestones
- Data export guarantee: users can export their data until the removal date
- Refund or credit policy: if applicable, how paid users are compensated
- Escalation path: how users can request extensions or exceptions

**Template:** Use [../templates/sunset-plan.md](../templates/sunset-plan.md).

**Routing:** Customer-treatment strategy routes to `conditional-customer-success` for account-level
execution, especially for products with named accounts, renewal cycles, or customer-success teams.
For products without customer-success teams (internal tools, public services, transactional
products), the sunset plan itself serves as the execution document.

**Principles:**
- Never remove access without notice. The deprecation announcement must precede removal by a
  documented interval.
- Never delete user data without offering export. Data belongs to the user.
- Never degrade support during the sunset window. Support commitments hold until the removal date.
- Respect the user's investment in the feature. Acknowledge the disruption and make the transition
  as smooth as possible.

## Phase 4: Internal Cleanup

**Goal:** Remove the feature completely from the system and update all internal artifacts.

**Required outputs:**
- Feature flag removal: remove all feature flags, kill switches, and toggles
- Code archival: archive the feature's code (do not leave dead code in the active codebase)
- Documentation update: remove or archive feature documentation; update references in other docs
- Monitoring and alerting retirement: remove dashboards, alerts, runbooks, and SLOs for the feature
- Infrastructure reclamation: decommission dedicated infrastructure, reclaim resources
- Dependency cleanup: remove third-party dependencies used only by the retired feature

**Template:** Use [../templates/sunset-plan.md](../templates/sunset-plan.md).

## Phase 5: Learning Closure

**Goal:** Capture what the feature's lifecycle taught before the evidence disappears.

**Required outputs:**
- Retained learning record: what was learned, why, and how it should inform future work
- Assumption ledger finalization: close out assumptions with final evidence
- Feedback routing: route learning to roadmap, analytics, adoption, experimentation, specifications

**Template:** Use [../templates/retained-learning-record.md](../templates/retained-learning-record.md).

**Principle:** The learning from a retired feature is as valuable as the learning from a successful
one. A feature that failed taught you something about your users, your market, or your assumptions.
Capture it before the evidence is gone.

## Decision Record Requirement

Every retirement decision must record:
- The accountable human decision-maker (name and role)
- The evidence considered (expected vs. observed, assumption ledger, feature health assessment)
- The context (product, market, user base, alternatives, business priorities)
- The rationale (why retire, not harvest or pivot)
- The date of decision
- The sunset timeline with phase milestones

No retirement decision may be made by an automated threshold. Rules like "retire if DAU < 100" or
"kill if NPS < 30" are prohibited in this skill. Retirement is a human judgment informed by
evidence, not a formula.

## Cross-Cutting: Incident Learning Distinction

Retiring a feature because it is unhealthy or misaligned with strategy is a lifecycle decision.
Retiring a feature because it caused an incident and a postmortem recommended removal is an
incident-driven decision. The latter routes through `incident-learning` (not yet landed) and
[../../site-reliability-engineering/SKILL.md](../../site-reliability-engineering/SKILL.md).
Lifecycle-learning consumes the incident signal as input but does not produce the postmortem.

# Assumption Ledger Update

Update the assumption ledger with evidence from the outcome review. For each assumption that
drove the feature, record whether it held, weakened, or broke, and adjust confidence accordingly.

## Feature Identity

| Field | Value |
|---|---|
| Feature / capability name | |
| Prior assumption ledger date | |
| Update date | |
| Updater | |

## Assumption Updates

For each assumption in the prior ledger, record the evidence from the outcome review and the
confidence shift.

| # | Assumption | Prior confidence | Evidence from outcome review | Held / Weakened / Broke | New confidence | Notes |
|---|---|---|---|---|---|---|
| 1 | | High / Medium / Low | | | High / Medium / Low | |
| 2 | | | | | | |
| 3 | | | | | | |

## New Assumptions Surfaced

What new assumptions did the outcome review surface that were not in the prior ledger?

| # | New assumption | Trigger (what observation surfaced this) | Initial confidence | Should this be tested? |
|---|---|---|---|---|
| 1 | | | High / Medium / Low | Yes / No |
| 2 | | | | |

## Assumptions to Retire

Which prior assumptions are no longer relevant and should be removed from the active ledger?

| # | Assumption | Reason for retirement |
|---|---|---|
| 1 | | |
| 2 | | |

## Ledger Health

- **Total assumptions (active):**
- **High-confidence assumptions:**
- **Assumptions that weakened or broke this cycle:**
- **Assumptions overdue for re-examination (no update in >2 cycles):**
- **Blind spots:** (areas where we have no assumptions but probably should)

## Routing

- [ ] Updated assumptions routed to roadmap (product-roadmapping-and-portfolio)
- [ ] Testable new assumptions routed to experimentation (product-experimentation)
- [ ] Measurement-gap assumptions routed to analytics (product-analytics-and-measurement)

# Feature Health Record

Assess feature health across multiple dimensions. Do not reduce to a single score or traffic-light
color. Each dimension has its own evidence, confidence, and trend.

## Feature Identity

| Field | Value |
|---|---|
| Feature / capability name | |
| Assessment date | |
| Assessor | |
| Prior health record date | |

## Health Dimensions

### 1. Adoption Health

| Metric | Value | Confidence | Trend (over 3 cycles) | Threshold for concern |
|---|---|---|---|---|
| Activation rate | | | Improving / Stable / Declining | |
| Time-to-value (median) | | | | |
| Feature discovery rate | | | | |
| Sustained use (DAU/WAU/MAU as appropriate) | | | | |
| Cohort retention (30/60/90-day) | | | | |

**Adoption health summary:** (narrative, with evidence)

### 2. Technical Health

| Metric | Value | Confidence | Trend | Threshold for concern |
|---|---|---|---|---|
| Error rate | | | | |
| P95/P99 latency | | | | |
| Availability (uptime %) | | | | |
| Known bugs (open, by severity) | | | | |
| Dependency freshness (outdated deps) | | | | |

**Technical health summary:** (narrative, with evidence)

### 3. Operational Health

| Metric | Value | Confidence | Trend | Threshold for concern |
|---|---|---|---|---|
| Support ticket volume | | | | |
| Time-to-resolution (median) | | | | |
| Alert frequency (false positives, actionable) | | | | |
| On-call burden (pages per week) | | | | |
| Documentation freshness | | | | |

**Operational health summary:** (narrative, with evidence)

### 4. Strategic Health

| Factor | Assessment | Evidence |
|---|---|---|
| Alignment with current strategy | Strong / Moderate / Weak | |
| User need confirmed | Yes / Partial / No | |
| Competitive differentiation | Strong / Moderate / Weak / None | |
| Revenue or value contribution | | |
| Replacement or alternative exists | Yes / Partial / No | |

**Strategic health summary:** (narrative, with evidence)

## Cross-Dimension Patterns

Are there correlations or conflicts across dimensions? (e.g., "High adoption but declining
technical health — investment in reliability needed" or "Strong strategic alignment but no
adoption — discovery or positioning problem")

## Overall Assessment

- **Strongest dimension:**
- **Weakest dimension:**
- **Most concerning trend:**
- **Most improved since last assessment:**
- **Recommended lifecycle decision direction:** (continue / improve / harvest / pivot / pause / retire — preliminary, to be confirmed by the formal decision record)

# Outcome Review

Compare expected outcomes against observed outcomes for a feature or capability that has been
live long enough to produce data. Use the epistemic discipline categories: every claim is
classified as expected, observed, uncertain, or inferred. See
[../references/epistemic-discipline.md](../references/epistemic-discipline.md).

## Feature Identity

| Field | Value |
|-------|-------|
| Feature / capability name | |
| Launch date | |
| Review date | |
| Review window (start → end) | |
| Reviewer | |

## Expected Outcomes

What did we predict or intend before launch? Source each expectation.

| # | Expected outcome | Source (spec, roadmap, hypothesis) | Target threshold or range |
|---|---|---|---|
| 1 | | | |
| 2 | | | |
| 3 | | | |

## Observed Outcomes

What actually happened, measured from data? Include confidence intervals and sources.

| # | Observed outcome | Value | Confidence interval / precision | Measurement source | Window |
|---|---|---|---|---|---|
| 1 | | | | | |
| 2 | | | | | |
| 3 | | | | |

## Gap Analysis

For each expected outcome, compare against the corresponding observed outcome.

| Expected # | Observed # | Gap (direction and magnitude) | Confidence in gap | Notes |
|---|---|---|---|---|
| | | | High / Medium / Low | |

## Uncertain Claims

What could not be determined, or is ambiguous or contested?

| # | Uncertainty | Type (aleatory / epistemic) | Impact on assessment |
|---|---|---|---|
| 1 | | | |
| 2 | | | |

## Inferred Conclusions

What do we conclude from the comparison, with reasoning made explicit?

| # | Inference | Supporting evidence (expected + observed + uncertain) | Strength (strong / moderate / tentative) |
|---|---|---|---|
| 1 | | | |
| 2 | | | |

## Summary

- **Overall alignment:** (e.g., "3 of 5 expected outcomes matched; 1 significantly below; 1 uncertain")
- **Key surprise:** (what was most unexpected, in either direction)
- **Key uncertainty:** (the most important thing we cannot determine)
- **Recommended next step:** (proceed to assumption update / health assessment / decision)

# Retained Learning Record

Capture durable reusable learning from a completed lifecycle cycle. This is not a transient
meeting summary — it is the evidence that the launch-to-learning loop actually closed. The
record survives the feature and informs future decisions.

## Record Identity

| Field | Value |
|---|---|
| Feature / capability name | |
| Lifecycle decision | (continue / improve / harvest / pivot / pause / retire) |
| Decision date | |
| Record author | |
| Record date | |
| Record ID | (unique, stable identifier) |

## What We Expected

Summarize the key expected outcomes from the spec, roadmap, or launch brief. What did we
predict would happen?

## What We Observed

Summarize the key observed outcomes with confidence. What actually happened?

## What Was Uncertain

What could we not determine? What was ambiguous, noisy, or contested?

## What We Inferred

What did we conclude, and with what strength? What is the chain of reasoning from evidence
to conclusion?

## Assumptions: Before and After

| Assumption | Before (confidence) | After (confidence) | What changed? |
|---|---|---|---|
| | | | |
| | | | |
| | | | |

## What We Would Do Differently

Given what we now know, what would we change about how this feature was specified, built,
launched, or measured?

## Reusable Patterns

What patterns, heuristics, or rules of thumb emerged that apply beyond this feature?

| Pattern | Description | When it applies | Confidence |
|---|---|---|---|
| | | | |
| | | | |

## Anti-Patterns to Avoid

What approaches failed or produced misleading results that should be avoided in the future?

| Anti-pattern | Description | Why it failed | How to detect it early |
|---|---|---|---|
| | | | |
| | | | |

## Feedback Routed

| Destination | What was routed | Date |
|---|---|---|
| Roadmap (product-roadmapping-and-portfolio) | | |
| Analytics (product-analytics-and-measurement) | | |
| Adoption (product-adoption) | | |
| Experimentation (product-experimentation) | | |
| Specifications (spec-driven-development) | | |
| Customer Success (conditional-customer-success) | (if applicable) | |
| Incident Learning (incident-learning) | (if applicable) | |

## Record Status

**Status:** (Draft / Final)

**Next review:** (date or "terminal — feature retired")

**Linked records:** (prior retained learning records for the same feature, if any)

# Retirement / Continuation Decision

Make and record a lifecycle decision: continue, improve, harvest, pivot, pause, or retire.
This decision requires human judgment informed by evidence. No automated threshold or formula
replaces context and accountability.

## Feature Identity

| Field | Value |
|---|---|
| Feature / capability name | |
| Decision date | |
| Decision-maker (name and role) | |
| Prior decision (if any) and date | |

## Evidence Considered

| Source | Date | Key findings |
|---|---|---|
| Outcome review | | |
| Assumption ledger | | |
| Feature health record | | |
| Other (specify) | | |

## Decision

**Decision:** (Continue / Improve / Harvest / Pivot / Pause / Retire)

**Rationale:** (Why this decision, not the other five? Cite the specific evidence that drove the
choice. If retiring, explain why harvest or pivot was rejected. If continuing, explain why
improve or harvest was not selected.)

**Context considered:**
- Product and market context:
- User base and impact:
- Available alternatives for users:
- Business priorities and resource constraints:
- Strategic alignment:

**Risks of this decision:**
- If we are wrong, what breaks?
- What would change our mind?

**Risks of NOT making this decision (status quo):**
- What deteriorates if we defer?

## Accountable Human Judgment

**Decision-maker:** (name and role — must be a human, not an automated system or threshold)

**I confirm that I have reviewed the evidence above and made this decision based on my
judgment of the product, market, user, and business context.**

**Sign-off date:**

## If Retire: Sunset Triggers

| Trigger | Date / condition |
|---|---|
| Deprecation announcement | |
| End-of-life (last day of full support) | |
| End-of-support (last day of limited support) | |
| Removal (feature removed from product) | |
| Internal cleanup complete | |
| Learning closure recorded | |

**Sunset plan:** (link to [sunset-plan.md](sunset-plan.md) or fill here)

## If Not Retire: Follow-Up

| Action | Owner | Due date |
|---|---|---|
| Next review date | | |
| Metrics to monitor | | |
| Triggers that would change the decision | | |

## Routing

- [ ] Decision routed to roadmap (product-roadmapping-and-portfolio)
- [ ] If retire: sunset plan routed to customer-success (conditional-customer-success)
- [ ] Learning routed to retained learning record

# Sunset Plan

Plan the full retirement lifecycle for a feature or capability: deprecation communication,
migration path, customer treatment during sunset, and internal cleanup. Use when the lifecycle
decision is Retire. See [../references/retirement-lifecycle.md](../references/retirement-lifecycle.md).

## Feature Identity

| Field | Value |
|---|---|
| Feature / capability name | |
| Retirement decision date | |
| Sunset plan author | |
| Sunset plan date | |

## Deprecation Communication

| Field | Value |
|---|---|
| Deprecation announcement date | |
| Rationale for retirement (evidence-backed) | |
| Replacement or alternative | |
| Affected user segments | |
| Communication channels | |

**Announcement draft / key messages:**

## Timeline

| Milestone | Date | Description |
|---|---|---|
| Announcement | | Public deprecation notice |
| End-of-life (EOL) | | Last day of full support |
| End-of-support (EOS) | | Last day of limited support; no new bug fixes |
| Removal | | Feature removed from the product |
| Data export deadline | | Last day users can export data |
| Internal cleanup complete | | All flags, code, docs, monitoring removed |

## Migration Path

| Field | Value |
|---|---|
| Recommended replacement | |
| Migration guide location | |
| Data export format | |
| Data export instructions | |
| Migration tooling available | Yes / No — describe |
| Compatibility window | (how long the old and new coexist) |

**Step-by-step migration instructions for users:**

## Customer Treatment

| Field | Value |
|---|---|
| Support SLA during sunset | |
| Grace period duration | |
| Data export guarantee | Yes / No — describe |
| Refund or credit policy | |
| Escalation contact for exceptions | |
| Enterprise / B2B extended support | Yes / No — describe |

**Customer communication plan:** (coordinate with `conditional-customer-success` for
account-level execution — prose reference, skill not yet landed)

## Internal Cleanup Checklist

- [ ] Feature flags removed
- [ ] Kill switches and toggles removed
- [ ] Code archived (not deleted — archived for reference)
- [ ] Dead code paths removed from active codebase
- [ ] Documentation removed or archived
- [ ] Documentation cross-references updated
- [ ] Monitoring dashboards retired
- [ ] Alerting rules removed
- [ ] SLOs / SLIs updated or removed
- [ ] Runbooks archived
- [ ] Infrastructure decommissioned
- [ ] Third-party dependencies removed (if feature-specific)
- [ ] Database tables / schemas cleaned up (after data export window closes)
- [ ] API endpoints deprecated and removed
- [ ] On-call rotations updated
- [ ] Support knowledge base updated

## Learning Closure

- [ ] Retained learning record completed
- [ ] Assumption ledger finalized
- [ ] Learning routed to roadmap, analytics, adoption, experimentation, specifications