prr-kit 1.0.0

package/src/prr/workflows/3-review/architecture-review/workflow.yaml

@@ -0,0 +1,18 @@
+name: architecture-review
+description: "Architecture-focused review: SOLID principles, layering, coupling, codebase consistency"
+author: "PR Review Framework"
+
+config_source: "{project-root}/_prr/prr/config.yaml"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+target_repo: "{config_source}:target_repo"
+review_output: "{config_source}:review_output"
+date: system-generated
+
+installed_path: "{project-root}/_prr/prr/workflows/3-review/architecture-review"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+
+pr_context: "{review_output}/current-pr-context.yaml"
+project_context: "{review_output}/project-context.yaml"
+output_file: "{review_output}/architecture-review-{date}.md"

package/src/prr/workflows/3-review/general-review/checklist.md

@@ -0,0 +1,23 @@
+---
+title: "General Review Completion Checklist"
+validation-target: "General review output file"
+---
+
+# General Review Checklist
+
+## Coverage
+- [ ] All changed files reviewed (or all chunks if large diff)
+- [ ] Logic and correctness checked for each changed function
+- [ ] Error handling reviewed
+- [ ] Test coverage assessed
+
+## Finding Quality
+- [ ] Every finding has: file path + line/function reference
+- [ ] Every finding has: severity level (🔴/🟡/🟢)
+- [ ] Every finding has: suggested fix or improvement
+- [ ] No vague findings ("this code is bad" — must specify why and what to do)
+
+## Output
+- [ ] Findings written to `{review_output}/general-review-{date}.md`
+- [ ] PR context updated with `general-review` in completed list
+- [ ] At least one positive observation included (balanced review)

package/src/prr/workflows/3-review/general-review/instructions.xml

@@ -0,0 +1,68 @@
+<workflow>
+  <critical>Workflow engine rules: {project-root}/_prr/core/tasks/workflow.xml</critical>
+  <critical>Communicate all responses in {communication_language}</critical>
+  <critical>Load PR context from {pr_context} before starting review</critical>
+  <critical>Every finding MUST include: file path + line/function reference + severity + suggested fix</critical>
+
+  <step n="1" goal="Load PR context and diff">
+    <check if="{pr_context} does not exist">
+      <output>❌ No PR selected. Please run [SP] Select PR first.</output>
+      <stop/>
+    </check>
+
+    <action>Read {pr_context} to get: target_branch, base_branch, diff_strategy, files_changed</action>
+    <action>Run: git diff {base_branch}...{target_branch} in {target_repo}</action>
+    <action>Note diff_strategy: if 'chunked', process file by file</action>
+
+    <output>🔍 Starting General Code Review
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PR: {target_branch} → {base_branch}
+Strategy: {diff_strategy}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
+  </step>
+
+  <step n="2" goal="Review code logic and correctness">
+    <action>For each changed file (or chunk if diff_strategy=chunked):</action>
+    <check-list id="logic">
+      <item>Logical errors: conditions, edge cases, off-by-one errors</item>
+      <item>Null/undefined handling: are all possible null states handled?</item>
+      <item>Error handling: are errors caught and handled appropriately?</item>
+      <item>Return values: are return paths complete and correct?</item>
+      <item>Data validation: is user input properly validated?</item>
+    </check-list>
+    <output-format>
+For each finding:
+🔴/🟡/🟢 [SEVERITY] `file.js:lineN` — **Description**
+→ Suggested fix: `code example`
+    </output-format>
+  </step>
+
+  <step n="3" goal="Review code quality and maintainability">
+    <check-list id="quality">
+      <item>Naming: are variable/function/class names clear and meaningful?</item>
+      <item>Function size: are functions doing one thing? (>30 lines is a yellow flag)</item>
+      <item>DRY violations: is logic duplicated that should be extracted?</item>
+      <item>Magic numbers/strings: should be named constants</item>
+      <item>Comments: missing where logic is complex; unnecessary where code is clear</item>
+      <item>Dead code: unreachable code, unused variables, TODO comments left</item>
+    </check-list>
+  </step>
+
+  <step n="4" goal="Review test coverage">
+    <check-list id="tests">
+      <item>New logic: is it covered by unit tests?</item>
+      <item>Edge cases: are boundary conditions tested?</item>
+      <item>Error paths: are error/exception paths tested?</item>
+      <item>Test quality: do tests actually test behavior, not just coverage?</item>
+    </check-list>
+  </step>
+
+  <step n="5" goal="Compile and write findings">
+    <action>Group all findings by severity: 🔴 Blockers first, then 🟡 Warnings, then 🟢 Suggestions</action>
+    <action>Add positive observations: acknowledge good practices found</action>
+    <action>Write findings to {output_file} using the standard review report format</action>
+    <action>Update {pr_context}: add 'general-review' to completed reviews list</action>
+    <output>✅ General review complete. {blocker_count} blockers, {warning_count} warnings, {suggestion_count} suggestions.
+Run [RR] Generate Report to compile all findings, or continue with another review type.</output>
+  </step>
+</workflow>

