prr-kit 1.1.3 → 1.2.1

package/src/prr/workflows/2-analyze/collect-pr-context/steps/step-03-build-knowledge-base.md

@@ -0,0 +1,337 @@
+---
+name: "step-03-build-knowledge-base"
+description: "Build structured PR-specific knowledge base for reviewers"
+---
+
+# Step 3: Build PR-Specific Knowledge Base
+
+## Goal
+Transform collected data into structured knowledge base optimized for reviewers.
+
+## Sequence of Instructions
+
+### 1. Announce Knowledge Base Building
+
+```
+🧠 Building PR-specific knowledge base...
+```
+
+### 2. Create Knowledge Base Structure
+
+Build YAML structure with all collected context:
+
+```yaml
+# PR-Specific Context
+# Generated: {timestamp}
+# For PR: {pr_number} / Branch: {branch_name}
+
+pr_metadata:
+  pr_number: {pr_number}
+  branch: {branch_name}
+  base_branch: {base_branch}
+  files_changed: {n}
+  collected_at: {ISO timestamp}
+
+files_analysis:
+  changed_files:
+    - path: src/stores/todoStore.js
+      extension: .js
+      category: pinia-store
+      domains: [state-management]
+
+    - path: src/views/TodoListView.vue
+      extension: .vue
+      category: vue-view
+      domains: [ui-components, state-management]
+
+  domains_involved:
+    - state-management
+    - ui-components
+
+  file_types:
+    - .js (1 file)
+    - .vue (1 file)
+
+relevant_rules:
+  # ESLint rules that apply to this PR
+  eslint:
+    vue/multi-word-component-names:
+      severity: error
+      applies_to: [TodoListView.vue]
+      description: Component names must be multi-word
+
+    vue/require-prop-types:
+      severity: error
+      applies_to: [*.vue]
+      description: Props must have type definitions
+
+    prefer-const:
+      severity: error
+      applies_to: [*.js, *.vue]
+      description: Use const instead of let when variable is not reassigned
+
+    no-var:
+      severity: error
+      applies_to: [*.js, *.vue]
+      description: No var keyword allowed
+
+  prettier:
+    semi: false
+    singleQuote: true
+    tabWidth: 2
+    printWidth: 100
+    applies_to: all_files
+
+relevant_guidelines:
+  # From CLAUDE.md
+  state_management:
+    source: CLAUDE.md
+    section: State Management
+    content: |
+      Use Pinia stores with setup function style.
+      - State: use ref() and reactive()
+      - Getters: use computed()
+      - Actions: regular functions
+      - No Options API allowed
+
+    applies_to: [src/stores/todoStore.js]
+
+  security:
+    source: CLAUDE.md
+    section: Security
+    content: |
+      Never use v-html with user input.
+      All inputs must be validated and sanitized.
+
+    applies_to: [src/views/TodoListView.vue]
+
+  # From CONTRIBUTING.md
+  component_standards:
+    source: CONTRIBUTING.md
+    section: Component Standards
+    content: |
+      - Use PascalCase for component names
+      - Multi-word names required (enforced by ESLint)
+      - Props must have types and defaults
+      - Use Composition API with <script setup>
+
+    applies_to: [src/views/TodoListView.vue]
+
+  # From ARCHITECTURE.md
+  container_presentational_pattern:
+    source: ARCHITECTURE.md
+    section: Component Architecture
+    content: |
+      Follow Container/Presentational pattern:
+      - Container (views/): Connect to stores, handle logic
+      - Presentational (components/): Receive props, emit events
+
+    applies_to: [src/views/TodoListView.vue]
+
+  pinia_patterns:
+    source: ARCHITECTURE.md
+    section: State Management
+    adr: ADR-002
+    content: |
+      Use Pinia with setup function style.
+      Rationale: Simpler API, better TypeScript support.
+      Actions modify state directly (no mutations).
+
+    applies_to: [src/stores/todoStore.js]
+
+inline_context:
+  annotations:
+    - file: src/stores/todoStore.js
+      line: 10
+      type: "@pattern"
+      content: "Use composition API only"
+      priority: high
+
+    - file: src/stores/todoStore.js
+      line: 15
+      type: "@security"
+      content: "Validate all inputs before storage"
+      priority: critical
+
+stack_context:
+  # Populated from data/stacks/{stack}.md files for each detected stack.
+  # All reviewers (GR, SR, PR, AR, BR) MUST read and apply these rules
+  # in addition to project-specific guidelines.
+  detected_stacks: [vue3, typescript]
+
+  rules:
+    vue3:
+      security:
+        - severity: critical
+          rule: "v-html with user-controlled data → XSS. Use {{ }} or DOMPurify."
+        - severity: high
+          rule: "Dynamic :is binding with user string → arbitrary component injection."
+      performance:
+        - severity: high
+          rule: "watchEffect/watch with async ops without onCleanup → memory leak on unmount."
+        - severity: medium
+          rule: "v-for without :key or using index key → broken reconciliation on reorder."
+      architecture:
+        - severity: high
+          rule: "Direct store state mutation outside action → bypasses Pinia devtools."
+        - severity: high
+          rule: "Props mutation instead of emit → violates one-way data flow."
+      code_quality:
+        - severity: high
+          rule: "defineProps without TypeScript types → silent prop misuse."
+        - severity: medium
+          rule: "Options API mixed with Composition API in same component."
+      common_bugs:
+        - severity: high
+          rule: "reactive() destructuring loses reactivity — use toRefs() to preserve it."
+        - severity: medium
+          rule: "watch missing immediate:true when logic should run on initial value."
+    typescript:
+      architecture:
+        - severity: high
+          rule: "'any' type defeats TypeScript purpose — use unknown + type narrowing."
+        - severity: high
+          rule: "strict:false or missing strict in tsconfig → implicit any, loose null checks."
+      code_quality:
+        - severity: high
+          rule: "@ts-ignore without explanation hides real bugs."
+        - severity: medium
+          rule: "Missing return type annotation on exported functions."
+    # ... additional detected stacks follow same pattern
+
+external_context:
+  # Populated only when external_sources.enabled: true and tools were available
+  mcp_tools_used: []              # e.g. ["confluence", "jira"]
+
+  knowledge_base:                 # From Confluence / Notion / etc.
+    - source: Confluence
+      page: "Engineering Standards"
+      content: |
+        All state mutations must be logged for audit purposes.
+        JWT tokens must be validated server-side.
+
+  issue_context:                  # From Jira / Linear / GitHub Issues
+    key: ENG-123
+    title: "Add user authentication"
+    type: story
+    acceptance_criteria:
+      - "User can log in with email and password"
+      - "Session expires after 24 hours"
+      - "Failed login shows error message without leaking details"
+
+  design_context:                 # From Figma / Zeplin (UI changes only)
+    matched_components: []
+    specs: []
+
+  rag_patterns:                   # From AWS Bedrock / GitHub Graph RAG / etc.
+    - pattern: "Auth store pattern"
+      source: "Previous PR #88"
+      content: "Use httpOnly cookies for token storage, not localStorage"
+
+  url_sources:                    # From plain URL fetches
+    - name: "Shared ESLint config"
+      url: "https://raw.githubusercontent.com/org/standards/main/eslint.md"
+      content: "..."
+
+review_priorities:
+  # Guide reviewers on what to focus on
+  critical:
+    - "Verify no v-html with user input (security requirement)"
+    - "Check ESLint error-level rules compliance"
+    - "Verify Pinia setup function style (ADR-002)"
+
+  important:
+    - "Check component naming (multi-word required)"
+    - "Verify props have types and defaults"
+    - "Check Container/Presentational pattern adherence"
+
+  low_priority:
+    - "Minor style preferences"
+    - "Optional optimizations"
+
+reviewer_guidance:
+  general_review:
+    - "Check for ESLint rule violations (no-var, prefer-const)"
+    - "Verify component naming follows standards"
+    - "Check inline annotations are followed"
+
+  security_review:
+    - "Flag ANY v-html usage (critical)"
+    - "Check input validation per inline annotations"
+    - "Verify no hardcoded secrets"
+
+  performance_review:
+    - "Check computed vs methods usage"
+    - "Verify efficient filtering/searching"
+
+  architecture_review:
+    - "Verify Container/Presentational pattern"
+    - "Check Pinia setup function style (not Options API)"
+    - "Verify SRP adherence"
+
+context_sources:
+  # Track what sources were used
+  primary_docs: [CLAUDE.md, AGENTS.md]
+  config_files: [.eslintrc.js, .prettierrc]
+  standards_docs: [CONTRIBUTING.md, ARCHITECTURE.md]
+  inline_annotations: yes
+  mcp_tools: []                   # list of MCP tools actually used
+  rag_systems: []                 # list of RAG systems queried
+  url_sources: []                 # list of plain URLs fetched
+```
+
+### 3. Determine Output Filename
+
+```javascript
+if (pr_number_available) {
+  filename = `pr-${pr_number}-context.yaml`
+} else {
+  // Use sanitized branch name
+  const safeBranchName = branch_name.replace(/[^a-zA-Z0-9-]/g, '-')
+  filename = `pr-${safeBranchName}-context.yaml`
+}
+```
+
+### 4. Write Knowledge Base to File
+
+Write to: `{review_output}/{filename}`
+
+Example: `_prr-output/pr-123-context.yaml`
+
+### 5. Report Completion
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ PR-Specific Context Ready
+
+📄 File: {filename}
+📊 Stats:
+   • ESLint rules: {n}
+   • Guidelines: {m}
+   • Inline annotations: {k}
+   • MCP tools used: {mcp_list or "none"}
+   • RAG patterns: {rag_count}
+   • Issue context: {issue_key or "none"}
+
+🎯 Domains: {domains}
+📚 Sources: {source_count} ({list})
+
+✓ Context is fresh and PR-specific
+✓ Ready for review workflows
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 6. Store Context Path
+
+Update PR context file to include knowledge base path:
+
+```yaml
+# {review_output}/current-pr-context.yaml
+pr_knowledge_base: "{review_output}/{filename}"
+```
+
+This allows review workflows to find the knowledge base.
+
+### 7. Workflow Complete
+
+Mark workflow as complete. Context is ready for use by review workflows (GR, SR, PR, AR).

