prr-kit 1.1.3 → 1.2.1

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

@@ -1,18 +1,17 @@
-name: architecture-review
-description: "Architecture-focused review: SOLID principles, layering, coupling, codebase consistency"
-author: "PR Review Kit"
-
-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"
+name: architecture-review
+description: "Architecture-focused review: SOLID principles, layering, coupling, codebase consistency"
+author: "PR Review Kit"
+
+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"
+output_file: "{review_output}/architecture-review-{date}.md"

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

@@ -0,0 +1,27 @@
+---
+title: "Business Review Completion Checklist"
+validation-target: "Business review output file"
+---
+
+# Business Review Checklist
+
+## Coverage
+- [ ] Feature completeness assessed (branch name, PR title, acceptance criteria if available)
+- [ ] User impact traced (existing flows checked for regressions, new flows checked for clarity)
+- [ ] Business risk evaluated for each 🔴 finding from prior reviews (SR, GR, PR, AR)
+- [ ] Data and migration impact assessed (schema changes, storage migration, rollback plan)
+- [ ] Observability gaps identified (analytics, error monitoring, logging, feature flags)
+- [ ] Cross-cutting and deployment concerns reviewed (browser compat, API contracts, env parity)
+
+## Finding Quality
+- [ ] Every finding states: user impact (who is affected and what happens)
+- [ ] Every finding states: severity level (🔴/🟡/🟢/❓)
+- [ ] Technical findings from prior reviews translated into business language
+- [ ] ❓ QUESTION findings include: specific concern + exact question to ask author
+- [ ] Business Verdict section written: overall risk level (CRITICAL/HIGH/MEDIUM/LOW/MINIMAL)
+- [ ] Deployment recommendation stated: ship now / ship with fixes / do not ship
+- [ ] Post-ship monitoring noted: what to watch after deploy
+
+## Output
+- [ ] Findings written to `{review_output}/business-review-{date}.md`
+- [ ] PR context updated with `business-review` in completed list

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

