roadmap-scopecraft

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:

# 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
• vision_not_empty: VISION_AND_STAGE_DEFINITION.md has 20+ lines
• roadmap_not_empty: ROADMAP.md has 50+ lines

Content Quality

• phases_in_range: ROADMAP.md has 3-5 phases (matches ^## Phase \d)
• epics_have_stories: EPICS_AND_STORIES.md has 5+ stories (matches ^#### Story)
• stories_have_acceptance_criteria: 5+ "Acceptance Criteria" sections
• risks_documented: 3+ risk entries in table format
• metrics_defined: "North Star Metric" section exists

No Placeholders

• no_todo_placeholders: Zero [TODO], [TBD], [PLACEHOLDER] markers
• no_empty_brackets: Zero empty [ ] template brackets (warning)

Self-Validation Process

Before each iteration ends, mentally run through these checks:

1. Count files in scopecraft/ - must be 6
2. Count "## Phase" headers in ROADMAP.md - must be 3-5
3. Count "#### Story" headers in EPICS_AND_STORIES.md - must be 5+
4. Search for [TODO], [TBD], [PLACEHOLDER] - must be 0
5. Verify "North Star Metric" exists in METRICS_AND_PMF.md
6. Verify risk table has 3+ rows with Technical/Product/GTM

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.