package/src/prr/workflows/2-analyze/collect-pr-context/workflow.md

@@ -0,0 +1,123 @@
+---
+name: collect-pr-context
+description: "Collect fresh, PR-specific context from multiple sources after describing the PR"
+main_config: "{project-root}/_prr/prr/config.yaml"
+nextStep: "./steps/step-01-analyze-files.md"
+output_file: "{review_output}/pr-{pr_number}-context.yaml"
+---
+
+# Collect PR-Specific Context Workflow
+
+**Goal:** Dynamically collect context relevant to THIS specific PR from multiple sources. Context is always fresh and PR-specific, never cached.
+
+## WHY THIS APPROACH
+
+**Problems with static cached context:**
+- ❌ Goes stale when rules change
+- ❌ User must remember to refresh manually
+- ❌ Includes irrelevant context for small PRs
+
+**Benefits of dynamic PR-specific context:**
+- ✅ Always latest (collected fresh each time)
+- ✅ PR-specific (only rules/docs relevant to files changed)
+- ✅ No manual refresh needed
+- ✅ Can extract inline code annotations
+- ✅ Supports multiple sources (docs, configs, code, external APIs)
+
+## WHEN TO RUN
+
+**Automatically** after [DP] Describe PR in the quick workflow.
+Runs before any review workflows to provide fresh context.
+
+## CONTEXT SOURCES
+
+### 1. Primary Documentation
+- `CLAUDE.md` - Project-wide instructions
+- `AGENTS.md` - Agent-specific guidelines
+- `.github/CLAUDE_CODE_RULES.md`
+
+### 2. Config Files (based on file types changed)
+- `.eslintrc*` - Linting rules
+- `.prettierrc*` - Formatting rules
+- `tsconfig.json` - TypeScript config
+- `vite.config.*` / `webpack.config.*` - Build config
+
+### 3. Standards Documents
+- `CONTRIBUTING.md` - Coding standards
+- `ARCHITECTURE.md` - Architecture patterns
+- `docs/**/*.md` - Domain-specific docs
+
+### 4. Inline Code Annotations
+Extract from changed files:
+- `@context:` - Contextual information
+- `@security:` - Security requirements
+- `@pattern:` - Required patterns
+- `@rule:` - Specific rules
+
+### 5. Stack-Specific Rules (automatic)
+Loaded from `_prr/prr/data/stacks/{stack}.md` based on detected technology. Detection is automatic from file extensions, imports, and config files — see `step-01-analyze-files.md` for full detection logic.
+
+**Frontend Frameworks:** vue3, react, angular, svelte, nextjs, nuxtjs, astro, solidjs, htmx, qwik
+**Styling:** typescript, tailwindcss, css, sass, styled-components
+**State Management:** redux, mobx, zustand
+**Backend — Node.js:** nestjs, expressjs, fastify, hono
+**Backend — Python:** fastapi, django, flask, python
+**Backend — Java:** spring-boot, java
+**Backend — JVM:** kotlin, scala
+**Backend — .NET:** csharp
+**Backend — Systems:** cpp, rust, zig
+**Backend — Functional:** elixir, phoenix, haskell
+**Backend — Scripting:** go, gin, fiber, actix, axum, lua, bash, php, laravel, rails
+**Database / ORM:** sql, postgresql, mysql, sqlite, mongodb, redis, dynamodb, prisma, typeorm, sequelize, drizzle
+**BaaS / Cloud:** firebase, supabase, aws-cdk
+**Testing — Unit/Integration:** jest-vitest, pytest, junit, playwright, cypress
+**Infrastructure:** docker, kubernetes, helm, terraform, github-actions, ansible, nginx
+**API Layer:** graphql, grpc, trpc, apollo, socket-io
+**Mobile:** react-native, flutter, expo, android, swift
+**Desktop:** electron, tauri
+**Runtime:** deno, bun, node
+**Game Dev:** unity, unreal, godot, phaser, bevy, babylonjs, opengl, vulkan, libgdx, love2d, monogame, pygame
+**AI/ML:** langchain, openai-api, pytorch, scikit-learn
+**Web Components:** lit, htmx
+**Blockchain:** solidity
+**Systems/WASM:** wasm
+
+Each stack file contains Security / Performance / Architecture / Code Quality / Common Bugs rules organized by severity (CRITICAL / HIGH / MEDIUM / LOW). Rules are injected into the knowledge base and applied by all reviewers (GR, SR, PR, AR, BR).
+
+If a stack has no matching data file, skip it silently and proceed with general rules only.
+
+### 6. External Sources (optional)
+- Company standards APIs
+- Confluence/Wiki pages
+- Remote documentation
+
+### 7. MCP Tools (if available in session)
+- **Knowledge base MCPs** (Confluence, Notion, Obsidian) → team standards, ADRs not in local docs
+- **Project management MCPs** (Jira, Linear, GitHub Issues) → linked issue, acceptance criteria
+- **Design MCPs** (Figma, Zeplin) → design specs for UI changes
+- **Code intelligence MCPs** (Sourcegraph, GitHub) → similar patterns in codebase
+
+### 8. RAG Systems (if configured)
+- AWS Bedrock knowledge base
+- GitHub Graph RAG
+- Custom vector databases
+- Query for: similar patterns, past decisions, architecture examples
+
+## WORKFLOW ARCHITECTURE
+
+3-step process:
+1. **Analyze files** changed in PR — extract metadata, domains, and **detect technology stacks**
+2. **Collect context** from all sources: primary docs, config files, standards docs, inline annotations, **stack-specific rules**, MCP tools, RAG systems
+3. **Build PR-specific knowledge base** — structured YAML with all context, stack rules, and reviewer guidance
+
+## INITIALIZATION
+
+Load config from `{main_config}`.
+
+Check if PR number is available:
+- If available: use `pr-{pr_number}-context.yaml`
+- If not: use `pr-{branch_name}-context.yaml`
+
+## EXECUTION
+
+Read fully and follow: `{nextStep}`

