Product Lifecycle Skill

The complete workflow from "I have an idea" to "code is shipped." Ensures that every feature is evaluated before it's built, every solution is chosen deliberately, and every implementation starts with a clear spec.

When to Activate

• User mentions a product idea, feature request, or "we should build X"
• User invokes /idea, /evaluate, /explore, or /prd
• User asks "is this worth building?" or "what's the best approach for X?"
• User wants to understand the full development process
• Multiple solution approaches exist and a trade-off analysis is needed before coding begins
• Acceptance criteria are missing or too vague to guide implementation
• Stakeholders need to align on scope before engineering work starts
• A feature was built but its value or success metrics were never defined

---

Quick Decision Flow

Right now, which stage are you in?

1. Have a raw idea or feature request?
   → /idea "<description>"       (produces docs/ideas/<name>.md)

2. Idea documented but not evaluated?
   → /evaluate <name>            (Go / No-Go / Modify from product-evaluator agent)
   → If No-Go: STOP. Document why. Do not build.

3. Got a Go or Modify? Need to pick an approach?
   → /explore <name>             (2-4 options + ADR from solution-designer agent)

4. Approach chosen? Need a spec?
   → /prd <name>                 (PRD with user stories + acceptance criteria)

5. PRD ready? Time to implement?
   → /overnight <name>           (autonomous pipeline, reads PRD)
   → /plan <name>                (step-by-step plan, then /tdd)

6. Implementation done?
   → /code-review + /verify + commit + PR

Skip a stage only if: you already have its output (e.g., the team already wrote a PRD). Don't skip evaluation — it's the only gate that prevents building the wrong thing.

---

The Full Lifecycle

@startuml
skinparam defaultFontSize 13

|Product Discovery|
:Raw idea in your head;
:/idea "description"\n→ docs/ideas/<name>.md;
note right
  Structures the idea:
  problem, user, success metric
  Asks clarifying questions
  if gaps exist
end note

:/evaluate <name>\n→ docs/evals/<name>-eval.md;
note right
  product-evaluator agent:
  problem clarity, user fit,
  alternatives research,
  feasibility, Go/No-Go
end note

if (Go or Modify?) then (yes)
  :/explore <name>\n→ docs/decisions/<name>-adr.md;
  note right
    solution-designer agent:
    2-4 options, trade-off table,
    Architecture Decision Record
  end note

  :/prd <name>\n→ docs/specs/<name>-prd.md;
  note right
    User stories, acceptance criteria,
    API changes, NFRs, scope
    Compatible with /overnight + /plan
  end note
else (No-Go)
  :Document reason\nRevisit or discard;
  stop
endif

|Implementation|
:/overnight implement <name>\nor /plan <name>\nor /tdd <name>;
note right
  Reads the PRD.
  /overnight auto-selects
  pipeline pattern.
  /plan creates step-by-step plan.
end note

:Implementation runs\n(with TDD, API Contract if needed);

:Code Review + Verify;

:Commit + PR;

stop
@enduml

---

Stage 1: Idea Capture (/idea)

Purpose: Turn a vague thought into a structured idea document.

Produces: docs/ideas/YYYY-MM-DD-<name>.md

A good idea document answers:

1. Problem — What problem, for whom, in what situation?
2. User — Specific persona, not "users"
3. Current state — What do they do today, and why is it bad?
4. Proposed solution — Rough shape of the answer
5. Success metric — What would measurably improve?

Common mistake: Starting with the solution ("we should use WebSockets") instead of the problem. The /idea command asks for the problem first.

---

Stage 2: Evaluation (/evaluate)

Purpose: Determine if the idea is worth building, before writing any code.

Produces: docs/evals/YYYY-MM-DD-<name>-eval.md

Delegated to: product-evaluator agent (model: Opus)

Evaluation Dimensions

Dimension	What it assesses
Problem Clarity	Is the problem real, specific, and well-understood?
User Fit	Is there a concrete user with this problem, urgently?
Solution Fit	Does the proposed solution actually solve the problem?
Feasibility	Effort estimate, dependencies, risk level
Differentiation	Why build vs. use an existing tool?
Opportunity Cost	What are we NOT building if we build this?

Possible Outcomes

@startuml
start
:Evaluation Complete;
if (Score ≥ 20/30\nand no red flags?) then (yes)
  :GO\nProceed to /explore;
  stop
else
  if (Core problem valid\nbut scope/approach wrong?) then (yes)
    :MODIFY\nAdjust scope or approach\nthen /explore the modified version;
    stop
  else (no)
    :NO-GO\nDocument reason\nConsider alternative action;
    stop
  endif
endif
@enduml

Red Flags → No-Go

• Problem Clarity or User Fit < 3/5
• A clearly superior existing solution found
• Opportunity Cost < 2/5 (something more important needs doing)
• Overall score < 15/30

---

Stage 3: Solution Design (/explore)

Purpose: Find the best approach, not just any approach.

Produces: docs/decisions/YYYY-MM-DD-<name>-adr.md

Delegated to: solution-designer agent (model: Opus)

What Good Options Look Like

