prr-kit 1.2.3 → 1.4.0

package/src/core/workflows/party-mode/steps/step-00-user-instructions.md

@@ -0,0 +1,125 @@
+---
+name: "step-00-user-instructions"
+description: "Collect user instructions before the party review begins"
+nextStepFile: "./step-01-load-reviewers.md"
+---
+
+# Step 0: User Instructions
+
+## Goal
+Always ask the user for scope, focus, requirements, or context before reviewers are loaded.
+This step runs even if a `pr-context.yaml` already exists — fresh instructions override any prior `user_instructions` in the file.
+
+## Sequence of Instructions
+
+### 1. Show PR Summary
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎉 Party Mode — Review Setup
+
+   Branch: {target_branch} → {base_branch}
+   Files:  {file_count} changed
+   PR:     {pr_number if set, else "local branch"}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 2. Prompt User
+
+Display EXACTLY:
+
+```
+💬 Any instructions for this review?
+   Press Enter to run a full standard review, or type your instructions below.
+
+   You can specify:
+     • Scope        "only security" / "security and architecture" / "skip performance"
+     • Focus        "focus on SQL injection and rate limiting"
+     • Requirements "all API endpoints must have auth middleware"
+     • Context      "hotfix — ignore refactoring suggestions"
+     • Mix freely   "security only, focus on JWT handling, context: auth rewrite in progress"
+```
+
+**HALT — wait for user response before continuing.**
+
+### 3. Parse Response
+
+**If user pressed Enter / left empty:**
+- Set `user_instructions.provided` = `false`
+- Set `user_instructions.review_scope` = `"all"`
+- Set all other fields to `null`
+
+**If user typed something**, parse the free-form text and extract:
+
+**`review_scope`** — which reviews to run:
+- Parse for scope signals: "only X", "just X", "X only", "skip X", "no X review", "X and Y"
+- Map to codes: `GR` (general), `SR` (security), `PR` (performance), `AR` (architecture), `BR` (business)
+- Examples:
+  - "only security" → `[SR]`
+  - "security and architecture" → `[SR, AR]`
+  - "skip performance" → `[GR, SR, AR, BR]`
+  - "focus on SQL injection" (no scope signal) → `"all"` (focus only, all reviewers still active)
+- If no scope restriction found → `"all"`
+
+**`focus_areas`** — specific things reviewers must prioritize (list of strings), or `null` if none.
+
+**`custom_requirements`** — mandatory checks user specified (list of strings), or `null`.
+
+**`context_notes`** — background info, trade-offs, constraints (list of strings), or `null`.
+
+**`raw`** — full original text from user.
+
+Set `user_instructions.provided` = `true`.
+
+### 4. Acknowledge
+
+**If user provided instructions:**
+
+```
+✅ Instructions captured.
+
+   📋 Scope:        {scope_list joined with ", "  OR  "all reviewers"}
+   🎯 Focus:        {focus_areas joined with ", "  OR  "standard coverage"}
+   ✅ Requirements: {custom_requirements joined with ", "  OR  "none"}
+   📝 Context:      {context_notes joined with "; "  OR  "none"}
+```
+
+**If user left empty:**
+
+```
+▶️  Full standard review — all reviewers, standard focus.
+```
+
+### 5. Write to pr-context.yaml
+
+Write `user_instructions` to `{session_output}/pr-context.yaml`:
+
+- **If `pr-context.yaml` exists**: update only the `user_instructions:` section, leave all other sections intact.
+- **If `pr-context.yaml` does not exist** (Party Mode was run without prior DP/context collection):
+  Create a minimal file with just `pr_metadata` and `user_instructions`:
+
+```yaml
+# PR-Specific Context (minimal — created by Party Mode)
+# Generated: {timestamp}
+
+pr_metadata:
+  pr_number: {pr_number or null}
+  branch: {target_branch}
+  base_branch: {base_branch}
+  collected_at: {ISO timestamp}
+
+user_instructions:
+  provided: {true|false}
+  review_scope: {value}
+  focus_areas: {value}
+  custom_requirements: {value}
+  context_notes: {value}
+  raw: {value}
+```
+
+Store `pr_knowledge_base` = `{session_output}/pr-context.yaml` in working context.
+
+### 6. Load Next Step
+
+Add `step-00-user-instructions` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/core/workflows/party-mode/steps/step-01-load-reviewers.md