package/src/prr/workflows/3-review/general-review/workflow.yaml

@@ -0,0 +1,18 @@
+name: general-review
+description: "General code quality review: logic, naming, readability, error handling, DRY, test coverage"
+author: "PR Review Framework"
+
+config_source: "{project-root}/_prr/prr/config.yaml"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+target_repo: "{config_source}:target_repo"
+review_output: "{config_source}:review_output"
+date: system-generated
+
+installed_path: "{project-root}/_prr/prr/workflows/3-review/general-review"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+
+pr_context: "{review_output}/current-pr-context.yaml"
+project_context: "{review_output}/project-context.yaml"
+output_file: "{review_output}/general-review-{date}.md"

package/src/prr/workflows/3-review/performance-review/checklist.md

@@ -0,0 +1,22 @@
+---
+title: "Performance Review Completion Checklist"
+validation-target: "Performance review output file"
+---
+
+# Performance Review Checklist
+
+## Coverage
+- [ ] Database/query patterns checked (N+1, missing pagination, SELECT *)
+- [ ] Async/await patterns reviewed
+- [ ] Memory management reviewed
+- [ ] Frontend performance checked (if frontend code changed)
+
+## Finding Quality
+- [ ] Every finding has: file path + line/function reference
+- [ ] Every finding has: estimated impact (high/medium/low) with brief rationale
+- [ ] Micro-optimizations are NOT flagged (only impactful issues)
+- [ ] Each finding includes suggested fix
+
+## Output
+- [ ] Findings written to `{review_output}/performance-review-{date}.md`
+- [ ] PR context updated with `performance-review` in completed list

package/src/prr/workflows/3-review/performance-review/instructions.xml