Options must be meaningfully different, not minor variations:

Option Type	Example
Minimal / In-house	Use existing infrastructure, minimal new code
Third-party service	Integrate Firebase FCM, Stripe, Auth0, etc.
Full custom	Own implementation, maximum control
Phased approach	Start minimal, designed for extension

Trade-off Matrix

The solution-designer scores each option across relevant dimensions:

           | Option A | Option B | Option C |
-----------|----------|----------|----------|
Complexity | ✓✓       | ✗        | ✓        |
Time→value | ✓✓       | ✓✓       | ✗        |
Control    | ✗        | ~        | ✓✓       |
Cost       | ✓✓       | ✗        | ✓        |
Risk       | ✓✓       | ✓        | ✗        |

✓✓ very good / ✓ good / ~ neutral / ✗ poor / ✗✗ very poor

What an ADR Must Contain

1. Context — what constraints shape the solution space
2. Options — 2-4 meaningfully different approaches, each concrete enough to estimate
3. Trade-off table — honest comparison
4. Decision — one choice, with clear reasoning
5. Rejected options — why each was not chosen
6. Implementation sketch — what files/APIs would change

---

Stage 4: PRD (/prd)

Purpose: Write the implementation spec that bridges product thinking and code.

Produces: docs/specs/YYYY-MM-DD-<name>-prd.md

The PRD is the handoff document. It is directly consumed by /overnight, /plan, and /tdd.

PRD Structure

Section	Purpose
Problem + Solution	1 paragraph each — what and why
User Stories	"As a X, I want Y so that Z"
Acceptance Criteria	Concrete, testable, checkboxes
Scope (in/out)	Explicit boundary prevents scope creep
API Changes	If any — triggers api-contract step
Non-Functional Requirements	Latency, security, retention
Implementation Notes	Key ADR decisions that constrain code
Success Metrics	Post-ship measurement

Acceptance Criteria Quality Check

Good criteria are:

• Specific: "GET /api/v1/auth/github redirects to GitHub with scope=read:user" ✓
• Testable: Can be verified by a test or a manual check ✓
• Binary: Either done or not done ✓

Bad criteria:

• "Push notifications work" ✗ (vague)
• "Fast enough" ✗ (not measurable)
• "Good user experience" ✗ (subjective)

---

Stage 5: Implementation (existing commands)

The PRD feeds directly into the implementation pipeline:

/overnight implement <name>   → autonomous pipeline, reads PRD, selects pattern
/plan <name>                  → interactive planning from PRD
/tdd <name>                   → starts RED phase from acceptance criteria

The overnight-pipeline command knows to look for PRD files in docs/specs/ — so if you name the idea consistently, handoff is automatic.

---

File Structure Convention

docs/
  ideas/
    2025-03-05-order-push-notifications.md     ← /idea output
  evals/
    2025-03-05-order-push-notifications-eval.md  ← /evaluate output
  decisions/
    2025-03-05-order-push-notifications-adr.md   ← /explore output
  specs/
    2025-03-05-order-push-notifications-prd.md   ← /prd output
    (also used by /overnight for implementation)

Use the same <feature-name> throughout. Commands search by partial name match, so push-notifications finds all related documents.

---

When to Skip Stages

Not every change needs the full lifecycle:

Change Type	Stages to Run
New product feature (unknown value)	All 4 stages
New feature (clear value, chosen approach)	/prd → implement
Bug fix	Directly to /plan or /tdd
Refactor (no behavior change)	Directly to /plan
Chore (deps, config, tooling)	Directly to implementation
Internal API change	/prd (for spec) → implement

The product discovery phase is most valuable when:

• You're uncertain whether it's worth building
• Multiple approaches exist and the choice isn't obvious
• Multiple stakeholders need to align on scope before work starts

---

Common Mistakes

Mistake	Consequence	Fix
Skipping evaluation	Build the wrong thing	Always evaluate before building
Solution in the idea doc	Evaluating the solution, not the problem	Rewrite the problem statement without the solution
Vague acceptance criteria	"Done" is never defined	Each criterion must be binary and testable
Skipping the ADR	Repeat the same architecture debates later	Always document the decision and rejected options
PRD without success metrics	Can't learn from what shipped	Add at least 1 measurable post-ship metric
Scope creep in the PRD	Implementation grows indefinitely	Explicit "Out of Scope" section is mandatory

---

Quick Reference

# Capture a new idea
/idea push notifications when orders ship

# Evaluate it (is it worth building?)
/evaluate order-push-notifications

# Design the solution (which approach?)
/explore order-push-notifications

# Write the PRD (what exactly to build)
/prd order-push-notifications

# Implement (autonomous overnight)
/overnight implement order-push-notifications

# OR: implement interactively
/plan order-push-notifications
/tdd order-push-notifications

---

Related Skills and Commands

• api-contract — invoked automatically when PRD contains API changes
• overnight-pipeline — autonomous implementation from PRD
• autonomous-loops — pattern library for unattended execution
• /plan — interactive implementation planning (reads PRD)
• /tdd — test-driven implementation (reads acceptance criteria from PRD)
• /code-review — review after implementation