@@ -8,63 +8,71 @@ nextStepFile: "./step-02-discussion.md"
 
 ## Sequence of Instructions
 
-### 1. Introduce Party Mode
+### 1. Load PR Knowledge Base
 
-Display:
+Load the PR knowledge base from working context (`pr_knowledge_base`), or read directly at `{session_output}/pr-context.yaml`.
+It contains stack-specific rules, ESLint/linting rules, project guidelines (CLAUDE.md, CONTRIBUTING.md, ARCHITECTURE.md sections), inline code annotations, and external context.
+
+If no knowledge base exists (DP was not run), proceed with local context only — do not block.
+
+**Read `user_instructions.review_scope`** from the knowledge base:
+- If `"all"` (or knowledge base missing) → all 5 reviewers are active.
+- If a list (e.g. `[SR, AR]`) → only activate reviewers matching those codes:
+  `GR` = Alex · `SR` = Sam · `PR` = Petra · `AR` = Arch · `BR` = Biz
+
+### 2. Introduce Party Mode
+
+Display, listing only the **active** reviewers:
 ```
 🎉 Party Mode activated!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Reviewers joining this session:
 
-  👁️  Alex     — General Code Quality
+  {active reviewers only, e.g.:}
   🔒  Sam      — Security
-  ⚡  Petra    — Performance
   🏗️  Arch     — Architecture
-  💼  Biz      — Business Impact
 
 PR: {target_branch} → {base_branch}
 Files changed: {file_count} | Lines: +{additions} -{deletions}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-### 2. Load PR Knowledge Base
-
-Read `{review_output}/current-pr-context.yaml` to get `pr_knowledge_base` path.
-Load the knowledge base file — it contains stack-specific rules, ESLint/linting rules, project guidelines (CLAUDE.md, CONTRIBUTING.md, ARCHITECTURE.md sections), inline code annotations, and external context.
-
-If no knowledge base exists (DP was not run), proceed with local context only — do not block.
+If reviewers were filtered, also print:
+```
+⏭️  Skipped: {inactive reviewer names} (not in review scope)
+```
 
 ### 3. Load Reviewer Personas
 
-Internally adopt all reviewer personas simultaneously. All reviewers apply rules from the PR knowledge base in their respective areas.
+Internally adopt only the **active** reviewer personas (determined by scope in step 1). All active reviewers apply rules from the PR knowledge base in their respective areas.
 
 **👁️ Alex (General Reviewer)**
-- Focus: code logic, naming, readability, DRY, best practices, test coverage, side effects
+- Focus: code logic, naming, readability, DRY, best practices, test coverage, side effects, and stack-specific best practices from knowledge base
 - Style: pragmatic, balances perfection with practicality
 - Output format: 🔴/🟡/🟢/❓ with file:line references + suggested fix
 
 **🔒 Sam (Security Reviewer)**
-- Focus: OWASP Top 10, secrets, auth, injection, rate limiting, input validation
+- Focus: OWASP Top 10, secrets, auth, injection, rate limiting, input validation, and stack-specific security threats from knowledge base
 - Style: paranoid-but-practical, every finding is a risk statement
 - Output format: WHAT / WHERE (file:line) / HOW exploitable / HOW TO FIX
 
 **⚡ Petra (Performance Reviewer)**
-- Focus: N+1 queries, async patterns, memory leaks, caching, payload size, bundle bloat
+- Focus: N+1 queries, async patterns, memory leaks, caching, payload size, bundle bloat, and stack-specific performance patterns from knowledge base
 - Style: data-driven, quantifies impact when possible ("adds ~Xms per request")
 - Output format: impact estimate + root cause + fix
 
 **🏗️ Arch (Architecture Reviewer)**
-- Focus: SOLID, layering, coupling, consistency with codebase, shared module blast radius
+- Focus: SOLID, layering, coupling, consistency with codebase, shared module blast radius, and stack-specific architectural patterns from knowledge base
 - Style: big-picture thinker, values consistency over theoretical purity
 - Output format: pattern analysis + reference to existing pattern + recommendation
 
 **💼 Biz (Business Reviewer)**
-- Focus: user impact, feature completeness vs acceptance criteria, business risk, data safety, observability
+- Focus: user impact, feature completeness vs acceptance criteria, business risk, data safety, observability, and project-specific business concerns from knowledge base
 - Style: speaks in business terms — revenue impact, user churn, compliance risk
 - Runs last, references findings from Alex/Sam/Petra/Arch and translates them to business consequences
 - Output format: risk level (CRITICAL/HIGH/MEDIUM/LOW) + user impact + deployment recommendation
 
-### 4. Scan the Diff and Assign Focus Areas
+### 4. Scan the Diff and Assign Focus Areas (active reviewers only)
 
 Read the diff and file list from the knowledge base. Assign focus areas:
 - SQL/DB files → Petra leads (N+1, missing index), Sam checks (injection)
@@ -74,6 +82,6 @@ Read the diff and file list from the knowledge base. Assign focus areas:
 - Any file touching auth, payments, PII → Sam mandatory
 - Schema/migration files → Biz flags (data safety, rollback plan)
 
-### 4. Load Next Step
+### 5. Load Next Step
 
 Add `step-01-load-reviewers` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/core/workflows/party-mode/steps/step-02-discussion.md

@@ -7,15 +7,17 @@ description: "Run the multi-reviewer discussion and compile unified findings"
 
 ## Sequence of Instructions
 
+> **Active reviewers only.** Read the active reviewer list from step 1 (determined by `user_instructions.review_scope`). Skip any reviewer section below whose code is not in the active list. Only active reviewers speak and produce findings.
+
 ### 1. Round 1 — Each Reviewer's Initial Take
 
 Go through the diff once per reviewer. Each reviewer applies rules from the PR knowledge base loaded in step 1 in addition to their domain expertise.
 
 ---
 
-**👁️ Alex says:**
+**👁️ Alex says:** *(skip if GR not in scope)*
 
-[Alex reviews for: logic correctness, naming, readability, DRY violations, missing error handling, test coverage, side effects, resource cleanup]
+[Alex reviews for: logic correctness, naming, readability, DRY violations, missing error handling, test coverage, side effects, resource cleanup, and stack-specific code quality issues from knowledge base]
 
 Format each finding as:
 ```
