@snipcodeit/mgw 0.1.3 → 0.2.1

package/commands/review.md

@@ -1,23 +1,35 @@
 ---
 name: mgw:review
-description: Review and classify new comments on a GitHub issue since last triage
-argument-hint: "<issue-number>"
+description: Review GitHub comments on issues OR perform deep PR analysis
+argument-hint: "<issue-number | pr-number | pr-url> [--pr]"
 allowed-tools:
   - Bash
   - Read
   - Write
   - Edit
+  - Glob
+  - Grep
   - Task
   - AskUserQuestion
 ---
 
 <objective>
-Standalone comment review for a triaged issue. Fetches new comments posted since
-triage, classifies them (material/informational/blocking), and updates the state
-file accordingly.
+Two-mode review command:
 
-Use this when you want to check for stakeholder feedback before running the pipeline,
-or to review comments on a blocked issue before unblocking it.
+**Mode 1: Issue Comment Review (default)**
+Review and classify new comments on a GitHub issue since last triage. Fetches new comments,
+classifies them (material/informational/blocking/resolution), and updates state.
+
+Use this when checking for stakeholder feedback before running the pipeline, or reviewing
+comments on a blocked issue.
+
+**Mode 2: PR Deep Review (with --pr flag)**
+Comprehensive PR review that mimics a senior engineer's code review process. Problem-solving
+orchestration with high autonomy to analyze, question assumptions, and provide architectural
+guidance across five dimensions.
+
+This is intentionally different from execution orchestration — the reviewer has space to think
+deeply rather than produce code.
 </objective>
 
 <execution_context>
@@ -28,82 +40,149 @@ or to review comments on a blocked issue before unblocking it.
 </execution_context>
 
 <context>
-Issue number: $ARGUMENTS
-
-State: .mgw/active/ (must exist — issue must be triaged first)
+Reference: $ARGUMENTS (issue number, PR number, or PR URL)
+Flags: --pr forces PR deep review mode
 </context>
 
 <process>
 
-<step name="validate_and_load">
-**Validate input and load state:**
+<step name="detect_mode">
+**Detect review mode:**
 
 ```bash
 REPO_ROOT=$(git rev-parse --show-toplevel)
-```
 
-Parse $ARGUMENTS for issue number. If missing:
-```
-AskUserQuestion(
-  header: "Issue Number Required",
-  question: "Which issue number do you want to review comments for?",
-  followUp: "Enter the GitHub issue number (e.g., 42)"
-)
-```
+# Parse arguments
+REFERENCE="$ARGUMENTS"
+PR_MODE=false
 
-Load state file: `${REPO_ROOT}/.mgw/active/${ISSUE_NUMBER}-*.json`
+# Check for --pr flag
+if [[ "$REFERENCE" =~ --pr[[:space:]]|$ ]]; then
+  PR_MODE=true
+  REFERENCE=$(echo "$REFERENCE" | sed 's/--pr//g' | xargs)
+fi
 
