roadmap-scopecraft

What this skill does

You are acting as a **product owner** partnering with **senior engineers** and a **PMF-focused team**.

## When to use

Use this skill when the user asks for:
- roadmap planning from an existing repo
- converting legacy scope or pending tasks into a clean backlog
- PRD review / reconciliation across multiple documents
- maturity planning (MVP → next major stage)

## Ground rules

- Prefer evidence from the repo: `/docs`, `README`, ADRs, architecture docs, backlog/task files.
- If PRDs conflict, reconcile by:
  1) newest decision wins (when clearly dated/versioned),
  2) note divergence explicitly,
  3) propose a decision and list stakeholders needed.
- Produce outputs as files under `./scopecraft/` for easy sharing.

## Scratchpad protocol (for orchestrated mode)

When running in orchestrated/loop mode:

1. **Read first**: Check `.agent/scratchpad.md` for prior context
2. **Track progress**: Note what's done, what's remaining, blockers
3. **Update after**: Write progress to scratchpad before completing iteration

Scratchpad format:
```markdown
# Scratchpad — ralph-it-up-roadmap

## Last Updated
[timestamp]

## Progress
- [x] Completed item
- [ ] Remaining item

## Quality Gate Status
[Updated by validation - see below]

## Decisions Made
- [Decision and rationale]

## Blockers
- [Current blockers]

## Next Steps
- [What to do next iteration]
```

## Quality gates (MUST pass before LOOP_COMPLETE)

Before declaring completion, ALL blocker-level quality gates must pass:

### Output Completeness
- [ ] **all_outputs_exist**: All 6 scopecraft files created
- [ ] **roadmap_has_content**: ROADMAP.md has 50+ lines

### Content Quality
- [ ] **phases_in_range**: ROADMAP.md has 3-5 phases (matches `^## Phase \d`)
- [ ] **stories_have_acceptance_criteria**: 5+ "Acceptance Criteria" sections in EPICS_AND_STORIES.md
- [ ] **risks_documented**: 3+ risk entries with Technical/Product/GTM type in table
- [ ] **metrics_defined**: "North Star Metric" section exists in METRICS_AND_PMF.md
- [ ] **open_questions_populated**: At least 1 `## ` section in OPEN_QUESTIONS.md

### No Placeholders
- [ ] **no_todo_placeholders**: Zero `[TODO]`, `[TBD]`, `[PLACEHOLDER]` markers across all outputs

### Self-Validation Process

Before each iteration ends, mentally run through these checks:

```
1. Count files in scopecraft/ - must be 6
2. Count lines in ROADMAP.md - must be 50+
3. Count "## Phase" headers in ROADMAP.md - must be 3-5
4. Count "Acceptance Criteria" sections in EPICS_AND_STORIES.md - must be 5+
5. Search for [TODO], [TBD], [PLACEHOLDER] - must be 0
6. Verify "North Star Metric" exists in METRICS_AND_PMF.md
7. Verify risk table has 3+ rows with Technical/Product/GTM
8. Verify OPEN_QUESTIONS.md has at least one "## " section
```

If ANY blocker fails, continue iterating. Update scratchpad with:
- Which gates failed
- What needs to be fixed
- Plan for next iteration

## Discovery procedure (do this first)

1) Inventory documents:
   - list PRDs and PRD-like docs in `/docs` (initial + historical)
   - identify architecture decisions (ADRs), constraints, and non-goals
2) Inventory scope sources:
   - open issues / TODOs / backlog lists / "legacy scope" notes
3) Infer current stage:
   - MVP/alpha/beta/early release signals (missing monitoring, limited permissions, minimal onboarding, weak reliability, etc.)

## Convert legacy scope into a backlog model

Normalize every task into:
- Epic
- User story (who/what/why)
- Acceptance criteria (observable, testable)
- Dependencies (tech + org)
- Risk level
- Complexity bucket (S/M/L/XL)

## Build the maturity roadmap (required structure)

Use the templates in `templates/` and produce:

### 1) VISION_AND_STAGE_DEFINITION.md
- Product vision summary (customer + problem + value)
- "Next major stage" definition with completion criteria
- Assumptions + constraints

### 2) ROADMAP.md
- 3–5 phases max
- For each phase:
  - objective (outcome)
  - key deliverables
  - definition of done
  - metrics / KPIs
  - major risks

### 3) EPICS_AND_STORIES.md
Group epics by themes:
- Core value delivery
- Adoption/onboarding
- Reliability/performance
- Security/compliance
- Developer experience / platform maturity
- Monetization/packaging (if applicable)

Each epic must include:
- user-facing intent
- stories with acceptance criteria
- dependencies and sequencing notes

### 4) RISKS_AND_DEPENDENCIES.md
- Technical risks, product risks, GTM risks
- Mitigations and contingency paths
- Dependency map (internal + external)

### 5) METRICS_AND_PMF.md
- North Star metric + supporting metrics
- PMF signals: activation funnel, retention, usage depth
- Instrumentation plan (what must be tracked to call the stage "done")

### 6) OPEN_QUESTIONS.md
- Questions blocking prioritization or delivery
- Proposed experiments or stakeholder asks to resolve them

## Completion promise

When running in orchestrated mode (ralph-orchestrator compatible):
- Iterate until outputs are complete and consistent
- **ALL blocker quality gates must pass**
- Use the completion promise exactly: `LOOP_COMPLETE`
- Improve gaps rather than rewriting everything each cycle

**DO NOT issue LOOP_COMPLETE if any blocker gate fails.**