@@ -0,0 +1,68 @@
+<workflow>
+  <critical>Workflow engine rules: {project-root}/_prr/core/tasks/workflow.xml</critical>
+  <critical>Communicate all responses in {communication_language}</critical>
+  <critical>Focus on IMPACTFUL performance issues — skip micro-optimizations that add complexity without measurable benefit</critical>
+  <critical>Quantify impact when possible: "this adds ~Xms per request" or "X MB memory per session"</critical>
+
+  <step n="1" goal="Load PR context and diff">
+    <check if="{pr_context} does not exist">
+      <output>❌ No PR selected. Please run [SP] Select PR first.</output>
+      <stop/>
+    </check>
+    <action>Read {pr_context} and load git diff</action>
+    <output>⚡ Starting Performance Review
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Focus: N+1 queries | Memory | Async | Bundle size | Caching
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
+  </step>
+
+  <step n="2" goal="Database and query performance">
+    <check-list id="database">
+      <item>N+1 queries: DB call inside a loop? Should use batch/join instead</item>
+      <item>Missing pagination: queries that could return unbounded result sets</item>
+      <item>SELECT *: fetching all columns when only a few are needed</item>
+      <item>Missing index: filtering/sorting on non-indexed columns</item>
+      <item>Unnecessary queries: data already available in context/cache but re-fetched</item>
+      <item>Transaction missing: multiple DB writes without transaction (data integrity risk)</item>
+    </check-list>
+  </step>
+
+  <step n="3" goal="Async and concurrency patterns">
+    <check-list id="async">
+      <item>Sequential awaits in loop: `for (x of arr) { await fn(x) }` should be Promise.all</item>
+      <item>Unnecessary await: async function that doesn't need to be async</item>
+      <item>Missing error handling on async operations</item>
+      <item>Blocking operations on main thread/event loop</item>
+      <item>Race conditions: shared state mutated from multiple async paths</item>
+    </check-list>
+  </step>
+
+  <step n="4" goal="Memory management">
+    <check-list id="memory">
+      <item>Event listener cleanup: listeners added but not removed (memory leak pattern)</item>
+      <item>Large objects held in closure/module scope unnecessarily</item>
+      <item>Accumulating arrays/objects without cleanup</item>
+      <item>setInterval/setTimeout without clearInterval/clearTimeout</item>
+      <item>Frontend: components not cleaning up on unmount</item>
+    </check-list>
+  </step>
+
+  <step n="5" goal="Frontend performance (if applicable)">
+    <check-list id="frontend">
+      <item>Bundle size: large new dependencies imported? Is tree-shaking possible?</item>
+      <item>Unnecessary re-renders: state changes causing full component re-renders</item>
+      <item>Images/assets: unoptimized media, missing lazy loading</item>
+      <item>Blocking scripts or render-blocking resources</item>
+      <item>Expensive computations in render path (should be memoized)</item>
+    </check-list>
+  </step>
+
+  <step n="6" goal="Compile and write findings">
+    <action>For each finding: estimate impact (high/medium/low) with brief rationale</action>
+    <action>Distinguish: impactful issues vs micro-optimizations (flag only impactful)</action>
+    <action>Write findings to {output_file}</action>
+    <action>Update {pr_context}: add 'performance-review' to completed list</action>
+    <output>⚡ Performance review complete.
+Run [RR] Generate Report to compile all findings.</output>
+  </step>
+</workflow>

package/src/prr/workflows/3-review/performance-review/workflow.yaml

@@ -0,0 +1,18 @@
+name: performance-review
+description: "Performance-focused code review: N+1 queries, memory leaks, async patterns, bundle size, caching"
+author: "PR Review Framework"
+
+config_source: "{project-root}/_prr/prr/config.yaml"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+target_repo: "{config_source}:target_repo"
+review_output: "{config_source}:review_output"
+date: system-generated
+
+installed_path: "{project-root}/_prr/prr/workflows/3-review/performance-review"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+
+pr_context: "{review_output}/current-pr-context.yaml"
+project_context: "{review_output}/project-context.yaml"
+output_file: "{review_output}/performance-review-{date}.md"

package/src/prr/workflows/3-review/security-review/checklist.md

@@ -0,0 +1,25 @@
+---
+title: "Security Review Completion Checklist"
+validation-target: "Security review output file"
+---
+
+# Security Review Checklist
+
+## Coverage
+- [ ] Secrets scan completed (hardcoded API keys, passwords, tokens)
+- [ ] OWASP A01-A05 checked
+- [ ] OWASP A06-A10 checked
+- [ ] Auth/authorization logic reviewed (if applicable)
+- [ ] Input validation reviewed (if applicable)
+- [ ] New dependencies checked for known vulnerabilities
+
+## Finding Quality
+- [ ] Every finding states: WHAT the vulnerability is
+- [ ] Every finding states: WHERE (file + line number)
+- [ ] Every finding states: IMPACT (what could an attacker do)
+- [ ] Every finding states: HOW TO FIX
+- [ ] Severity: Critical/High/Medium/Low/Info (not just emojis)
+
+## Output
+- [ ] Findings written to `{review_output}/security-review-{date}.md`
+- [ ] PR context updated with `security-review` in completed list