@@ -0,0 +1,153 @@
+<workflow>
+  <critical>Workflow engine rules: {project-root}/_prr/core/tasks/workflow.xml</critical>
+  <critical>Communicate all responses in {communication_language}</critical>
+  <critical>Think like a Product Manager and Tech Lead combined — bridge technical findings to business outcomes</critical>
+  <critical>Translate EVERY significant technical issue into its business consequence: who is affected, what is the impact, what is the risk magnitude</critical>
+  <critical>Run AFTER GR/SR/PR/AR so you can reference their findings and elevate them to business language</critical>
+  <critical>Finding severities: 🔴 BLOCKER | 🟡 WARNING | 🟢 SUGGESTION | ❓ QUESTION. Use ❓ when business intent or user impact cannot be determined from the diff alone — e.g., "Is this behavior change intentional from a product perspective?", "Were users informed of this breaking change?". A QUESTION that gets a bad answer becomes a BLOCKER or WARNING depending on the business consequence.</critical>
+
+  <step n="1" goal="Load PR context, prior findings, and prepare business 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} to get: target_branch, base_branch, pr_type, pr_knowledge_base, completed_reviews</action>
+    <action>Load PR-specific knowledge base from {pr_knowledge_base} — extract issue_context (acceptance criteria) if available from MCP tools</action>
+    <action>Load findings already collected from completed reviews (GR, SR, PR, AR) to translate them into business impact</action>
+    <action>Run: git diff {base_branch}...{target_branch} --stat in {target_repo} for file scope</action>
+
+    <output>💼 Starting Business Review
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Focus: User Impact | Business Risk | Feature Completeness
+       Data Safety | Observability | Cross-cutting Concerns
+PR type: {pr_type} | Prior reviews loaded: {completed_reviews}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
+  </step>
+
+  <step n="2" goal="Feature completeness and acceptance criteria">
+    <action>Determine what this PR is supposed to deliver based on: branch name, PR description, commit messages, issue context from MCP (if available)</action>
+    <check-list id="completeness">
+      <item>Does the implementation cover the full scope described in the branch name / PR title?</item>
+      <item>If acceptance criteria available (from Jira/Linear MCP): check each AC item against the diff — implemented or missing?</item>
+      <item>Are error states handled from the user's perspective? (not just technically caught, but communicated clearly)</item>
+      <item>Are loading states present for async operations that users will notice?</item>
+      <item>Are empty states handled? (empty list, no results, zero state)</item>
+      <item>Edge cases that affect real users: very long inputs, special characters, concurrent users, offline state</item>
+      <item>Demo / test data or hardcoded values that should not reach production</item>
+    </check-list>
+    <output-format>
+🔴/🟡/🟢/❓ [COMPLETENESS] — **Description**
+→ User impact: what happens to the user if this is shipped as-is
+→ Suggested fix or question: what needs to be added/changed, or what to ask the author
+    </output-format>
+  </step>
+
+  <step n="3" goal="User impact analysis">
+    <action>Trace the user journey through the changed code: what flows are affected, what changes for the user</action>
+    <check-list id="user-impact">
+      <item>UX regressions: does any existing user flow break or degrade?</item>
+      <item>Behavior changes: is existing behavior changed in a way users rely on? (implicit contract broken)</item>
+      <item>New flows: are new features intuitive? Is the UI clear about what actions do?</item>
+      <item>Destructive actions: are irreversible actions (delete, clear, migrate) clearly communicated with confirmation?</item>
+      <item>Feedback loops: do users know when operations succeed or fail? Are there success/error messages?</item>
+      <item>Performance from user perspective: will users notice slowness? (N+1 queries → slow page load, missing debounce → laggy search)</item>
+      <item>Accessibility: keyboard navigation, screen reader labels (aria), color contrast, focus management</item>
+      <item>Mobile/responsive: does UI work on small screens if app is used on mobile?</item>
+    </check-list>
+  </step>
+
+  <step n="4" goal="Business risk assessment — translate technical findings">
+    <action>For each 🔴 finding from prior reviews (SR, GR, PR, AR), assess the business consequence</action>
+    <check-list id="business-risk">
+      <item>Security vulnerabilities → business risk:
+        - XSS: can lead to account takeover, data theft, GDPR breach, reputational damage
+        - Hardcoded credentials: instant unauthorized access if code is public
+        - Broken auth: unauthorized access to protected resources
+        - Token forgeable: privilege escalation, account impersonation
+      </item>
+      <item>Data loss risk: operations that silently lose user data (fire-and-forget DB writes, missing rollback)</item>
+      <item>Downtime risk: breaking changes that could cause failures in production (migration without fallback, schema change)</item>
+      <item>Compliance risk: GDPR (user data exposure), accessibility laws (WCAG), industry regulations</item>
+      <item>Revenue/retention risk: bugs that directly affect core user workflows → churn</item>
+      <item>Support burden: confusing UX or silent errors → high support ticket volume</item>
+      <item>Scale risk: patterns that work with test data but fail at production scale (N+1 with 10k records)</item>
+    </check-list>
+    <output-format>
+🔴 [BUSINESS RISK: CRITICAL/HIGH] — **Risk title**
+→ Technical root cause: {finding from prior review}
+→ Business consequence: {what actually happens in production to real users}
+→ Affected scope: {who / how many users / which workflows}
+→ Mitigation: {what must change before shipping}
+    </output-format>
+  </step>
+
+  <step n="5" goal="Data and migration impact">
+    <action>Identify any changes that affect existing user data or storage mechanisms</action>
+    <check-list id="data-migration">
+      <item>Storage migration: if switching storage (e.g. localStorage → IndexedDB), what happens to existing user data?</item>
+      <item>Schema changes: are existing records compatible with new schema? Is there a migration script?</item>
+      <item>Data seeding: does seeding run every time? Could it overwrite user-created data?</item>
+      <item>Multi-user isolation: is data properly scoped per user? Can User A access User B's data?</item>
+      <item>Rollback plan: if this deploy fails or has a bug, can we roll back without data loss?</item>
+      <item>Backward compatibility: does old code still work if new schema is deployed (blue/green, canary)?</item>
+    </check-list>
+  </step>
+
+  <step n="6" goal="Observability and measurability">
+    <check-list id="observability">
+      <item>Analytics: are new features tracked so we can measure adoption and success?</item>
+      <item>Error monitoring: are errors surfaced to a monitoring system (not just console.error)?</item>
+      <item>Logging: are key business events logged for audit/debug? (login, data mutation, auth failure)</item>
+      <item>Feature flags: is this behind a flag so it can be disabled without a deploy if issues arise?</item>
+      <item>Success metrics: how will the team know this feature is working as intended post-deploy?</item>
+      <item>Internationalization: are there hardcoded strings that would need translation in a multi-language product?</item>
+    </check-list>
+  </step>
+
+  <step n="7" goal="Cross-cutting and deployment concerns">
+    <check-list id="cross-cutting">
+      <item>Browser compatibility: do new APIs (IndexedDB, btoa, CSS features) work across supported browsers?</item>
+      <item>Breaking API contracts: does this change any interfaces that other teams or services depend on?</item>
+      <item>Environment parity: are there dev-only artifacts that could leak to production? (demo hints, console logs, mock data)</item>
+      <item>Third-party dependencies: are new packages added? License compatible? Bundle size impact on users?</item>
+      <item>Deployment order: does this require coordinated deployment with backend or other services?</item>
+    </check-list>
+  </step>
+
+  <step n="8" goal="Compile business impact and write findings">
+    <action>Assign overall business risk level: CRITICAL | HIGH | MEDIUM | LOW | MINIMAL</action>
+
+    <risk-matrix>
+      CRITICAL = data breach risk, auth bypass, mass data loss, compliance violation
+      HIGH     = significant UX regression, silent data loss for some users, performance cliff at scale
+      MEDIUM   = missing features from AC, confusing UX, no observability, rollback concerns
+      LOW      = minor UX gaps, no analytics, non-critical missing edge cases
+      MINIMAL  = additive feature, no regressions, low risk changes
+    </risk-matrix>
+
+    <action>Structure the output by category, ordered by severity within each section:
+      - Feature Completeness gaps (🔴 first, then 🟡, 🟢, ❓)
+      - User Impact issues
+      - Business Risk items (translated from technical findings)
+      - Data/Migration concerns
+      - Observability gaps
+      - Cross-cutting issues
+      - ❓ Questions for Author (consolidated at the end)
+    </action>
+
+    <action>Write a "Business Verdict" section:
+      - Overall risk level
+      - Top 3 business concerns
+      - Deployment recommendation: ship now / ship with fixes / do not ship
+      - Post-ship monitoring: what to watch after deploy
+    </action>
+
+    <action>Update {pr_context}: add 'business-review' to completed reviews list</action>
+
+    <output>💼 Business review complete.
+Business risk: {risk_level}
+{blocker_count} blockers (🔴), {warning_count} warnings (🟡), {suggestion_count} suggestions (🟢), {question_count} questions (❓) for author.
+Run [RR] Generate Report to compile all findings.</output>
+  </step>
+</workflow>

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

