---
name: pm-planning
description: Apply product management thinking when analyzing a codebase to plan milestones. Use during autonomous planning (sf autonomous, discuss-headless) to discover what needs to be built, prioritize work, and define done. Synthesizes Working Backwards, JTBD, Opportunity-Solution Tree, RICE prioritization, and scoping/cutting frameworks adapted for software development planning.
---

# PM Planning: Autonomous Codebase-to-Roadmap Thinking

Apply rigorous product management frameworks when analyzing a codebase autonomously to decide what to build next. These frameworks were designed for product managers at Stripe, Figma, Duolingo, Airbnb — adapt them for software planning from evidence in code.

---

## Phase 1: Diagnose Before You Plan

### The Rumelt Framework (Technical Diagnosis)
Structure your analysis as:
1. **Diagnosis** — What is the core challenge? What is broken, incomplete, or risky?
2. **Guiding Policies** — What principles will govern decisions? (e.g., "boring tech over novelty", "test coverage before features")
3. **Actions** — Specific milestones and slices that follow from the policies

Never start planning without completing the diagnosis. A plan without a diagnosis is just a wish list.

### Struggling Moments = Demand
Bob Moesta: *"A struggling moment causes demand. Nobody creates a product and then demand follows — the struggling moment exists first."*

When analyzing code, look for struggling moments encoded in the codebase:
- `TODO`, `FIXME`, `HACK`, `XXX` comments — places devs knew something was wrong
- Error handling with `panic`, `log.Fatal`, or bare `catch (e) {}` — brittle paths
- Missing test files or `// test this` comments — unvalidated logic
- Hardcoded values, magic numbers, missing configuration — future pain
- Dead code, commented-out features — abandoned attempts
- Long functions, high cyclomatic complexity — cognitive overload

These are your users' (developers') struggling moments. They are the real requirements.

---

## Phase 2: Working Backwards (Define Done First)

Before writing a single slice, answer: **What does the finished milestone look like?**

Write a mental press release for each milestone:
- **Headline:** What is now true that wasn't before?
- **Customer benefit:** Who benefits and how? (for internal tools: who uses this and what can they now do?)
- **Before/After:** What was the experience before? What is it after?
- **Evidence of done:** What test, metric, or demo proves it?

Ian McAllister: *"Working backwards is all about the problem and starting there. Teams that do it wrong don't work backwards — they have something they want to build."*

Apply to milestones: don't plan implementation until you can answer "why does this exist?" and "what proves it's complete?"

---

## Phase 3: Opportunity-Solution Tree (Problem Space First)

Teresa Torres framework — always discover the problem space before the solution space.

```
Desired Outcome (what changes for the better)
    │
    ├── Opportunity 1 (problem/gap discovered in codebase)
    │       ├── Solution A
    │       └── Solution B
    │
    ├── Opportunity 2 (problem/gap)
    │       ├── Solution A
    │       └── Solution B
    │
    └── Opportunity 3 (problem/gap)
            └── Solution A
```

**In codebase analysis, opportunities come from:**
- Missing test coverage on critical paths
- Error handling gaps (unhandled edge cases)
- Performance bottlenecks (slow queries, N+1 patterns)
- Security gaps (unvalidated inputs, missing auth checks)
- Missing observability (no metrics, no structured logging)
- Incomplete features (half-built flows, stub implementations)
- Integration failures (APIs called but not validated)
- Documentation gaps that block onboarding

**Anti-patterns:**
- Do NOT start with solutions ("we need a cache layer") — start with problems ("response times degrade under load")
- Do NOT confuse tech debt with opportunity — ask whether fixing it changes the outcome
- Do NOT skip the tree — going straight from diagnosis to implementation skips the problem/solution mapping

---

## Phase 4: JTBD Analysis — Who Is This For?

Even for internal/technical software, apply Jobs-to-be-Done:

**Functional jobs** (what task must be accomplished):
- "Deploy reliably without fear of breaking production"
- "Understand what the system is doing when something goes wrong"
- "Add a new feature without breaking existing ones"
- "On-board a new engineer in less than a day"

**Social jobs** (how stakeholders want to be perceived):
- "Demonstrate to leadership that the system is stable and measurable"
- "Earn trust from ops team that deployments are safe"

**Emotional jobs** (what anxiety is removed):
- "Not be woken up at 3am by a silent failure"
- "Feel confident that test suite catches regressions"
- "Trust the data in dashboards is accurate"

**Map discovered gaps to jobs.** A gap that addresses no job is low priority. A gap that addresses multiple intense jobs is the highest priority.

---

## Phase 5: Prioritization — Cannonballs vs Lead Bullets

Adriel Frederick: *"Have some cannonballs — high-investment, high-impact bets — and lead bullets — incremental improvements. 80% energy on cannonballs, 20% on lead bullets."*

Score opportunities with RICE:
- **Reach** — how many users/paths/features affected
- **Impact** — severity if unaddressed (data loss > UX glitch)
- **Confidence** — how certain are we this matters (evidence in code = high confidence)
- **Effort** — estimated slice count to address