package/src/prr/workflows/2-analyze/describe-pr/steps/step-02-classify.md

@@ -22,7 +22,8 @@ Analyze the diff to determine the PRIMARY type (pick the best match):
 | `feature` | New files, new functions, new UI components |
 | `refactor` | Same behavior, restructured code, renamed variables |
 | `performance` | Caching, query optimization, async improvements |
-| `security` | Auth changes, input validation, dependency updates |
+| `security` | Auth changes, input validation, dependency security updates |
+| `hotfix` | Urgent production fix, usually a targeted single change |
 | `test` | Only test file changes |
 | `docs` | Only documentation/comment changes |
 | `config` | Config files, env, CI/CD changes |
@@ -38,12 +39,17 @@ Based on PR type and what was changed:
 ### 3. Generate Review Recommendations
 
 Based on classification, recommend specific reviews:
-- bugfix → GR (general) + SR (if security-related)
-- feature → GR + AR (architecture) + PR (if DB/async)
-- security → SR (mandatory) + GR
-- performance → PR + GR
+- bugfix → GR + SR (if security-related) + BR (if user-facing)
+- feature → GR + AR + PR (if DB/async) + BR (user impact + feature completeness)
+- security → SR (mandatory) + GR + BR (business/compliance risk)
+- performance → PR + GR + BR (if user-facing slowness)
 - refactor → AR + GR