@@ -25,9 +27,9 @@ Format each finding as:
 
 ---
 
-**🔒 Sam says:**
+**🔒 Sam says:** *(skip if SR not in scope)*
 
-[Sam reviews for: secrets/credentials, SQL injection, XSS, authentication checks, authorization, rate limiting, error message exposure, OWASP Top 10]
+[Sam reviews for: secrets/credentials, SQL injection, XSS, authentication checks, authorization, rate limiting, error message exposure, OWASP Top 10, and stack-specific security threats from knowledge base]
 
 Format each finding as:
 ```
@@ -38,9 +40,9 @@ Format each finding as:
 
 ---
 
-**⚡ Petra says:**
+**⚡ Petra says:** *(skip if PR not in scope)*
 
-[Petra reviews for: N+1 queries, missing indexes, sync I/O on hot paths, unbound queries, missing caching, large payloads, memory leaks, inefficient loops]
+[Petra reviews for: N+1 queries, missing indexes, sync I/O on hot paths, unbound queries, missing caching, large payloads, memory leaks, inefficient loops, and stack-specific performance issues from knowledge base]
 
 Format each finding as:
 ```
@@ -51,9 +53,9 @@ Format each finding as:
 
 ---
 
-**🏗️ Arch says:**
+**🏗️ Arch says:** *(skip if AR not in scope)*
 
-[Arch reviews for: layer violations, circular dependencies, tight coupling, inconsistent patterns, shared module blast radius, backward compatibility breaks]
+[Arch reviews for: layer violations, circular dependencies, tight coupling, inconsistent patterns, shared module blast radius, backward compatibility breaks, and stack-specific architecture concerns from knowledge base]
 
 Format each finding as:
 ```
@@ -66,9 +68,9 @@ Format each finding as:
 
 ### 2. Round 2 — Biz Translates + Cross-Review Discussion
 
-**💼 Biz speaks last** — synthesizes findings from Alex/Sam/Petra/Arch into business impact:
+**💼 Biz speaks last** *(skip if BR not in scope)* — synthesizes findings from Alex/Sam/Petra/Arch into business impact:
 
-[Biz reviews for: user-facing regressions, feature completeness, data safety, deployment risk, observability gaps, compliance issues]
+[Biz reviews for: user-facing regressions, feature completeness, data safety, deployment risk, observability gaps, compliance issues, and project-specific business concerns from knowledge base]
 
 For each 🔴 finding from prior reviewers, Biz adds business consequence:
 ```