-If no state file exists:
+# Determine if PR or issue based on format
+if [[ "$REFERENCE" =~ ^https?://github\.com/[^/]+/[^/]+/pull/ ]]; then
+  # URL - determine if issue or PR
+  if [[ "$REFERENCE" =~ /pull/ ]]; then
+    PR_MODE=true
+  fi
+  PR_REF="$REFERENCE"
+elif [[ "$REFERENCE" =~ ^https?://github\.com/[^/]+/[^/]+/issues/ ]]; then
+  PR_MODE=false
+  ISSUE_REF="$REFERENCE"
+elif [[ "$REFERENCE" =~ ^[0-9]+$ ]]; then
+  # Number - check if it's a PR or issue by testing
+  # Default to issue comment review (safer default)
+  PR_MODE=false
+  NUMBER="$REFERENCE"
+else
+  # Default: issue comment review
+  PR_MODE=false
+  NUMBER="$REFERENCE"
+fi
+
+# Export for later steps
+export PR_MODE
 ```
-Issue #${ISSUE_NUMBER} hasn't been triaged yet.
-Run /mgw:issue ${ISSUE_NUMBER} first, then review comments.
+</step>
+
+<step name="route_to_mode">
+**Route to appropriate review mode:**
+
+If PR_MODE=true → Jump to "pr_review" section below
+If PR_MODE=false → Continue to "issue_comments" section
+
+</step>
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MODE 1: ISSUE COMMENT REVIEW (original functionality, optimized)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+<step name="issue_validate">
+**Validate issue and load state:**
+
+```bash
+# Parse issue number
+if [ -n "$NUMBER" ]; then
+  ISSUE_NUMBER="$NUMBER"
+elif [ -n "$ISSUE_REF" ]; then
+  ISSUE_NUMBER=$(echo "$ISSUE_REF" | grep -oE '[0-9]+$' | head -1)
+fi
+
+if [ -z "$ISSUE_NUMBER" ]; then
+  AskUserQuestion(
+    header: "Issue Number Required",
+    question: "Which issue number do you want to review comments for?",
+    followUp: "Enter the GitHub issue number (e.g., 42)"
+  )
+  ISSUE_NUMBER="$ANSWER"
+fi
+
+# Verify issue exists
+gh issue view "$ISSUE_NUMBER" >/dev/null 2>&1 || {
+  echo "Error: Issue #${ISSUE_NUMBER} not found."
+  exit 1
+}
+
+# Check if issue is triaged (state file exists)
+if [ ! -f "${REPO_ROOT}/.mgw/active/${ISSUE_NUMBER}-*.json" ]; then
+  echo "Issue #${ISSUE_NUMBER} hasn't been triaged yet."
+  echo "Run /mgw:issue ${ISSUE_NUMBER} first, then review comments."
+  # Still allow review but warn
+fi
 ```
 </step>
 
-<step name="fetch_comments">
-**Fetch current comment state from GitHub:**
+<step name="issue_fetch_comments">
+**Fetch current comment state:**
 
 ```bash
 CURRENT_COMMENTS=$(gh issue view $ISSUE_NUMBER --json comments --jq '.comments | length' 2>/dev/null || echo "0")
-STORED_COMMENTS="${triage.last_comment_count}"
+STORED_COMMENTS=0
 
-if [ -z "$STORED_COMMENTS" ] || [ "$STORED_COMMENTS" = "null" ]; then
-  STORED_COMMENTS=0
+# Try to get stored count from state file
+if [ -f "${REPO_ROOT}/.mgw/active/${ISSUE_NUMBER}-"*".json" ]; then
+  STATE_FILE=$(ls "${REPO_ROOT}/.mgw/active/${ISSUE_NUMBER}-"*".json" | head -1)
+  STORED_COMMENTS=$(jq -r '.triage.last_comment_count // 0' "$STATE_FILE" 2>/dev/null || echo "0")
 fi
 
 NEW_COUNT=$(($CURRENT_COMMENTS - $STORED_COMMENTS))
-```
 
-If no new comments (`NEW_COUNT <= 0`):
-```
-No new comments on #${ISSUE_NUMBER} since triage (${STORED_COMMENTS} comments at triage, ${CURRENT_COMMENTS} now).
-```
-Stop.
+if [ "$NEW_COUNT" -le 0 ]; then
+  echo "No new comments on #${ISSUE_NUMBER} since triage (${STORED_COMMENTS} stored, ${CURRENT_COMMENTS} now)."
+  echo "Done."
+  exit 0
+fi
 
-If new comments exist, fetch them:
-```bash
+# Fetch new comments
 NEW_COMMENTS=$(gh issue view $ISSUE_NUMBER --json comments \
   --jq "[.comments[-${NEW_COUNT}:]] | .[] | {author: .author.login, body: .body, createdAt: .createdAt}" 2>/dev/null)
+
+# Get issue context for classification
+ISSUE_TITLE=$(gh issue view $ISSUE_NUMBER --json title -q '.title')
+PIPELINE_STAGE=$(jq -r '.pipeline_stage // "new"' "$STATE_FILE" 2>/dev/null || echo "new")
+GSD_ROUTE=$(jq -r '.gsd_route // "unknown"' "$STATE_FILE" 2>/dev/null || echo "unknown")
 ```
 </step>
 
-<step name="classify_comments">
-**Spawn classification agent:**
+<step name="issue_classify">
+**Spawn classification agent (lightweight):**
 
 ```
 Task(
   prompt="
-<files_to_read>
-- ./CLAUDE.md (Project instructions — if exists, follow all guidelines)
+KR|<files_to_read>
+ST|- ./CLAUDE.md (Project instructions — if exists)
 </files_to_read>
 
 Classify new comments on GitHub issue #${ISSUE_NUMBER}.
 
 <issue_context>
-Title: ${issue_title}
-Current pipeline stage: ${pipeline_stage}
-GSD Route: ${gsd_route}
-Triage scope: ${triage.scope}
+Title: ${ISSUE_TITLE}
+Current pipeline stage: ${PIPELINE_STAGE}
+GSD Route: ${GSD_ROUTE}
 </issue_context>
 
 <new_comments>
@@ -111,150 +190,211 @@ ${NEW_COMMENTS}
 </new_comments>
 
 <classification_rules>
-Classify each comment (and the overall batch) into ONE of:
-
-- **material** — Comment changes scope, requirements, acceptance criteria, or design.
-  Examples: 'Actually we also need to handle X', 'Changed the requirement to Y',
-  'Don't forget about edge case Z'.
+- **material** — Comment changes scope, requirements, acceptance criteria, or design
+- **informational** — Status update, acknowledgment, question, +1
+- **blocking** — Explicit instruction to stop or wait
+- **resolution** — Comment indicates a previously identified blocker has been resolved
 
-- **informational** — Status update, acknowledgment, question that doesn't change scope, +1.
-  Examples: 'Looks good', 'Thanks for picking this up', 'What's the ETA?', '+1'.
-
-- **blocking** — Explicit instruction to stop or wait. Must contain clear hold language.
-  Examples: 'Don't work on this yet', 'Hold off', 'Blocked by external dependency',
-  'Wait for design review'.
-
-- **resolution** — Comment indicates a previously identified blocker or issue has been resolved.
-  Examples: 'The dependency has been updated', 'Security review complete — approved',
-  'Added the missing acceptance criteria', 'Updated the issue with more detail',
-  'Fixed the blocking issue in #42'.
-
-If ANY comment in the batch is blocking, overall classification is blocking.
-If ANY comment is resolution (and none blocking), overall classification is resolution.
-If ANY comment is material (and none blocking/resolution), overall classification is material.
-Otherwise, informational.
+Priority: blocking > resolution > material > informational
 </classification_rules>
 
 <output_format>
 Return ONLY valid JSON:
 {
   \"classification\": \"material|informational|blocking|resolution\",
-  \"reasoning\": \"Brief explanation of why this classification was chosen\",
-  \"per_comment\": [
-    {
-      \"author\": \"username\",
-      \"snippet\": \"first 100 chars of comment\",
-      \"classification\": \"material|informational|blocking|resolution\"
-    }
-  ],
-  \"new_requirements\": [\"list of new requirements if material, empty array otherwise\"],
-  \"blocking_reason\": \"reason if blocking, empty string otherwise\",
-  \"resolved_blocker\": \"description of what was resolved, empty string otherwise\"
+  \"reasoning\": \"Brief explanation\",
+  \"per_comment\": [{\"author\": \"username\", \"snippet\": \"first 100 chars\", \"classification\": \"...\"}],
+  \"new_requirements\": [],
+  \"blocking_reason\": \"\",
+  \"resolved_blocker\": \"\"
 }
 </output_format>
-",
+  ",
   subagent_type="general-purpose",
   description="Classify comments on #${ISSUE_NUMBER}"
 )
 ```
 </step>
 
-<step name="present_and_act">
+<step name="issue_present_and_act">
 **Present classification and offer actions:**
 
-Display the classification result:
-
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MGW ► COMMENT REVIEW — #${ISSUE_NUMBER}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-New comments: ${NEW_COUNT} since triage
+New comments: ${NEW_COUNT}
 Classification: ${classification}
 Reasoning: ${reasoning}
 
-${per_comment_table}
-
-${if material: 'New requirements detected:\n' + new_requirements}
-${if blocking: 'Blocking reason: ' + blocking_reason}
+Actions based on classification:
+- informational: Update last_comment_count
+- material: Update with new requirements
+- blocking: Option to block pipeline
+- resolution: Option to re-triage
 ```
 
-Offer actions based on classification:
+</step>
 
-**If informational:**
-```
-AskUserQuestion(
-  header: "Informational Comments",
-  question: "Mark comments as reviewed and update state?",
-  options: [
-    { label: "Yes", description: "Update last_comment_count, continue" },
-    { label: "No", description: "Keep current state, don't update count" }
-  ]
-)
+# ═══════════════════════════════════════════════════════════════════════════════
+# MODE 2: PR DEEP REVIEW (new functionality)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+<step name="pr_review">
+**PR Deep Review Mode:**
+
+This section handles comprehensive PR analysis. Jump here if PR_MODE=true.
+
+<step name="pr_validate">
+**Validate and parse PR reference:**
+
+```bash
+# Parse PR number from various formats
+if [[ "$REFERENCE" =~ ^https?://github\.com/[^/]+/[^/]+/pull/([0-9]+) ]]; then
+  PR_NUMBER="${BASH_REMATCH[1]}"
+elif [[ "$REFERENCE" =~ ^[0-9]+$ ]] && "$PR_MODE" = true; then
+  PR_NUMBER="$REFERENCE"
+else
+  # Try current branch
+  CURRENT_BRANCH=$(git branch --show-current)
+  PR_NUMBER=$(gh pr view "$CURRENT_BRANCH" --json number -q '.number' 2>/dev/null || echo "")
+fi
+
+# Verify PR exists
+gh pr view "$PR_NUMBER" >/dev/null 2>&1 || {
+  echo "Error: PR #${PR_NUMBER} not found."
+  exit 1
+}
 ```
-If yes: update `triage.last_comment_count` to $CURRENT_COMMENTS in state file.
+</step>
 
-**If material:**
+<step name="pr_fetch_details">
+**Fetch comprehensive PR details:**
+
+```bash
+PR_DATA=$(gh pr view "$PR_NUMBER" --json number,title,body,state,url,baseRefName,headRefName,author,createdAt,changedFiles)
+PR_TITLE=$(echo "$PR_DATA" | jq -r '.title')
+PR_BODY=$(echo "$PR_DATA" | jq -r '.body // ""')
+PR_STATE=$(echo "$PR_DATA" | jq -r '.state')
+PR_URL=$(echo "$PR_DATA" | jq -r '.url')
+PR_BASE=$(echo "$PR_DATA" | jq -r '.baseRefName')
+PR_HEAD=$(echo "$PR_DATA" | jq -r '.headRefName')
+PR_AUTHOR=$(echo "$PR_DATA" | jq -r '.author.login')
+FILE_COUNT=$(echo "$PR_DATA" | jq -r '.changedFiles')
+
+# Find linked issue
+LINKED_ISSUE=$(echo "$PR_BODY" | grep -oE '(closes|fixes|addresses|resolves) #[[:digit:]]+' | grep -oE '[[:digit:]]+' | head -1)
+
+if [ -n "$LINKED_ISSUE" ]; then
+  ISSUE_TITLE=$(gh issue view "$LINKED_ISSUE" --json title -q '.title' 2>/dev/null || echo "")
+fi
 ```
-AskUserQuestion(
-  header: "Material Comments Detected",
-  question: "How should MGW handle the scope change?",
-  options: [
-    { label: "Acknowledge and continue", description: "Update state with new requirements, keep current route" },
-    { label: "Re-triage", description: "Run /mgw:issue to re-analyze with new context" },
-    { label: "Ignore", description: "Don't update state" }
-  ]
-)
+</step>
+
+<step name="pr_prepare_context">
+**Prepare review directory:**
+
+```bash
+REVIEW_DIR="${REPO_ROOT}/.mgw/reviews"
+mkdir -p "$REVIEW_DIR"
+
+REVIEW_ID="pr-${PR_NUMBER}-$(date +%Y%m%d-%H%M%S)"
+REVIEW_STATE_FILE="${REVIEW_DIR}/${REVIEW_ID}.json"
+
+cat > "$REVIEW_STATE_FILE" << EOF
+{
+  \"review_id\": \"${REVIEW_ID}\",
+  \"pr_number\": ${PR_NUMBER},
+  \"pr_title\": \"${PR_TITLE}\",
+  \"pr_url\": \"${PR_URL}\",
+  \"linked_issue\": ${LINKED_ISSUE:-null},
+  \"reviewer\": \"${PR_AUTHOR}\",
+  \"created_at\": \"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\",
+  \"status\": \"in_progress\",
+  \"mode\": \"deep_pr_review\"
+}
+EOF
 ```
-If acknowledge: update `triage.last_comment_count` and store new_requirements in state.
-If re-triage: suggest running `/mgw:issue ${ISSUE_NUMBER}` to re-triage.
+</step>
+
+<step name="pr_spawn_reviewer">
+**Spawn deep review agent:**
 
-**If blocking:**
 ```
-AskUserQuestion(
-  header: "Blocking Comment Detected",
-  question: "Block the pipeline for this issue?",
-  options: [
-    { label: "Block", description: "Set pipeline_stage to 'blocked'" },
-    { label: "Override", description: "Ignore blocker, keep current stage" },
-    { label: "Review", description: "I'll review the comments manually" }
-  ]
+Task(
+  prompt="
+KR|<files_to_read>
+ST|- ./CLAUDE.md (Project instructions — if exists)
+</files_to_read>
+
+You are a senior code reviewer. Perform deep PR analysis addressing five dimensions:
+
+## 1. TEST THIS PR
+Run tests, build, verify functionality works.
+
+## 2. WHY DO WE NEED THIS?
+Analyze rationale vs linked issue #${LINKED_ISSUE:-none}.
+
+## 3. STATED INTENT VS ACTUAL CHANGES
+Compare PR claims vs actual code changes.
+
+## 4. IMPACT ANALYSIS
+Side effects, dependencies, patterns, security, performance.
+
+## 5. ARCHITECTURAL REVIEW
+Alternatives, design consistency, root cause vs symptom.
+
+## PR Context
+- **PR:** #${PR_NUMBER} - ${PR_TITLE}
+- **Author:** ${PR_AUTHOR}
+- **Base:** ${PR_BASE} ← ${PR_HEAD}
+- **Files:** ${FILE_COUNT}
+- **Linked Issue:** ${LINKED_ISSUE:-none} ${ISSUE_TITLE:+- ${ISSUE_TITLE}}
+
+## Output
+
+Write to ${REVIEW_STATE_FILE}:
+
+node -e \"
+const fs = require('fs');
+const state = JSON.parse(fs.readFileSync('${REVIEW_STATE_FILE}', 'utf-8'));
+state.analyses = {
+  test_results: { tests_passed: true/false, build_passed: true/false, summary: '...' },
+  rationale: { problem_identified: '...', problem_valid: true/false, priority: 'high/medium/low' },
+  intent_vs_implementation: { gaps: [], scope_creep: [] },
+  impact_analysis: { side_effects: [], dependencies: [], pattern_violations: [] },
+  architectural_review: { approach_correct: true/false, alternatives: [], recommendations: [] },
+  overall_verdict: { recommendation: 'approve/request_changes/needs_discussion', confidence: 'high/medium/low', summary: '...', blockers: [], concerns: [] }
+};
+state.status = 'completed';
+state.completed_at = new Date().toISOString();
+fs.writeFileSync('${REVIEW_STATE_FILE}', JSON.stringify(state, null, 2));
+console.log('Review complete.');
+\"
+  ",
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Deep review PR #${PR_NUMBER}"
 )
 ```
-If block: update `pipeline_stage = "blocked"` and `triage.last_comment_count` in state.
-If override: update `triage.last_comment_count` only, keep pipeline_stage.
+</step>
 
-**If resolution:**
-```
-AskUserQuestion(
-  header: "Blocker Resolution Detected",
-  question: "A previous blocker appears to be resolved. Re-triage this issue?",
-  options: [
-    { label: "Re-triage", description: "Run /mgw:issue to re-analyze with updated context" },
-    { label: "Acknowledge", description: "Update comment count, keep current pipeline stage" },
-    { label: "Ignore", description: "Don't update state" }
-  ]
-)
+<step name="pr_present">
+**Present review results:**
+
+```bash
+REVIEW_DATA=$(cat "$REVIEW_STATE_FILE")
+# Parse and display results in structured format
 ```
-If re-triage:
-  - Update `triage.last_comment_count`
-  - Suggest: "Run `/mgw:issue ${ISSUE_NUMBER}` to re-triage with the resolved context."
-  - If pipeline_stage is "blocked" or "needs-info" or "needs-security-review", note:
-    "Re-triage will re-evaluate gates and may unblock the pipeline."
-If acknowledge:
-  - Update `triage.last_comment_count`
-  - Keep current pipeline_stage
 </step>
 
 </process>
 
 <success_criteria>
-- [ ] Issue state loaded from .mgw/active/
-- [ ] Current comment count fetched from GitHub
-- [ ] New comments identified (delta from stored count)
-- [ ] Classification agent spawned and returned structured result
-- [ ] Classification presented to user with per-comment breakdown
-- [ ] User chose action (acknowledge/re-triage/block/ignore)
-- [ ] State file updated according to user choice
-- [ ] Resolution classification type supported with re-triage prompt
+- [ ] Mode detection works (issue comments vs PR deep review)
+- [ ] Issue comment classification still functions
+- [ ] PR deep review analyzes five dimensions
+- [ ] State properly separated (.mgw/reviews/ for PR, .mgw/active/ for issues)
+- [ ] Both modes preserve their respective contexts
 </success_criteria>