package/src/prr/workflows/3-review/security-review/data/owasp-checklist.csv

@@ -0,0 +1,19 @@
+id,category,check,severity,description
+A01-1,Broken Access Control,Missing authorization check,Critical,"Function/endpoint accessible without role check"
+A01-2,Broken Access Control,Privilege escalation,Critical,"User can access resources belonging to other users"
+A01-3,Broken Access Control,Insecure direct object reference,High,"ID exposed in URL/body without ownership check"
+A02-1,Cryptographic Failures,Hardcoded secret,Critical,"API key password or token in source code"
+A02-2,Cryptographic Failures,Weak hashing algorithm,High,"MD5 or SHA1 used for passwords"
+A02-3,Cryptographic Failures,Sensitive data over HTTP,High,"PII or auth tokens sent without TLS"
+A03-1,Injection,SQL injection,Critical,"User input concatenated into SQL query"
+A03-2,Injection,XSS vulnerability,High,"User input rendered without sanitization"
+A03-3,Injection,Command injection,Critical,"User input passed to shell/exec function"
+A03-4,Injection,Path traversal,High,"User-controlled file path without normalization"
+A05-1,Security Misconfiguration,Debug mode in production,High,"Debug endpoints or verbose errors exposed"
+A05-2,Security Misconfiguration,CORS wildcard,Medium,"Access-Control-Allow-Origin: * on sensitive endpoint"
+A07-1,Auth Failures,No rate limiting on auth,High,"Login/register endpoint without rate limiting"
+A07-2,Auth Failures,Weak session management,High,"Session token predictable or not rotated on login"
+A07-3,Auth Failures,JWT not validated,Critical,"JWT signature not verified or expiry not checked"
+A09-1,Logging Failures,Sensitive data in logs,Medium,"Password API key or PII logged to console"
+A09-2,Logging Failures,Stack trace to user,Medium,"Full error stack trace returned in API response"
+A10-1,SSRF,User-controlled URL fetch,High,"User input used in HTTP request without allowlist"

package/src/prr/workflows/3-review/security-review/instructions.xml