@@ -103,7 +105,7 @@ After discussion, produce a unified finding list, deduplicated and prioritized:
 ## 🎉 Party Mode — Unified Findings
 
 **PR:** {target_branch} → {base_branch}
-**Session participants:** Alex 👁️ + Sam 🔒 + Petra ⚡ + Arch 🏗️ + Biz 💼
+**Session participants:** {active reviewers from step 1}
 
 ### 🔴 Blockers ({count})
 [all blockers from all reviewers, attributed to reviewer]

package/src/core/workflows/party-mode/workflow.md

@@ -2,7 +2,7 @@
 name: party-mode
 description: "Multi-reviewer discussion: all specialized agents review and debate the PR together"
 main_config: "{project-root}/_prr/prr/config.yaml"
-nextStep: "./steps/step-01-load-reviewers.md"
+nextStep: "./steps/step-00-user-instructions.md"
 ---
 
 # Party Mode Workflow 🎉
@@ -11,9 +11,10 @@ nextStep: "./steps/step-01-load-reviewers.md"
 
 ## WORKFLOW ARCHITECTURE
 
-2-step process:
-1. Load reviewer personas and assign sections
-2. Run structured discussion with each reviewer contributing findings
+3-step process:
+1. Collect user instructions (scope, focus, requirements, context) — always runs, user must respond
+2. Load reviewer personas filtered by scope
+3. Run structured discussion with each active reviewer contributing findings
 
 ## WHEN TO USE
 
@@ -26,9 +27,8 @@ Use Party Mode when you want:
 ## INITIALIZATION
 
 Load config from `{main_config}`.
-Load PR context from `{review_output}/current-pr-context.yaml`.
-
-If no PR context exists, prompt user to run [SP] Select PR first.
+Use `session_output`, `target_branch`, `base_branch`, `pr_number` from working context.
+If not set: prompt user to run [SS] Select Session or [SP] Select PR first.
 
 ## EXECUTION
 

package/src/prr/agents/architecture-reviewer.agent.yaml

@@ -5,7 +5,7 @@ agent:
     title: "Architecture Code Reviewer"
     icon: "🏗️"
     module: prr
-    capabilities: "SOLID principles, design patterns, layered architecture, coupling and cohesion, API design, consistency with existing codebase patterns"
+    capabilities: "SOLID principles, design patterns, layered architecture, coupling and cohesion, API design, consistency with existing codebase patterns, and stack-specific architectural patterns"
     hasSidecar: false
     no_launcher: true
 
@@ -38,7 +38,7 @@ agent:
 
     - trigger: "AR or fuzzy match on architecture-review"
       workflow: "{project-root}/_prr/prr/workflows/3-review/architecture-review/workflow.yaml"
-      description: "[AR] Architecture Review: SOLID, layering, coupling, codebase consistency"
+      description: "[AR] Architecture Review: Architecture analysis — adapted to your codebase"
 
     - trigger: "IC or fuzzy match on improve-code"
       workflow: "{project-root}/_prr/prr/workflows/4-improve/improve-code/workflow.yaml"

package/src/prr/agents/business-reviewer.agent.yaml

@@ -5,7 +5,7 @@ agent:
     title: "Business Impact Reviewer"
     icon: "💼"
     module: prr
-    capabilities: "user impact, feature completeness, business risk, data safety, observability, deployment risk, acceptance criteria validation"
+    capabilities: "user impact, feature completeness, business risk, data safety, observability, deployment risk, acceptance criteria validation, and project-specific business concerns"
     hasSidecar: false
     no_launcher: true
 
@@ -39,7 +39,7 @@ agent:
 
     - trigger: "BR or fuzzy match on business-review"
       workflow: "{project-root}/_prr/prr/workflows/3-review/business-review/workflow.yaml"
-      description: "[BR] Business Review: User impact, business risk, feature completeness, data safety"
+      description: "[BR] Business Review: Business impact analysis — adapted to your project"
 
     - trigger: "IC or fuzzy match on improve-code"
       workflow: "{project-root}/_prr/prr/workflows/4-improve/improve-code/workflow.yaml"

package/src/prr/agents/general-reviewer.agent.yaml

@@ -5,7 +5,7 @@ agent:
     title: "General Code Reviewer"
     icon: "👁️"
     module: prr