**Cannonballs** in codebase terms:
- No test coverage on the main business flow
- No error recovery in critical path (data loss risk)
- Missing observability (blind operations)
- Core feature incomplete (can't demo the product)

**Lead bullets:**
- Code style inconsistencies
- Minor performance improvements
- Documentation completeness
- Nice-to-have features

**Prioritize cannonballs first. They have asymmetric upside.**

---

## Phase 6: MVP Thinking — Build the Scooter

Eeke de Milliano: *"If you're building an MVP for a car, don't build just the axle — build a scooter. A scooter is a complete, functional, smaller value proposition."*

Each milestone should be a scooter: **a complete, functional, demonstrable thing** — not a half-finished larger thing.

Apply when defining slice boundaries:
- Does this slice deliver something runnable/testable/demoable by itself?
- If we stopped after this slice, would we have something of value?
- Is the slice end-to-end (vertical slice) or horizontal infrastructure with no immediate user value?

**Appetite-based scoping** (Ryan Singer):
- Fix the time budget first: "This milestone should complete in 2-3 weeks of AI work"
- Vary scope to fit the appetite — never extend deadlines, cut scope
- If a feature can't be scoped to fit, it's probably two milestones

**Cut aggressively:**
- Remove anything that isn't in the critical path to done
- Remove anything where manual testing can substitute for automation (for now)
- Remove anything the job doesn't require

---

## Phase 7: Technical Strategy Principles

Will Larson: *"A common strategy that's really good but boring: we only use the tools we already have. Engineers want to introduce new languages and databases. A great strategy for most companies is: use the standard kit."*

When planning milestones:
- Prefer fixing existing code over introducing new abstractions
- Prefer tests over documentation (tests are executable documentation)
- Prefer removing code over adding code when the job can be done either way
- Prefer simple over clever — if you can't explain it in one sentence, it's too complex

---

## Synthesis: What to Put in CONTEXT.md

A strong CONTEXT.md answers all of these:
1. **Diagnosis** — What is the core challenge this milestone addresses?
2. **Desired outcome** — What is different after this milestone? Who benefits?
3. **Evidence** — What in the codebase (struggling moments, test failures, TODOs) confirms this is real?
4. **Job addressed** — Whose functional/emotional job does this serve?
5. **Scooter definition** — What is the complete, demonstrable end state?
6. **Appetite** — Rough estimate (slices, sessions)
7. **Cannonball or lead bullet?** — Is this high-leverage or incremental?
8. **Assumptions** — What did we decide autonomously and why?

---

## Anti-Patterns to Avoid

- **Shiny object trap** (Marily Nika): Don't plan AI features, new frameworks, or architectural rewrites unless there's a diagnosed struggling moment that demands it
- **Solution-first** (Ian McAllister): Don't start with "we should add X" — start with "users struggle with Y"
- **All incremental, no cannonballs** (Jackie Bavaro): A roadmap that's only bug fixes and tech debt never moves the product forward
- **Feature factory** (Teresa Torres): Planning without problem discovery — shipping things without evidence they address real pain
- **Never killing scope**: If scope grows in investigation, cut elsewhere — appetite is fixed
- **Unwritten strategy** (Will Larson): Plans that exist only in prompts can't be debugged. Write CONTEXT.md before planning slices.

---

## Persistent Memory: `.sf/PM-STRATEGY.md`

After each planning session (bootstrap, discuss-milestone, research-milestone), write or update `.sf/PM-STRATEGY.md` with your PM analysis. This file is the project's product strategy memory — it persists across all sessions and milestones.

**Write after every planning unit.** Future agents read this to understand what's been decided strategically and why.

### File format

```markdown
# Product Strategy

_Last updated: YYYY-MM-DD by <unit-type>_

## Diagnosis
<!-- Rumelt: what is the core challenge? Updated as new struggles discovered. -->

## Opportunity Map
<!-- OST: top opportunities with evidence, RICE scores, cannonball/lead-bullet classification -->
| Opportunity | Evidence | Reach | Impact | Confidence | Effort | Score | Class |
|---|---|---|---|---|---|---|---|
| ... | ... | ... | ... | ... | ... | ... | cannonball/lead-bullet |

## Jobs Analysis
<!-- Whose functional/emotional jobs does this product serve? What anxieties are removed? -->

## Guiding Policies
<!-- Rumelt: principles governing decisions. e.g. "tests before features", "no new dependencies without diagnosis" -->

## Strategic Decisions
<!-- What was decided and why — supplement to DECISIONS.md with product-level rationale -->

## What Was Deferred and Why
<!-- Opportunities/features explicitly scoped out. Prevents relitigating the same decisions. -->

## Milestone Sequencing Rationale
<!-- Why milestones are in this order — what job each unlocks -->
```

**Rules:**
- Append new findings, don't overwrite old ones — this is a running log
- Always update the Opportunity Map when new struggling moments are discovered
- Always update Guiding Policies when a new principle emerges from analysis
- Mark deferred items explicitly — "out of scope for now" is valuable signal

---

## Sources

Synthesized from:
- [lenny-skills (RefoundAI)](https://github.com/RefoundAI/lenny-skills) — 86 PM skills from Lenny's Podcast
- [Product-Manager-Skills (deanpeters)](https://github.com/deanpeters/Product-Manager-Skills) — 47 skills, Teresa Torres, Geoffrey Moore frameworks
- Teresa Torres, *Continuous Discovery Habits* — Opportunity Solution Tree
- Richard Rumelt, *Good Strategy/Bad Strategy* — Diagnosis/Policies/Actions
- Bob Moesta, *Demand-Side Sales* — Struggling moments and JTBD
- Ryan Singer, *Shape Up* — Appetite-based scoping