@@ -0,0 +1,17 @@
+name: business-review
+description: "Business impact review: user impact, business risk, feature completeness, data safety, observability"
+author: "PR Review Kit"
+
+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/business-review"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+
+pr_context: "{review_output}/current-pr-context.yaml"
+output_file: "{review_output}/business-review-{date}.md"

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

@@ -10,12 +10,16 @@ validation-target: "General review output file"
 - [ ] Logic and correctness checked for each changed function
 - [ ] Error handling reviewed
 - [ ] Test coverage assessed
+- [ ] Side effects reviewed (observer deps, resource cleanup, derived value purity, global state mutations)
+- [ ] Cross-file impact assessed (shared modules, event/signal dispatch, API and contract changes)
 
 ## Finding Quality
 - [ ] Every finding has: file path + line/function reference
-- [ ] Every finding has: severity level (🔴/🟡/🟢)
+- [ ] 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)
+- [ ] ❓ QUESTION findings include: specific concern + which files may be affected + exact question to ask author
+- [ ] Side effect findings include: the affected location OUTSIDE the diff (not just the changed file)
 
 ## Output
 - [ ] Findings written to `{review_output}/general-review-{date}.md`

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

@@ -3,25 +3,32 @@
   <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>
+  <critical>Finding severities: 🔴 BLOCKER (must fix before merge) | 🟡 WARNING (should fix) | 🟢 SUGGESTION (nice to have) | ❓ QUESTION (uncertain — ask author before judging). Use ❓ when: (a) you cannot determine intent from the diff alone, (b) behavior depends on runtime context you can't see, (c) a side effect MAY exist but you need confirmation. A QUESTION that gets a bad answer becomes a BLOCKER or WARNING.</critical>
 