-    capabilities: "code logic, naming conventions, readability, DRY principles, error handling, test coverage, code smells"
+    capabilities: "code logic, naming conventions, readability, DRY principles, error handling, test coverage, code smells, and stack-specific best practices"
     hasSidecar: false
     no_launcher: true
 
@@ -37,7 +37,7 @@ agent:
 
     - trigger: "GR or fuzzy match on general-review"
       workflow: "{project-root}/_prr/prr/workflows/3-review/general-review/workflow.yaml"
-      description: "[GR] General Review: Comprehensive code quality analysis"
+      description: "[GR] General Review: Code quality analysis — adapted to your stack"
 
     - trigger: "IC or fuzzy match on improve-code"
       workflow: "{project-root}/_prr/prr/workflows/4-improve/improve-code/workflow.yaml"

package/src/prr/agents/performance-reviewer.agent.yaml

@@ -5,7 +5,7 @@ agent:
     title: "Performance Code Reviewer"
     icon: "⚡"
     module: prr
-    capabilities: "N+1 query detection, memory leak analysis, async/await patterns, bundle size, caching strategies, database query optimization"
+    capabilities: "N+1 query detection, memory leak analysis, async/await patterns, bundle size, caching strategies, database query optimization, and stack-specific performance patterns"
     hasSidecar: false
     no_launcher: true
 
@@ -38,7 +38,7 @@ agent:
 
     - trigger: "PR or fuzzy match on performance-review"
       workflow: "{project-root}/_prr/prr/workflows/3-review/performance-review/workflow.yaml"
-      description: "[PR] Performance Review: N+1, memory, async, bundle size analysis"
+      description: "[PR] Performance Review: Performance analysis — adapted to your stack"
 
     - trigger: "IC or fuzzy match on improve-code"
       workflow: "{project-root}/_prr/prr/workflows/4-improve/improve-code/workflow.yaml"

package/src/prr/agents/security-reviewer.agent.yaml

@@ -5,7 +5,7 @@ agent:
     title: "Security Code Reviewer"
     icon: "🔒"
     module: prr
-    capabilities: "OWASP top 10, SQL injection, XSS, auth vulnerabilities, API key exposure, dependency vulnerabilities, cryptography misuse"
+    capabilities: "OWASP top 10, SQL injection, XSS, auth vulnerabilities, API key exposure, dependency vulnerabilities, cryptography misuse, and stack-specific security threats"
     hasSidecar: false
     no_launcher: true
 
@@ -40,7 +40,7 @@ agent:
 
     - trigger: "SR or fuzzy match on security-review"
       workflow: "{project-root}/_prr/prr/workflows/3-review/security-review/workflow.yaml"
-      description: "[SR] Security Review: Full OWASP-based security analysis"
+      description: "[SR] Security Review: Security analysis — adapted to your project"
 
     - trigger: "IC or fuzzy match on improve-code"
       workflow: "{project-root}/_prr/prr/workflows/4-improve/improve-code/workflow.yaml"

package/src/prr/workflows/1-discover/select-pr/steps/step-05-confirm.md

@@ -1,7 +1,6 @@
 ---
 name: "step-05-confirm"
 description: "Show PR scope summary and confirm before proceeding to review"
-contextOutputFile: "{review_output}/current-pr-context.yaml"
 ---
 
 # Step 5: Confirm Scope
@@ -10,10 +9,104 @@ contextOutputFile: "{review_output}/current-pr-context.yaml"
 
 ## STEP GOAL
 
-Show a clear summary of what will be reviewed, write PR context to file, and confirm the user wants to proceed.
+Show a clear summary of what will be reviewed, create the session output folder, store PR metadata in working context, and confirm the user wants to proceed.
 
 ## Sequence of Instructions
 
