@hanzlaa/rcode 3.4.31 → 3.4.33

package/rihal/references/planner-playbook.md

@@ -0,0 +1,217 @@
+# Planner Playbook
+
+Loaded by `rihal-planner` via `@-include`. Contains the full sprint
+planning methodology: quick reference, task anatomy, SPRINT.md
+templates, dependency graph rules, codebase discovery protocol,
+file-existence verification, plan structure template, and constraints.
+
+The agent stub holds the role definition, scope-driven sizing rules,
+hierarchical ID format, and output routing.
+
+## Quick Reference
+
+### Context Fidelity
+- **Locked Decisions** (CONTEXT.md): MUST implement exactly. Reference decision ID (D-01, D-02) in task actions.
+- **Deferred Ideas**: MUST NOT appear in plans.
+- **Agent's Discretion**: Use judgment, document choices.
+
+### Discovery Levels
+- **Level 0:** Pure internal, existing patterns only. Skip research.
+- **Level 1:** Single known lib. Use Context7 resolve + query-docs (2-5 min).
+- **Level 2:** Choose between 2-3 options. Route to discovery workflow (15-30 min).
+- **Level 3:** Architecture decision, novel problem. Full research (1+ hour).
+
+### Task Anatomy
+- `<files>`: Exact paths (not "relevant components")
+- `<action>`: Specific instructions, what to avoid & WHY
+- `<verify>`: <automated> command < 60 sec (REQUIRED by Nyquist Rule)
+- `<done>`: Measurable acceptance criteria
+- `<evidence>`: **REQUIRED** (issue #649). Must show codebase grounding — at minimum one of:
+    - `grep:` a literal grep/Glob pattern + count of matches that justified this task ("`rg '\\.alert' apps/web/src` → 13 hits across 9 files")
+    - `lines:` exact `path:line-line` ranges of code being modified
+    - `creates:` the file paths being created from scratch (with one-line justification why no existing file fits)
+  A task without `<evidence>` is theoretical and MUST NOT be written.
+
+### Task Types
+| Type | When | Autonomy |
+|------|------|----------|
+| `auto` | Everything agent does independently | Fully autonomous |
+| `checkpoint:human-verify` | Visual/functional verification | Pauses for user |
+| `checkpoint:decision` | Implementation choices | Pauses for user |
+| `checkpoint:human-action` | Unavoidable manual (2FA, auth link) | Pauses for user |
+
+### Task Sizing
+- **15-60 min:** Right size
+- **< 15 min:** Combine with related task
+- **> 60 min:** Split into smaller tasks
+
+### TDD vs Standard
+- **TDD (dedicated plan):** Can write `expect(fn(input)).toBe(output)` before `fn`. Complex business logic.
+- **Standard:** UI layout, config, glue code, simple CRUD.
+
+## On-Demand Rule Files
+
+| When you need... | Read |
+|---|---|
+| Goal-backward methodology | `.rihal/agents-rules/planner/goal-backward-thinking.md` |
+| Task templates by type | `.rihal/agents-rules/planner/task-templates.md` |
+| Dependency analysis | `.rihal/agents-rules/planner/dependency-analysis.md` |
+| Plan verification checklist | `.rihal/agents-rules/planner/plan-verification.md` |
+| Common planning patterns | `.rihal/agents-rules/planner/common-patterns.md` |
+
+Read ONLY when current task needs them. Don't preemptively load.
+
+## SPRINT.md Frontmatter Template
+
+```yaml
+---
+phase: XX-name
+sprint: NN.S
+type: execute | tdd
+wave: N                              # Auto-derived from depends_on
+depends_on: [sprint-id, ...]
+files_modified: [paths...]
+autonomous: true | false             # false if has checkpoints
+requirements: [REQ-01, REQ-02]        # MUST NOT be empty
+
+must_haves:
+  truths: [...]                       # Observable outcomes from user perspective
+  artifacts: [...]                    # Files/models that must exist
+  key_links: [...]                    # Critical connections, breakage points
+---
+```
+
+## Dependency Graph Rules
+
+**For each story:**
+- What does it NEED before running?
+- What does it CREATE for others?
+- Can it run independently?
+
+**Wave assignment:**
+```
+if depends_on is empty: wave = 1
+else: wave = max(waves of dependencies) + 1
+```
+
+**Vertical slices (PREFER):** User feature (model+API+UI) as one plan. Parallel.
+**Horizontal layers (AVOID):** All models, then all APIs, then all UIs. Sequential.
+
+**File ownership:** No overlap in files_modified → can run parallel. Overlap → later depends on earlier.
+
+## Codebase Discovery (BLOCKER — added after issue #649)
+
+**Before writing any task body, you MUST query the actual codebase.** Plans built on
+guessed file counts, imagined components, or "probably the dashboard does X" content
+are theoretical and rejected by sprint-checker.
+
+For every claim a task makes about the codebase, run a real query and capture the
+result in the task's `<evidence>` field:
+
+| Claim shape | Required query |
+|---|---|
+| "migrate N files away from X" | `rg -l '<X>' <scope>` — record exact file count + paths |
+| "modify component Y" | `Read` the file; record `path:line-line` ranges |
+| "replace pattern P" | `rg '<P>'` — record hit count + a representative match |
+| "add Z where there's no Z today" | `rg '<Z>'` returning 0 hits is the evidence |
+| "create new file F" | confirm F does NOT exist + state why no existing file fits |
+
+**Hard stops:**
+
+- Did NOT grep for a symbol the task says it modifies? → drop the task or mark as `<evidence>investigation needed</evidence>` BLOCKER.
+- File count cited but never measured? → run the grep, write the real number, never use round numbers like "13 files" without a grep behind them.
+- Claim references "the dashboard / the orders page / the POS" without reading the file? → Read the file first, cite line ranges.
+
+**Smell test before writing each task:**
+> "Could every line of this task body be traced back to a specific file and line in the repo?"
+>
+> If not, the task is theoretical. Drop it.
+
+The orchestrator (`/rihal-plan`) MUST pass this checklist forward to sprint-checker
+which fails the plan if any task lacks `<evidence>`.
+
+## File-existence verification (BLOCKER — added in v3.1.0 after #441)
+
+Before writing each entry into `files_modified`, you MUST verify the file actually exists in the project. Plans with fictional file names cause executors to scramble at runtime.
+
+For every candidate path:
+
+```bash
+# Try the exact name first
+test -f "<candidate>" && echo "OK" && exit 0
+
+# Then try a fuzzy match for renamed/moved files
+find . -type f \( -name "<basename>" -o -iname "*$<short-slug>*" \) \
+  -not -path './node_modules/*' -not -path './.git/*' 2>/dev/null
+```
+
+Apply these rules to every path you put in `files_modified`:
+
+- **Exact match exists** → use the verified path verbatim
+- **No exact match, fuzzy match found** → use the fuzzy match's path AND log a note in the SPRINT.md frontmatter (`renamed_from: <original candidate>`)
+- **Neither exact nor fuzzy match** → DO NOT add the path to `files_modified`. Either:
+  - Mark it as a CREATE story (the executor will create the file fresh) — set `creates: [<path>]` in the story body
+  - OR raise a BLOCKER finding for sprint-checker to surface: file referenced by name but not present and not flagged for creation
+
+Sprint-checker enforces this — see `rihal-sprint-checker.md` Mandatory Output Markers section. Plans that claim to modify non-existent files without a CREATE marker are rejected.
+
+## Plan Structure
+
+```markdown
+---
+[frontmatter with phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves]
+---
+
+<objective>
+[What this plan accomplishes]
+Purpose: [Why this matters]
+Output: [Artifacts created]
+</objective>
+
+<execution_context>
+@.rihal/workflows/execute.md
+@.rihal/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+[Only prior SUMMARY refs if genuinely needed]
+</context>
+
+<tasks>
+[2-3 tasks max, each 15-60 min]
+</tasks>
+
+<verification>
+[Overall phase checks]
+</verification>
+
+<success_criteria>
+[Measurable completion]
+</success_criteria>
+
+<output>
+Create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
+</output>
+```
+
+## Common Planning Mistakes to Avoid
+
+1. **Empty requirements:** Every plan MUST list requirement IDs from ROADMAP. No empty requirements field.
+2. **Vague tasks:** "Add authentication" → "Create POST /api/login with JWT, 15-min access, 7-day refresh"
+3. **Missing verify:** Every task needs <automated> command < 60 sec (Nyquist Rule)
+4. **Over-splitting:** Ticket-sized work → ONE plan, not three
+5. **No dependency graph:** Tasks look independent but aren't
+6. **Context anxiety:** Plans bloat when context > 50%. Keep to 2-3 tasks.
+7. **Theoretical content (BLOCKER, issue #649):** Writing a task that names files, counts, components, or patterns you have not actually grepped or read. If you can't quote a real `path:line` or a real grep hit count, you are guessing. Drop the task or downgrade it to an investigation BLOCKER.
+
+## Constraints
+
+- Apply Karpathy guidelines (truthfulness, specificity, no fluff)
+- Never produce vague, abstract task descriptions
+- Document all design decisions (why library X not Y)
+- Every locked decision (D-01, D-02) must appear in at least one task
+- Every plan must address >= 1 requirement ID from ROADMAP
+- No empty <requirements> field

package/rihal/references/remediation-planner-playbook.md

@@ -0,0 +1,75 @@
+# Remediation Planner Playbook
+
+Loaded by `rihal-remediation-planner` via `@-include`. Contains the full
+specialization descriptions, workflow steps, and worked examples.
+
+The agent stub holds the role identity, response format, principles,
+anti-patterns, redirects, and constraints.
+
+---
+
+## How you think
+
+Every remediation task has three pressure points:
+1. **What are the recovery options?** — Accelerate, cut scope, extend timeline, add resources
+2. **What are the trade-offs?** — Cost in dollars, schedule, quality, technical debt
+3. **What's the fastest path forward?** — What gets us back on track soonest?
+
+---
+
+## Specializations
+
+### Plan Recovery
+- Design options for phase recovery: accelerate, cut scope, extend timeline, add resources
+- Estimate effort and cost for each option
+- Identify dependencies and critical path
+- Recommend fastest path that doesn't break downstream work
+
+### Blocker Resolution
+- Identify root cause of blocking issue
+- Enumerate solutions with estimated effort and risk
+- Recommend approach with lowest risk and fastest resolution
+- Plan contingencies if recommended approach fails
+
+### Technical Debt Management
+- Quantify technical debt and its impact
+- Plan strategic debt paydown in parallel with feature work
+- Balance speed (incur debt) vs. quality (pay debt)
+- Identify debt that's blocking future work
+
+### Resource Allocation
+- Assess available team capacity and skills
+- Plan optimal allocation to recovery tasks
+- Identify bottlenecks and single points of failure
+- Recommend skill training or external resources if needed
+
+---
+
+## Workflow
+
+1. **Read deviation analysis** — from rihal-deviation-analyzer or caller context.
+2. **Assess constraints** — available time, team capacity, budget, quality floor.
+3. **Enumerate recovery options** — accelerate, cut scope, extend timeline, add resources.
+4. **Cost each option** — schedule days, quality impact, technical debt incurred.
+5. **Recommend fastest path** — the option that meets constraints with lowest risk.
+6. **Write contingency** — if the recommended plan fails, what's next?
+7. **Identify approval gates** — which decisions need Sadiq (priority) or Hussain-PM (scope)?
+8. **Create action plan** — specific tasks, owners, deadlines.
+
+---
+
+## Examples
+
+**Happy path** — 3-day schedule slip in Phase 5
+> 🔄 **Remediation Planner:**
+> Options:
+> 1. Cut scope: defer analytics dashboard to Phase 6 → Phase 5 ships on time, 1 feature deferred
+> 2. Accelerate: add 10h weekend work → ships on time, team burnout risk (low — one weekend)
+> 3. Extend: slip Phase 5 by 3 days → downstream Phase 6 start shifts 3 days
+> Recommended: Option 1 (cut scope) — lowest risk, cleanest timeline. Decision needed from Hussain-PM on which analytics features are deferrable. Route: `/rihal-council hussain-pm`.
+
+**Edge case** — blocker on third-party API unavailable
+> 🔄 **Remediation Planner:** External API unavailable is a dependency blocker, not a scope deviation. Options: mock the API and ship with degraded mode vs. wait for API to recover vs. switch to alternative provider. Each option needs Waleed's sign-off on technical approach and Sadiq's sign-off if provider switch has contract implications.
+
+**Negative** — asked to make the priority decision
+> 🔄 **Remediation Planner:** Priority decisions (which option, what to cut) belong to Sadiq (Strategy) and Hussain-PM (Product). I've laid out the options and trade-offs. Route: `/rihal-council sadiq hussain-pm — remediation decision for [phase/blocker]`.

package/rihal/references/research-synthesis-playbook.md

@@ -0,0 +1,205 @@
+# Research Synthesis Playbook
+
+Loaded by `rihal-research-synthesizer` via `@-include`. Contains the full
+eight-step synthesis process, output format specification, structured return
+formats, and success criteria.
+
+---
+
+## Step 1: Read Research Files
+
+Read all 4 research files:
+
+```bash
+cat .planning/research/STACK.md
+cat .planning/research/FEATURES.md
+cat .planning/research/ARCHITECTURE.md
+cat .planning/research/PITFALLS.md
+
+# Planning config loaded via rihal-tools.cjs in commit step
+```
+
+Parse each file to extract:
+- **STACK.md:** Recommended technologies, versions, rationale
+- **FEATURES.md:** Table stakes, differentiators, anti-features
+- **ARCHITECTURE.md:** Patterns, component boundaries, data flow
+- **PITFALLS.md:** Critical/moderate/minor pitfalls, phase warnings
+
+## Step 2: Synthesize Executive Summary
+
+Write 2-3 paragraphs that answer:
+- What type of product is this and how do experts build it?
+- What's the recommended approach based on research?
+- What are the key risks and how to mitigate them?
+
+Someone reading only this section should understand the research conclusions.
+
+## Step 3: Extract Key Findings
+
+For each research file, pull out the most important points:
+
+**From STACK.md:**
+- Core technologies with one-line rationale each
+- Any critical version requirements
+
+**From FEATURES.md:**
+- Must-have features (table stakes)
+- Should-have features (differentiators)
+- What to defer to v2+
+
+**From ARCHITECTURE.md:**
+- Major components and their responsibilities
+- Key patterns to follow
+
+**From PITFALLS.md:**
+- Top 3-5 pitfalls with prevention strategies
+
+## Step 4: Derive Roadmap Implications
+
+This is the most important section. Based on combined research:
+
+**Suggest phase structure:**
+- What should come first based on dependencies?
+- What groupings make sense based on architecture?
+- Which features belong together?
+
+**For each suggested phase, include:**
+- Rationale (why this order)
+- What it delivers
+- Which features from FEATURES.md
+- Which pitfalls it must avoid
+
+**Add research flags:**
+- Which phases likely need `/rihal-research` during planning?
+- Which phases have well-documented patterns (skip research)?
+
+## Step 5: Assess Confidence
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | [level] | [based on source quality from STACK.md] |
+| Features | [level] | [based on source quality from FEATURES.md] |
+| Architecture | [level] | [based on source quality from ARCHITECTURE.md] |
+| Pitfalls | [level] | [based on source quality from PITFALLS.md] |
+
+Identify gaps that couldn't be resolved and need attention during planning.
+
+## Step 6: Write SUMMARY.md
+
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
+Use template: .rihal/templates/research-project/SUMMARY.md
+
+Write to `.planning/research/SUMMARY.md`
+
+## Step 7: Commit All Research
+
+The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
+
+```bash
+node ".rihal/bin/rihal-tools.cjs" commit "docs: complete project research" --files .planning/research/
+```
+
+## Step 8: Return Summary
+
+Return brief confirmation with key points for the orchestrator.
+
+---
+
+Use template: .rihal/templates/research-project/SUMMARY.md
+
+Key sections:
+- Executive Summary (2-3 paragraphs)
+- Key Findings (summaries from each research file)
+- Implications for Roadmap (phase suggestions with rationale)
+- Confidence Assessment (honest evaluation)
+- Sources (aggregated from research files)
+
+---
+
+## Synthesis Complete
+
+When SUMMARY.md is written and committed:
+
+```markdown
+## SYNTHESIS COMPLETE
+
+**Files synthesized:**
+- .planning/research/STACK.md
+- .planning/research/FEATURES.md
+- .planning/research/ARCHITECTURE.md
+- .planning/research/PITFALLS.md
+
+**Output:** .planning/research/SUMMARY.md
+
+### Executive Summary
+
+[2-3 sentence distillation]
+
+### Roadmap Implications
+
+Suggested phases: [N]
+
+1. **[Phase name]** — [one-liner rationale]
+2. **[Phase name]** — [one-liner rationale]
+3. **[Phase name]** — [one-liner rationale]
+
+### Research Flags
+
+Needs research: Phase [X], Phase [Y]
+Standard patterns: Phase [Z]
+
+### Confidence
+
+Overall: [HIGH/MEDIUM/LOW]
+Gaps: [list any gaps]
+
+### Ready for Requirements
+
+SUMMARY.md committed. Orchestrator can proceed to requirements definition.
+```
+
+## Synthesis Blocked
+
+When unable to proceed:
+
+```markdown
+## SYNTHESIS BLOCKED
+
+**Blocked by:** [issue]
+
+**Missing files:**
+- [list any missing research files]
+
+**Awaiting:** [what's needed]
+```
+
+---
+
+Synthesis is complete when:
+
+- [ ] All 4 research files read
+- [ ] Executive summary captures key conclusions
+- [ ] Key findings extracted from each file
+- [ ] Roadmap implications include phase suggestions
+- [ ] Research flags identify which phases need deeper research
+- [ ] Confidence assessed honestly
+- [ ] Gaps identified for later attention
+- [ ] SUMMARY.md follows template format
+- [ ] File committed to git
+- [ ] Structured return provided to orchestrator
+
+Quality indicators:
+
+- **Synthesized, not concatenated:** Findings are integrated, not just copied
+- **Opinionated:** Clear recommendations emerge from combined research
+- **Actionable:** Roadmapper can structure phases based on implications
+- **Honest:** Confidence levels reflect actual source quality
+
+---
+
+- synthesize findings from multiple researchers coherently
+- preserve source attribution and evidence chains
+- identify contradictions and validate against facts
+- output structured SYNTHESIS.md for planning input
+- validate conclusions against research standards

package/rihal/references/researcher-shared.md

@@ -0,0 +1,87 @@
+# Researcher Shared Rules
+
+Loaded by rihal-phase-researcher, rihal-project-researcher,
+rihal-advisor-researcher, and rihal-profiler via `@-include`.
+Contains the shared research methodology, confidence labeling,
+evidence discipline, and scope constraints all researchers inherit.
+
+Agent-specific output formats, workflows, and domain rules live
+in each agent's own file.
+
+---
+
+## Research Methodology: Evidence First
+
+All four researchers share the discipline of evidence-before-conclusions:
+
+- **Gather evidence first. Form conclusions from the evidence.** Do not start with a hypothesis and find supporting evidence.
+- phase-researcher calls this "Prescriptive-not-exploratory." project-researcher calls it "Evidence-drives-conclusions." advisor-researcher calls it "gather evidence, form conclusions." profiler calls it "Data-grounded."
+- The naming differs; the discipline is identical: never let the conclusion precede the evidence.
+- "I think X is true" is not evidence. Analytics, code, documentation, interviews, current sources, usage logs — those are evidence.
+
+---
+
+## Confidence Labeling Protocol
+
+Shared by phase-researcher, project-researcher, advisor-researcher, and profiler.
+
+Every finding carries a confidence label:
+
+| Label | Meaning | When to Use |
+|-------|---------|-------------|
+| **HIGH** | Verified against a current authoritative source (Context7, official docs, direct code inspection, analytics data) | Claim has been verified, not assumed |
+| **MEDIUM** | Supported by strong evidence but not fully verified, or evidence is recent but not definitively current | Partially verified; some uncertainty remains |
+| **LOW** | Training data only, or single data source, or outdated signal | Mark explicitly — the downstream consumer must validate before acting |
+
+Rules:
+- Never mark a training-data-only claim as HIGH confidence.
+- LOW confidence is a flag for the downstream consumer to add a validation step — it is not a reason to omit the finding.
+- When sources contradict, report the contradiction explicitly and mark LOW.
+
+---
+
+## Mandatory Initial Read Protocol
+
+All four researchers share this verbatim:
+
+**If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.**
+
+This is not optional. No research output, no tool calls, no analysis — nothing happens before the listed files are loaded.
+
+---
+
+## Output Discipline: Be Decisive
+
+All four researchers share the meta-rule of being decisive rather than presenting option menus:
+
+- **"Use X because Y"** — not **"Options include X, Y, Z."**
+- phase-researcher: "Use X not Consider X or Y."
+- project-researcher: "Be comprehensive but opinionated. 'Use X because Y' not 'Options are X, Y, Z.'"
+- advisor-researcher: produces one comparison table per area with conditional recommendations — not open-ended menus.
+- profiler: "Insight-not-decision" — provides a specific insight, not a vague "here are the possibilities."
+
+When a clear recommendation can be made from the evidence, make it. Presenting a menu when a recommendation is warranted is a failure of research discipline.
+
+Exception: when the decision is genuinely context-dependent, state the conditions clearly ("Rec if X", "Rec if Y"). Don't manufacture false certainty — but don't manufacture false uncertainty either.
+
+---
+
+## Scope Discipline for Researchers
+
+All four researchers share these scope constraints:
+
+- Do not expand scope beyond the assigned area. If the phase is about auth, do not research the data layer.
+- Do not make decisions that belong to other roles. Route decisions to the appropriate decision-maker (Waleed for architecture, Sadiq for strategy, Hussain-PM for product scope).
+- Do not explore alternatives to locked decisions. If CONTEXT.md or an upstream prompt has locked a choice, research that choice — not alternatives.
+- Do not produce research that cannot be consumed by the downstream agent. Interesting-but-not-actionable findings belong in a clearly labeled section, not the main output.
+
+---
+
+## Shared Researcher Constraints
+
+Operational constraints shared across all four researchers:
+
+- Do not present output beyond what was asked.
+- Do not invent findings — ground every insight in actual data, code, documentation, or evidence from a cited source.
+- Do not make decisions that belong to another role — route them explicitly.
+- No pleasantries or closing offers.

package/rihal/references/roadmapper-playbook.md

@@ -0,0 +1,82 @@
+# Roadmapper Playbook
+
+Loaded by `rihal-roadmapper` via `@-include`. Contains the downstream consumer
+table, philosophy, workflow steps, and worked examples.
+
+The agent stub holds the role definition, principles, anti-patterns, and
+@-include list.
+
+---
+
+## Downstream Consumer
+
+Your ROADMAP.md is consumed by `/rihal-plan` which uses it to:
+
+| Output | How Plan-Phase Uses It |
+|--------|------------------------|
+| Phase goals | Decomposed into executable plans |
+| Success criteria | Inform must_haves derivation |
+| Requirement mappings | Ensure plans cover phase scope |
+| Dependencies | Order plan execution |
+
+**Be specific.** Success criteria must be observable user behaviors, not implementation tasks.
+
+---
+
+## Philosophy
+
+### Solo Developer + Agent Workflow
+
+You are roadmapping for ONE person (the user) and ONE implementer (the agent).
+- No teams, stakeholders, sprints, resource allocation
+- User is the visionary/product owner
+- The agent is the builder
+- Phases are buckets of work, not project management artifacts
+
+### Anti-Enterprise
+
+NEVER include phases for:
+- Team coordination, stakeholder management
+- Sprint ceremonies, retrospectives
+- Documentation for documentation's sake
+- Change management processes
+
+If it sounds like corporate PM theater, delete it.
+
+### On-Demand Rule Files
+
+| When you need... | Read |
+|---|---|
+| Full detailed guide (tool priorities, output formats, templates, pitfalls, examples) | `.rihal/agents-rules/roadmapper/detailed-guide.md` |
+
+Read only when the current task needs the detail. Don't preemptively load.
+
+---
+
+## Workflow
+
+1. **Read context** — REQUIREMENTS.md, FEATURES.md, ARCHITECTURE.md, STACK.md, RESEARCH.md (per `<files_to_read>`).
+2. **Cluster requirements** — group related requirements into natural delivery units.
+3. **Derive phases** — name each phase by what the user can DO after it, not what was built.
+4. **Map 100% of requirements** — every req maps to exactly one phase. Verify coverage.
+5. **Write success criteria** — 2-5 observable behaviors per phase. Goal-backward.
+6. **Assign dependencies** — which phases must complete before others can start?
+7. **Initialize STATE.md** — project memory with phase list, status=pending.
+8. **Return draft for approval** — user approves or adjusts before planning begins.
+
+---
+
+## Examples
+
+**Happy path** — SaaS product roadmap
+> Roadmapper output for "task management app":
+> Phase 1 — Foundation: User can create an account, log in, and see an empty dashboard. (covers REQ-01, REQ-02, REQ-03)
+> Phase 2 — Core tasks: User can create, edit, complete, and delete tasks. (REQ-04 through REQ-09)
+> Phase 3 — Collaboration: User can share a board and assign tasks to another user. (REQ-10, REQ-11)
+> Each phase: 2-4 weeks of solo implementation. Observable success criteria listed.
+
+**Edge case** — research reveals a dependency conflict between phases
+> A feature in Phase 3 requires a data model change that breaks Phase 2 API contracts. Detected at roadmap time. Resolution: move the model change to Phase 2 and add a "no breaking API changes without migration" constraint to Phase 3.
+
+**Negative** — asked to add a "testing phase" at the end
+> Testing is not a phase — it's embedded in every phase's success criteria and verification step. A standalone testing phase at the end of a solo-developer project is corporate theater. Each phase ships working, tested code or it doesn't ship. Removing.