@@ -0,0 +1,70 @@
+<workflow>
+  <critical>Workflow engine rules: {project-root}/_prr/core/tasks/workflow.xml</critical>
+  <critical>Communicate all responses in {communication_language}</critical>
+  <critical>For EVERY security finding: state WHAT, WHERE (file+line), HOW it could be exploited, and HOW to fix it</critical>
+  <critical>Think like an attacker — what could an adversary do with this vulnerability?</critical>
+
+  <step n="1" goal="Load PR context and prepare security analysis">
+    <check if="{pr_context} does not exist">
+      <output>❌ No PR selected. Please run [SP] Select PR first.</output>
+      <stop/>
+    </check>
+    <action>Read {pr_context}</action>
+    <action>Run: git diff {base_branch}...{target_branch} in {target_repo}</action>
+    <output>🔒 Starting Security Review — Thinking like an attacker
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OWASP Top 10 scan + secrets detection + auth review
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
+  </step>
+
+  <step n="2" goal="Scan for hardcoded secrets and sensitive data exposure">
+    <critical>This is the MOST CRITICAL check — do this FIRST</critical>
+    <check-list id="secrets">
+      <item>API keys, tokens, passwords hardcoded in source code</item>
+      <item>Private keys, certificates embedded in code</item>
+      <item>Database connection strings with credentials</item>
+      <item>Secrets in config files that should be in environment variables</item>
+      <item>Sensitive data logged to console (passwords, tokens, PII)</item>
+      <item>Stack traces exposed to end users (reveals internal structure)</item>
+    </check-list>
+  </step>
+
+  <step n="3" goal="OWASP A01-A05: Broken Access Control, Crypto, Injection, Insecure Design, Misconfiguration">
+    <check-list id="owasp-1-5">
+      <item>A01 Broken Access Control: authorization checks present? role-based? privilege escalation possible?</item>
+      <item>A02 Cryptographic Failures: weak hashing (MD5/SHA1)? HTTP instead of HTTPS? key management?</item>
+      <item>A03 Injection: SQL injection? XSS? command injection? template injection? all inputs sanitized?</item>
+      <item>A04 Insecure Design: security by obscurity? missing security controls at design level?</item>
+      <item>A05 Security Misconfiguration: debug mode enabled? default credentials? unnecessary features exposed?</item>
+    </check-list>
+  </step>
+
+  <step n="4" goal="OWASP A06-A10: Vulnerable Components, Auth, Integrity, Logging, SSRF">
+    <check-list id="owasp-6-10">
+      <item>A06 Vulnerable Components: new dependencies added? check for known CVEs</item>
+      <item>A07 Auth Failures: session management? password policies? brute force protection? JWT validation?</item>
+      <item>A08 Integrity Failures: deserialization of untrusted data? unsigned data accepted?</item>
+      <item>A09 Logging/Monitoring: security events logged? sensitive data excluded from logs?</item>
+      <item>A10 SSRF: user-controlled URLs fetched? internal services accessible?</item>
+    </check-list>
+  </step>
+
+  <step n="5" goal="Rate limiting and input validation">
+    <check-list id="input-rate">
+      <item>Rate limiting on auth endpoints (login, register, password reset)</item>
+      <item>Input length limits enforced server-side</item>
+      <item>File upload: type validation, size limits, storage location security</item>
+      <item>CORS configuration: not wildcard (*) on sensitive endpoints</item>
+    </check-list>
+  </step>
+
+  <step n="6" goal="Compile and write security findings">
+    <action>Group findings by severity: Critical → High → Medium → Low → Info</action>
+    <action>For each finding include: WHAT, WHERE (file+line), IMPACT (how exploitable), HOW TO FIX</action>
+    <action>Write to {output_file}</action>
+    <action>Update {pr_context}: add 'security-review' to completed list</action>
+    <output>🔒 Security review complete.
+{critical_count} critical, {high_count} high, {medium_count} medium findings.
+Run [RR] Generate Report to compile all findings.</output>
+  </step>
+</workflow>

package/src/prr/workflows/3-review/security-review/workflow.yaml

@@ -0,0 +1,19 @@
+name: security-review
+description: "Security-focused code review: OWASP top 10, injection, auth, secrets, dependencies"
+author: "PR Review Framework"
+
+config_source: "{project-root}/_prr/prr/config.yaml"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+target_repo: "{config_source}:target_repo"
+review_output: "{config_source}:review_output"
+date: system-generated
+
+installed_path: "{project-root}/_prr/prr/workflows/3-review/security-review"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+owasp_data: "{installed_path}/data/owasp-checklist.csv"
+
+pr_context: "{review_output}/current-pr-context.yaml"
+project_context: "{review_output}/project-context.yaml"
+output_file: "{review_output}/security-review-{date}.md"

package/src/prr/workflows/4-improve/improve-code/checklist.md

@@ -0,0 +1,18 @@
+---
+title: "Improve Code Completion Checklist"
+validation-target: "Improve code output file"
+---
+
+# Improve Code Checklist
+
+## Suggestion Quality
+- [ ] Every suggestion has: BEFORE code block
+- [ ] Every suggestion has: AFTER code block
+- [ ] Every suggestion has: explanation of WHY it's better
+- [ ] Suggestions are impactful — not style nitpicks
+- [ ] Suggestions are correct — the AFTER code actually works
+
+## Output
+- [ ] All suggestions written to `{review_output}/improve-code-{date}.md`
+- [ ] Suggestions grouped by category (Bugs | Quality | Performance | Best Practices)
+- [ ] PR context updated with `improve-code` in completed list

package/src/prr/workflows/4-improve/improve-code/instructions.xml