-  <step n="1" goal="Load PR context and diff">
+  <step n="1" goal="Load PR context, knowledge base, 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>Read {pr_context} to get: target_branch, base_branch, diff_strategy, files_changed, pr_knowledge_base</action>
+    <action>Load PR-specific knowledge base from {pr_knowledge_base} (e.g., pr-123-context.yaml)</action>
+    <note>Knowledge base contains: relevant ESLint rules, guidelines from CLAUDE.md/CONTRIBUTING.md/ARCHITECTURE.md, inline annotations, external rules</note>
     <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}
+Context: Loaded fresh PR-specific knowledge base
 Strategy: {diff_strategy}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
   </step>
 
-  <step n="2" goal="Review code logic and correctness">
+  <step n="2" goal="Review code logic and correctness with PR-specific context">
+    <action>Apply ESLint rules from knowledge_base.relevant_rules.eslint</action>
+    <action>Apply guidelines from knowledge_base.relevant_guidelines</action>
+    <action>Check inline annotations from knowledge_base.inline_context</action>
     <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>
@@ -32,8 +39,8 @@ Strategy: {diff_strategy}
     </check-list>
     <output-format>
 For each finding:
-🔴/🟡/🟢 [SEVERITY] `file.js:lineN` — **Description**
-→ Suggested fix: `code example`
+🔴/🟡/🟢/❓ [SEVERITY] `path/to/file:lineN` — **Description**
+→ Suggested fix or question: `code example or specific question to ask author`
     </output-format>
   </step>
 
@@ -57,12 +64,36 @@ For each finding:
     </check-list>
   </step>
 
-  <step n="5" goal="Compile and write findings">
-    <action>Group all findings by severity: 🔴 Blockers first, then 🟡 Warnings, then 🟢 Suggestions</action>
+  <step n="5" goal="Review side effects and cross-file technical impact">
+    <note>Reference the Impact Map from the describe-pr walkthrough if available. If not, perform the scan inline. This step applies to all stacks — frontend, backend, mobile, gaming, etc.</note>
+    <check-list id="side-effects">
+      <item>Observer / reactive subscriptions: are all dependencies or triggers for observers, watchers, and subscriptions declared correctly? Missing deps cause stale state; unnecessary triggers cause redundant work. Use ❓ if intent is unclear.</item>
+      <item>Resource cleanup: are resources acquired in lifecycle hooks (subscriptions, timers, handles, connections, threads, listeners) properly released on teardown/destruction? Missing cleanup causes leaks.</item>
+      <item>Derived / computed values: do any derived values or selectors have hidden side effects (mutations, I/O, network calls)? Derived values must be pure.</item>
+      <item>Shared / global state mutations: does this change mutate state visible outside the current module (singletons, global variables, shared memory, context, state managers)? Cross-reference Impact Map for who observes it.</item>
+      <item>Event / signal dispatch: new events, signals, notifications, or messages emitted — are all consumers/listeners accounted for? Is the payload shape backward compatible?</item>
+      <item>Public interface changes on shared modules: flag any breaking change (signature, return type, exported contract) here as ❓ QUESTION or 🔴 BLOCKER. Full blast radius analysis is covered in Architecture Review — cross-reference if AR has already run.</item>
+      <item>Unintended cascading reactions: does a state or data change trigger downstream observers, callbacks, or re-computations in unrelated parts of the system? Check for missing guards, debounce, or memoization.</item>
+      <item>Cross-boundary contract changes: changed API response, schema, binary format, serialization format, or protocol — are all consumers (other services, clients, upstream/downstream systems) updated in this PR or is a migration plan documented?</item>
+    </check-list>
+    <output-format>
+For side effect findings, include the AFFECTED LOCATION (the file outside the diff that is impacted):
+❓ QUESTION `src/core/SessionManager.cpp:42` — `activeUser` data structure changed. Are all observers updated?
+   Potentially affected: ProfileRenderer.cpp (callback on activeUser), PermissionGuard.ts (derived from activeUser)
+   → Ask author: "Were ProfileRenderer and PermissionGuard tested with the new data shape?"
+
+🔴 BLOCKER `src/common/InputHandler.h:15` — Required parameter `deviceId` added without default. Breaking change.
+   Affected consumers: ~12 files (see Impact Map)
+   → Add default value or make optional; audit all call sites.
+    </output-format>
+  </step>
+
+  <step n="6" goal="Compile and write findings">
+    <action>Group all findings by severity: 🔴 Blockers first, then 🟡 Warnings, then 🟢 Suggestions, then ❓ Questions</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.
+    <output>✅ General review complete. {blocker_count} blockers, {warning_count} warnings, {suggestion_count} suggestions, {question_count} questions for author.
 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