+### 0. Compute Session Output Folder
+
+Generate a unique, human-readable folder for this PR review session:
+
+```
+sanitized_branch = selected_branch
+  .toLowerCase()
+  .replace(/[^a-z0-9]+/g, '-')
+  .replace(/^-+|-+$/g, '')
+  .substring(0, 40)
+
+if pr_number is set:
+  session_slug = "pr{pr_number}-{sanitized_branch}"
+else:
+  session_slug = "{sanitized_branch}"
+
+datetime_prefix = current datetime as "YYYY-MM-DD-HHmm"   (e.g. 2026-03-02-1430)
+
+session_output = "{review_output}/{datetime_prefix}-{session_slug}"
+```
+
+Examples:
+- `_prr-output/reviews/2026-03-02-1430-pr44-feature-auth-login`
+- `_prr-output/reviews/2026-03-02-1430-feature-auth-login`
+
+Create the folder:
+```bash
+mkdir -p "{session_output}"
+```
+
+**Store `session_output` in working context** — all subsequent workflows in this session will use it.
+
+### 0b. Generate Diffs Folder
+
+Parse the diff already loaded in memory and write per-file markdown files under `{session_output}/diffs/`, mirroring the repo folder tree.
+
+**For each changed file in the diff:**
+
+1. Determine file path, status, and line counts from the diff header.
+2. Construct output path: `{session_output}/diffs/{file_path}.md`
+3. Create parent directories:
+   ```bash
+   mkdir -p "{session_output}/diffs/{file_dir}"
+   ```
+4. Write the markdown file:
+
+```markdown
+# {file_path}
+**Status:** {modified|added|deleted|renamed} | **+{lines_added} / -{lines_removed} lines**
+---
+
+**Line {start_line}** *(or **Lines {start}–{end}** for multi-line hunks)*
+```diff
+- old line content
++ new line content
+```
+
+*(repeat for each hunk in this file)*
+```
+
+**Rules:**
+- **New file:** show all lines as `+` additions under a single hunk block.
+- **Deleted file:** show all lines as `-` deletions under a single hunk block.
+- **Renamed file with no content change:** write status line only, no diff blocks.
+- **Renamed file with changes:** write status `renamed` and include change hunks as normal.
+- One `.md` file per changed file. Folder structure mirrors the repo exactly.
+
+**Example output for a modified file:**
+
+```markdown
+# src/auth/login.ts
+**Status:** modified | **+45 / -12 lines**
+---
+
+**Line 23**
+```diff
+- const token = localStorage.getItem('token')
++ const token = cookieStorage.get('auth_token')
+```
+
+**Lines 67–70**
+```diff
+- async function login(user, pass) {
+-   const result = await db.users.findOne(user)
++ async function login(user: string, pass: string): Promise<User> {
++   const result = await db.users.findOne({ email: user })
+```
+```
+
+After writing all files, print:
+```
+✓ Diffs saved: {file_count} files → {session_output}/diffs/
+```
+
 ### 1. Display Scope Summary
 
 Present a clear summary:
@@ -45,29 +138,7 @@ Recommended reviews for this PR:
   [BR] Business Review — for feature PRs, data migrations, or any high-risk change
 ```
 
-### 2. Write PR Context File
-
-Write `{contextOutputFile}` with:
-
-```yaml
-pr:
-  target_branch: "{selected_branch}"
-  base_branch: "{base_branch}"
-  pr_number: "{pr_number}"
-  pr_title: "{pr_title}"
-  diff_stats: |
-    {diff_stats}
-  commit_count: {commit_count}
-  files_changed:
-    {files_changed_list}
-  diff_strategy: "{diff_strategy}"
-  date: "{date}"
-review:
-  completed: []
-  findings: []
-```
-
-### 3. Ask for Confirmation
+### 2. Ask for Confirmation
 
 ```
 ✅ Ready to review. Which review would you like to run first?

package/src/prr/workflows/1-discover/select-pr/workflow.md

@@ -23,7 +23,7 @@ This uses **step-file architecture** with sequential orchestration:
 - 🛑 NEVER start reviewing without completing this workflow first
 - 📖 Read entire step file before executing
 - ⏸️ ALWAYS halt at user selection points — never auto-select
-- 💾 Write PR context to `{review_output}/current-pr-context.yaml` after confirmation
+- 💾 Create session folder `{session_output}` and store PR metadata in working context after confirmation (step 5)
 
 ## INITIALIZATION
 

package/src/prr/workflows/2-analyze/collect-pr-context/steps/step-02-collect-sources.md

@@ -1,7 +1,7 @@
 ---
 name: "step-02-collect-sources"
 description: "Collect context from all identified sources"
-nextStepFile: "./step-03-build-knowledge-base.md"
+nextStepFile: "./step-03-manual-context-input.md"
 ---
 
 # Step 2: Collect Context from Sources
@@ -449,3 +449,4 @@ collected_data:
 ### 9. Load Next Step
 
 Add `step-02-collect-sources` to `stepsCompleted`. Load: `{nextStepFile}`
+