-- All high-risk PRs → SR mandatory
+- hotfix → GR + SR + BR (high deployment risk — assess before shipping)
+- test → GR (light)
+- docs → (skip or GR light)
+- config → GR
+- chore → GR (light)
+- All high-risk PRs → SR mandatory + BR mandatory
 
 ### 4. Load Next Step
 

package/src/prr/workflows/2-analyze/describe-pr/steps/step-03-walkthrough.md

@@ -36,6 +36,64 @@ Format:
    Focus: Check token validation logic and blacklist cleanup mechanism
 ```
 
-### 3. Load Next Step
+### 3. Generate Impact Map
+
+After summarizing each file, proactively scan for cross-cutting side effects. This map will be attached to the PR description output and used by all review phases.
+
+#### 3a. Shared / Generic Module Changes
+
+For each changed file that is a **shared, generic, or common** resource (utility modules, shared libraries, base classes, common interfaces/headers, core services, shared data models, global state, or any module imported by many others):
+
+- Search the codebase (via grep/search tools on import/include/require/use statements) for all files that depend on it
+- Count consumers and list up to 5 of the most significant ones (most widely depended-upon, or in the most critical workflows based on naming/context)
+- Flag if the change is **breaking** (signature change, removed export, behavior change) or **additive**
+- If codebase search is unavailable (diff-only context), note: "⚠️ Consumer scan not possible — flag for manual inspection by reviewer"
+
+Format:
+```
+⚠️ IMPACT: src/common/HttpClient.ts — used by 34 files
+   Change type: Public interface modified (added required param `timeout`)
+   Key consumers: OrderService.ts, UserService.ts, NotificationService.ts
+   Risk: BREAKING — all consumers must pass `timeout` or get a compile/runtime error
+```
+
+#### 3b. Side Effect Scan
+
+For each changed file, identify any **observer/reactive dependencies** that may cause downstream effects in files NOT in the diff:
+
+- **Observer / reactive patterns**: watchers, listeners, Rx streams, signals, delegates, callbacks, subscriptions that observe state changed in this PR — are their side effects scoped or global?
+- **Lifecycle-bound resources**: listeners, timers, handles, connections, threads, or subscriptions created in setup/init — check that teardown/cleanup is still correct after this change
+- **Shared / global state**: singletons, global variables, shared memory, context, state managers — who reads or writes this state outside the diff?
+- **Event / signal dispatch**: new events, signals, notifications, or messages emitted/published — are all consumers/listeners accounted for? Is the payload backward compatible?
+- **Cross-boundary contracts**: API response shape, function signatures, binary interfaces (ABI), serialization schemas (protobuf, JSON schema, GraphQL), DB schema — which consumers depend on the old shape?
+
+Format:
+```
+⚡ SIDE EFFECT: src/core/SessionManager.cpp — `activeUser` state modified
+   Observed by (outside diff): ProfileRenderer.cpp (callback), PermissionGuard.ts (derived)
+   Risk: Logic change in activeUser may silently break profile display and permission checks
+```
+
+#### 3c. Impact Map Summary
+
+Produce a concise block at the end of the walkthrough:
+
+```
+📊 IMPACT MAP
+─────────────────────────────────────────────
+Shared modules modified    : X file(s) — [list]
+Blast radius (consumers)   : ~N files affected
+Side effects / observers   : X location(s) — [list]
+Cross-service dependencies : X (if applicable)
+─────────────────────────────────────────────
+⚠️  High-risk items for reviewers: [bullet list of top concerns]
+```
+
+If no cross-cutting impact is found, state explicitly:
+```
+📊 IMPACT MAP — No shared module or side effect impacts detected.
+```
+
+### 4. Load Next Step
 
 Add `step-03-walkthrough` to `stepsCompleted`. Load: `{nextStepFile}`

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

@@ -10,12 +10,16 @@ validation-target: "Architecture review output file"
 - [ ] Coupling and module dependencies reviewed
 - [ ] Consistency with existing codebase patterns assessed
 - [ ] SOLID violations checked (only real ones, not theoretical)
+- [ ] Shared/generic module changes identified and blast radius assessed
+- [ ] Backward compatibility of all changed public interfaces verified
 
 ## Finding Quality
 - [ ] Every finding references the EXISTING pattern that should be followed
 - [ ] Over-engineering suggestions are avoided (consistency > theoretical purity)
 - [ ] Every finding has: file path + what pattern was violated
 - [ ] Justification provided for why the finding matters (not just "violates SOLID")
+- [ ] Blast radius findings include: consumer count + list of unupdated consumers
+- [ ] ❓ QUESTION findings include: specific question + list of potentially affected files outside the diff
 
 ## Output
 - [ ] Findings written to `{review_output}/architecture-review-{date}.md`

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

@@ -3,17 +3,22 @@
   <critical>Communicate all responses in {communication_language}</critical>
   <critical>Consistency with EXISTING codebase patterns is paramount — avoid over-engineering or introducing new patterns without strong justification</critical>
   <critical>Always consider: would a new team member understand where this code belongs and why?</critical>
+  <critical>Finding severities: 🔴 BLOCKER | 🟡 WARNING | 🟢 SUGGESTION | ❓ QUESTION. Use ❓ when you cannot determine intent or impact from the diff alone and need author confirmation before judging. A QUESTION that gets a bad answer becomes a BLOCKER or WARNING.</critical>
 
-  <step n="1" goal="Load PR context and understand the codebase structure">
+  <step n="1" goal="Load PR context, knowledge base, and understand the codebase structure">
     <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 architectural patterns from knowledge_base.relevant_guidelines (ARCHITECTURE.md sections, ADRs)</action>
+    <action>Check pattern annotations from knowledge_base.inline_context (@pattern:)</action>
     <action>Also examine surrounding non-changed files to understand existing patterns</action>
     <output>🏗️ Starting Architecture Review
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Focus: Layer violations | Coupling | SOLID | Codebase consistency
+Context: Loaded architectural patterns & ADRs from ARCHITECTURE.md
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
   </step>
 
@@ -46,7 +51,29 @@ Focus: Layer violations | Coupling | SOLID | Codebase consistency
     </check-list>
   </step>
 
-  <step n="5" goal="SOLID principles (only flag real violations, not theoretical ones)">
+  <step n="5" goal="Shared module blast radius and backward compatibility">
+    <note>A change to any shared/common/generic module is high-risk because it affects all consumers — not just the code in this PR. This step must always run when any such file is changed.</note>
+    <check-list id="blast-radius">
+      <item>Identify: is the changed file a shared/common/generic resource? (utility modules, shared libraries, base classes, common interfaces/headers, core services, shared data models, global state)</item>
+      <item>Consumer count: search for all files importing or using this module and list them. Any breaking change is a 🔴 BLOCKER regardless of consumer count — high consumer count amplifies urgency but is not the deciding factor.</item>
+      <item>Backward compatibility: is the public interface (function signatures, return shapes, exported types, event/message payloads, binary interfaces) backward compatible? If breaking: are ALL affected consumers updated in this same PR, or is there an explicit migration/deprecation plan?</item>
+      <item>New required parameters without defaults are breaking changes — even if the author only updated their own call sites.</item>
+      <item>Behavior change: does a behavioral change to a shared module produce unintended effects in contexts the author did not test (e.g., different runtime configurations, platforms, permission levels, or edge-case inputs)?</item>
+      <item>Versioning / deprecation: if the change is intentionally breaking, is there a deprecation path? Is the old interface preserved with a deprecation notice?</item>
+    </check-list>
+    <output-format>
+🔴 BLOCKER `src/common/HttpClient.ts` — `sendRequest()` param `timeout` removed. Breaking change.
+   Consumer blast radius: ~23 files import this module (see Impact Map).
+   Not all consumers updated in this PR: OrderService.ts, NotificationService.ts still pass `timeout`.
+   → Either restore `timeout` as optional/deprecated, or update all consumers in this PR.
+
+❓ QUESTION `src/auth/AuthService.ts` — Return shape changed (added `permissions`, removed `roles`).
+   Consumers outside diff: RouteGuard.ts, AdminMiddleware.ts, PermissionHelper.ts
+   → Ask author: "Were all consumers of AuthService tested with the new return shape? Was `roles` removal intentional?"
+    </output-format>
+  </step>
+
+  <step n="6" goal="SOLID principles (only flag real violations, not theoretical ones)">
     <check-list id="solid">
       <item>SRP: class/module doing more than one thing AND causing maintenance problems?</item>
       <item>OCP: existing code modified instead of extended (when extension was clearly better)?</item>
@@ -57,12 +84,13 @@ Focus: Layer violations | Coupling | SOLID | Codebase consistency
     <note>Only flag SOLID violations when they cause REAL maintainability or extensibility problems — not theoretical purity</note>
   </step>
 
-  <step n="6" goal="Compile and write findings">
-    <action>Group findings: Layer Violations | Coupling Issues | Consistency Problems | SOLID Violations</action>
+  <step n="7" goal="Compile and write findings">
+    <action>Group findings: Layer Violations | Coupling Issues | Consistency Problems | SOLID Violations | ❓ Questions for Author</action>
     <action>For each finding: reference the EXISTING pattern that should be followed instead</action>
     <action>Write findings to {output_file}</action>
     <action>Update {pr_context}: add 'architecture-review' to completed list</action>
     <output>🏗️ Architecture 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>