@@ -1,18 +1,17 @@
-name: general-review
-description: "General code quality review: logic, naming, readability, error handling, DRY, test coverage"
-author: "PR Review Kit"
-
-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"
+name: general-review
+description: "General code quality review: logic, naming, readability, error handling, DRY, test coverage"
+author: "PR Review Kit"
+
+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"
+output_file: "{review_output}/general-review-{date}.md"

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

@@ -13,9 +13,11 @@ validation-target: "Performance review output file"
 
 ## Finding Quality
 - [ ] Every finding has: file path + line/function reference
+- [ ] Every finding has: severity level (🔴/🟡/🟢/❓)
 - [ ] Every finding has: estimated impact (high/medium/low) with brief rationale
 - [ ] Micro-optimizations are NOT flagged (only impactful issues)
-- [ ] Each finding includes suggested fix
+- [ ] Each finding includes suggested fix or question
+- [ ] ❓ QUESTION findings include: specific concern + context needed to assess severity (e.g., "Is this in a hot path?", "What is the expected data volume?")
 
 ## Output
 - [ ] Findings written to `{review_output}/performance-review-{date}.md`

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

@@ -3,16 +3,20 @@
   <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>
+  <critical>Finding severities: 🔴 BLOCKER | 🟡 WARNING | 🟢 SUGGESTION | ❓ QUESTION. Use ❓ when impact depends on context you cannot determine from the diff — e.g., "Is this function called in a hot path?", "What is the expected data volume here?". A QUESTION that gets a bad answer becomes a BLOCKER or WARNING.</critical>
 
-  <step n="1" goal="Load PR context and diff">
+  <step n="1" goal="Load PR context, knowledge base, 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>
+    <action>Load PR-specific knowledge base from {pr_knowledge_base}</action>
+    <action>Extract performance guidelines from knowledge_base.relevant_guidelines</action>
     <output>⚡ Starting Performance Review
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Focus: N+1 queries | Memory | Async | Bundle size | Caching
+Context: Loaded performance best practices from docs
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
   </step>
 
@@ -58,11 +62,14 @@ Focus: N+1 queries | Memory | Async | Bundle size | Caching
   </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>Distinguish: impactful issues vs micro-optimizations — only include impactful ones</action>