@@ -0,0 +1,59 @@
+<workflow>
+  <critical>Workflow engine rules: {project-root}/_prr/core/tasks/workflow.xml</critical>
+  <critical>Communicate all responses in {communication_language}</critical>
+  <critical>Every suggestion MUST include: BEFORE code and AFTER code — not just description</critical>
+  <critical>Focus on impactful improvements — not style nitpicks. Each suggestion must save real time or prevent real bugs</critical>
+
+  <step n="1" goal="Load PR context and diff">
+    <check if="{pr_context} does not exist">
+      <output>❌ No PR selected. Please run [SP] Select PR first.</output>
+      <stop/>
+    </check>
+    <action>Read {pr_context} and load full git diff</action>
+    <action>If diff_strategy is 'chunked': process one file at a time</action>
+    <output>💡 Generating Code Improvement Suggestions
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Each suggestion includes BEFORE and AFTER code
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
+  </step>
+
+  <step n="2" goal="Generate concrete improvement suggestions">
+    <action>For each changed file or chunk, identify improvements in these categories:</action>
+    <categories>
+      <category name="bugs">Logic errors that could cause incorrect behavior or exceptions</category>
+      <category name="quality">Simplifications that make code more readable or maintainable</category>
+      <category name="performance">Changes that reduce time/space complexity</category>
+      <category name="best-practices">Patterns that align with language/framework best practices</category>
+    </categories>
+
+    <output-format>
+Each suggestion must follow this format:
+
+**[CATEGORY] `file.js:lineN`** — One-line description
+
+```
+// BEFORE
+{current_code}
+```
+
+```
+// AFTER
+{improved_code}
+```
+
+> Why: {brief explanation of the improvement and its benefit}
+    </output-format>
+
+    <note>For large diffs: process file by file, generate 3-5 highest-impact suggestions per file</note>
+  </step>
+
+  <step n="3" goal="Compile and write suggestions">
+    <action>Group suggestions by category: Bugs | Quality | Performance | Best Practices</action>
+    <action>Sort within each category by impact (most impactful first)</action>
+    <action>Write all suggestions to {output_file}</action>
+    <action>Update {pr_context}: add 'improve-code' to completed list</action>
+    <output>💡 Code improvement suggestions generated.
+{total_count} suggestions: {bug_count} bugs, {quality_count} quality, {perf_count} performance, {bp_count} best practices.
+Run [RR] Generate Report or [PC] Post Comments to share these with the PR author.</output>
+  </step>
+</workflow>

package/src/prr/workflows/4-improve/improve-code/workflow.yaml

@@ -0,0 +1,18 @@
+name: improve-code
+description: "Generate concrete inline code suggestions with before/after diffs — focused on actionable improvements"
+author: "PR Review Framework"
+
+config_source: "{project-root}/_prr/prr/config.yaml"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+target_repo: "{config_source}:target_repo"
+review_output: "{config_source}:review_output"
+date: system-generated
+
+installed_path: "{project-root}/_prr/prr/workflows/4-improve/improve-code"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+
+pr_context: "{review_output}/current-pr-context.yaml"
+project_context: "{review_output}/project-context.yaml"
+output_file: "{review_output}/improve-code-{date}.md"

package/src/prr/workflows/5-ask/ask-code/steps/step-01-load-context.md

@@ -0,0 +1,37 @@
+---
+name: "step-01-load-context"
+description: "Load PR context and ask for the user's question"
+nextStepFile: "./step-02-answer.md"
+---
+
+# Step 1: Load Context and Get Question
+
+## Sequence of Instructions
+
+### 1. Load PR Context
+
+Read `{review_output}/current-pr-context.yaml`.
+
+If not found, prompt user to run [SP] Select PR first.
+
+### 2. Load the Diff
+
+Run `git diff {base_branch}...{target_branch}` in `{target_repo}`.
+
+### 3. Ask the User's Question
+
+```
+🤔 What would you like to ask about the code changes in this PR?
+
+You can ask about:
+  • Specific files or functions (e.g., "explain authController.js:handleLogin")
+  • Design decisions (e.g., "why was X approach used?")
+  • Potential issues (e.g., "what could go wrong with this change?")
+  • Interactions (e.g., "how does this affect the existing session handling?")
+```
+
+**HALT — wait for user's question before proceeding.**
+
+### 4. Load Next Step
+
+Add `step-01-load-context` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/prr/workflows/5-ask/ask-code/steps/step-02-answer.md

