Macro-phase modes of pair-next (analysis/implementation/review)

[rucka]

Story Statement

As a pair user who doesn't want to know the granular steps
I want macro-phase MODES of pair-next (analysis / implementation / review) that run the corresponding branch of the process
So that the real steps are hidden behind 2–3 facades while granular skills stay invocable (R2.11)

Where: pair-next invocation modes

Epic Context

Parent Epic: pair-next esteso & orchestrators #204
Status: Refined
Priority: P1 (Should-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given pair-next invoked in analysis mode
   When it runs
   Then it chains the analysis-branch steps (brainstorm/refinement family) appropriate to the current board state, without exposing step names unless asked

2. Given implementation mode on a Ready story
   When it runs
   Then the implement branch executes end-to-end; review mode likewise drives the review branch on an open PR

3. Given a user who invokes a granular skill directly
   When the skill runs
   Then behavior is identical to today — macro-phases are pure facades, NOT new skills (D24: no new process steps)

4. Given a process profile with disabled steps
   When a macro-phase runs
   Then disabled steps are skipped inside the phase (consistent with the profile story)

Business Rules

• Macro-phases are MODES of pair-next — zero new skills, zero duplicated logic
• Mode ↔ step mapping lives in the skills-guide/KB, not hardcoded prose in multiple places
• Steps inside a mode still respect macrostates and DoR (control state story)

Edge Cases and Error Handling

• Mode invoked in wrong context (e.g. review mode with no PR): report what's missing, suggest the right mode
• Step inside the phase HALTs: the phase surfaces the HALT as-is (no swallowing)

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Code review completed and approved
• Documentation updated — docs site (apps/website): the 3 modes documented for end users
• CLI (apps/pair-cli) updated where install/update/distribution is touched

Quality Assurance

• One end-to-end session per mode on a fixture project
• Regression: granular skill invocation unchanged

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 (M)
Confidence Level: Medium
Sizing Justification: mode dispatch + step chaining over existing selection engine; confirmed M(3)

Sprint Capacity Validation

Sprint Fit Assessment: yes
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: root/filter + steps/until stories (chaining uses the loop); process-profile story (skip semantics)
Dependent Stories: none

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: transcript comparison — mode session vs equivalent manual step sequence (must match outcomes)
Test Data Requirements: fixture project with items at analysis/implementation/review stages

Notes and Additional Context

Refinement Session Insights: kept P1 — UX sugar over P0 mechanics; delivers R2.11 without growing the skill catalog
Documentation Links: R2.11 · Spec G2 · D24

Technical Analysis

Implementation Approach

Technical Strategy: SKILL.md mode section: mode → ordered step-family mapping resolved against current macrostate; reuse the multi-step loop with an implicit until (phase exit condition); user-facing narration at phase level
Key Components: mode dispatch table; phase exit conditions; narration guidance
Integration Points: selection engine, run loop, process profile

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Facade drift when new steps are added	Medium	Medium	mode table lives next to the skills catalog; authoring checklist item

Task Breakdown

Checklist

• T1 — Mode dispatch table (analysis/implementation/review → step families + exit conditions)
• T2 — Phase execution over the run loop + HALT surfacing
• T3 — Profile-aware skipping inside phases
• T4 — End-to-end sessions + docs site page

Dependency Graph

T1 → T2 → T3 → T4

AC Coverage

Task	AC1	AC2	AC3	AC4
T1	✓	✓
T2	✓	✓	✓
T3				✓
T4	✓	✓	✓	✓