+    <action>For each finding: assign severity based on impact scope — 🔴 if causes measurable regression or data integrity risk, 🟡 if significant but not blocking, 🟢 if low-impact optimization, ❓ if impact cannot be determined without author context</action>
+    <action>Include a one-line impact rationale per finding (e.g., "adds ~Xms per request", "O(n²) on unbounded input", "leaks ~X MB per session")</action>
+    <action>Group findings by severity: 🔴 Blockers → 🟡 Warnings → 🟢 Suggestions → ❓ Questions for Author</action>
     <action>Write findings to {output_file}</action>
     <action>Update {pr_context}: add 'performance-review' to completed list</action>
     <output>⚡ Performance review complete.
+{blocker_count} blockers (🔴), {warning_count} warnings (🟡), {suggestion_count} suggestions (🟢), {question_count} questions (❓) for author.
 Run [RR] Generate Report to compile all findings.</output>
   </step>
 </workflow>

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

@@ -1,18 +1,17 @@
-name: performance-review
-description: "Performance-focused code review: N+1 queries, memory leaks, async patterns, bundle size, caching"
-author: "PR Review Kit"
-
-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"
+name: performance-review
+description: "Performance-focused code review: N+1 queries, memory leaks, async patterns, bundle size, caching"
+author: "PR Review Kit"
+
+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"
+output_file: "{review_output}/performance-review-{date}.md"

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

@@ -18,7 +18,8 @@ validation-target: "Security review output file"
 - [ ] 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)
+- [ ] Severity assigned: 🔴/🟡/🟢/❓ (Critical/High → 🔴, Medium → 🟡, Low/Info → 🟢)
+- [ ] ❓ QUESTION findings include: specific concern + exact question to ask author (e.g., "Was this auth check intentionally removed?")
 
 ## Output
 - [ ] Findings written to `{review_output}/security-review-{date}.md`

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

@@ -3,17 +3,22 @@
   <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>
+  <critical>Finding severities: 🔴 BLOCKER | 🟡 WARNING | 🟢 SUGGESTION | ❓ QUESTION. Use ❓ when you cannot determine from the diff whether a behavior is intentional or a vulnerability — e.g., "Is this endpoint intentionally public?", "Was this auth check deliberately removed?". A QUESTION that gets a bad answer becomes a BLOCKER.</critical>
 
-  <step n="1" goal="Load PR context and prepare security analysis">
+  <step n="1" goal="Load PR context, knowledge base, 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>Load PR-specific knowledge base from {pr_knowledge_base}</action>
+    <action>Extract security guidelines from knowledge_base.relevant_guidelines</action>
+    <action>Check for security annotations from knowledge_base.inline_context (@security:)</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
+Context: Loaded security guidelines from CLAUDE.md/CONTRIBUTING.md
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
   </step>
 
@@ -59,12 +64,12 @@ OWASP Top 10 scan + secrets detection + auth review
   </step>
 
   <step n="6" goal="Compile and write security findings">
-    <action>Group findings by severity: Critical → High → Medium → Low → Info</action>
+    <action>Group findings by severity: 🔴 Critical/High → 🟡 Medium → 🟢 Low/Info → ❓ Questions for Author</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.
+{blocker_count} blockers (🔴), {warning_count} warnings (🟡), {suggestion_count} suggestions (🟢), {question_count} questions (❓) for author.
 Run [RR] Generate Report to compile all findings.</output>
   </step>
 </workflow>

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

@@ -1,19 +1,18 @@
-name: security-review
-description: "Security-focused code review: OWASP top 10, injection, auth, secrets, dependencies"
-author: "PR Review Kit"
-
-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"
+name: security-review
+description: "Security-focused code review: OWASP top 10, injection, auth, secrets, dependencies"
+author: "PR Review Kit"
+
+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"
+output_file: "{review_output}/security-review-{date}.md"

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

@@ -1,18 +1,17 @@
-name: improve-code
-description: "Generate concrete inline code suggestions with before/after diffs — focused on actionable improvements"
-author: "PR Review Kit"
-
-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"
+name: improve-code
+description: "Generate concrete inline code suggestions with before/after diffs — focused on actionable improvements"
+author: "PR Review Kit"
+
+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"
+output_file: "{review_output}/improve-code-{date}.md"