@@ -0,0 +1,36 @@
+---
+name: "step-02-answer"
+description: "Answer the user's question about the code changes"
+---
+
+# Step 2: Answer the Question
+
+## Sequence of Instructions
+
+### 1. Analyze the Question in Context
+
+Using the full diff and PR context:
+- Locate the relevant code sections
+- Understand the full context around the specific area being asked about
+- Consider how it interacts with the rest of the codebase
+
+### 2. Provide a Focused Answer
+
+Structure the answer as:
+1. **Direct answer** to the question (1-3 sentences)
+2. **Supporting evidence** from the code (cite specific lines)
+3. **Additional context** if relevant (related code, implications)
+4. **Follow-up considerations** if the answer reveals potential issues
+
+### 3. Offer to Continue
+
+After answering:
+
+```
+💬 Does this answer your question?
+   Feel free to ask another question about the code, or return to the menu for review commands.
+```
+
+**HALT — this workflow supports multiple questions in the same session.**
+If the user asks another question, loop back to answering it without reloading context.
+If the user returns to the menu, workflow is complete.

package/src/prr/workflows/5-ask/ask-code/workflow.md

@@ -0,0 +1,31 @@
+---
+name: ask-code
+description: "Interactive Q&A about specific code changes in the selected PR"
+main_config: "{project-root}/_prr/prr/config.yaml"
+nextStep: "./steps/step-01-load-context.md"
+---
+
+# Ask Code Workflow
+
+**Goal:** Allow the reviewer to ask specific questions about the code changes in the PR. Unlike other review workflows that scan the entire diff, this focuses on a specific question or code area.
+
+Use cases:
+- "What does this function do?"
+- "Why was this pattern used instead of X?"
+- "What are the potential issues with this approach?"
+- "How does this change interact with the existing auth system?"
+- "Is this the right way to handle this edge case?"
+
+## WORKFLOW ARCHITECTURE
+
+Interactive 2-step flow:
+1. Load PR context and diff
+2. Answer the user's specific question with full context
+
+## INITIALIZATION
+
+Load config from `{main_config}`.
+
+## EXECUTION
+
+Read fully and follow: `{nextStep}`

package/src/prr/workflows/6-report/generate-report/steps/step-01-collect.md

@@ -0,0 +1,42 @@
+---
+name: "step-01-collect"
+description: "Collect findings from all completed review files"
+nextStepFile: "./step-02-organize.md"
+---
+
+# Step 1: Collect All Findings
+
+## Sequence of Instructions
+
+### 1. Load PR Context
+
+Read `{review_output}/current-pr-context.yaml` to get list of completed reviews.
+
+### 2. Collect Review Output Files
+
+For each completed review in `review.completed` list, read the corresponding output file:
+- `general-review` → `{review_output}/general-review-*.md` (latest)
+- `security-review` → `{review_output}/security-review-*.md` (latest)
+- `performance-review` → `{review_output}/performance-review-*.md` (latest)
+- `architecture-review` → `{review_output}/architecture-review-*.md` (latest)
+- `improve-code` → `{review_output}/improve-code-*.md` (latest)
+
+### 3. Parse All Findings
+
+From each file, extract all findings with their:
+- Severity (🔴 Blocker / 🟡 Warning / 🟢 Suggestion / Critical/High/Medium/Low)
+- Category (general/security/performance/architecture/improvement)
+- File + line reference
+- Description
+- Suggested fix
+
+### 4. Count Statistics
+
+Count:
+- Total findings by severity
+- Findings by category
+- Files with issues
+
+### 5. Load Next Step
+
+Add `step-01-collect` to `stepsCompleted`. Load: `{nextStepFile}`