evizi-kit 1.0.0

package/kits/shared/docs/pr-review-agent.md

@@ -0,0 +1,501 @@
+# PR Review Skill
+
+## 1. Overview
+
+The **PR Review Skill** enables AI agents to automatically review pull request code changes and create inline comments directly on Git platforms. When a user requests a PR review, the AI agent invokes this skill to fetch PR code, analyze it against project standards, and post structured feedback.
+
+### Key Capabilities
+
+- **Automated PR Review**: Fetch and review pull request code automatically
+- **Multi-Platform Support**: Create inline comments on GitHub, Gitea, GitLab, and Bitbucket
+- **Quality Assurance**: Identify bugs, security issues, and code standard violations
+- **Notification Integration**: Send review results to Google Chat
+
+### How It Works
+
+When a user asks the AI agent to review a PR (e.g., "Review PR #42"), the agent:
+1. Recognizes the request and invokes the `pr-review` skill
+2. The skill handles the entire PR review workflow
+3. Returns results to the user
+
+## 2. Components
+
+| Component | File | Description |
+|-----------|------|-------------|
+| **PR Review Skill** | `.cursor/skills/pr-review/SKILL.md` or `.github/skills/pr-review/SKILL.md` | Skill definition and workflow for PR review process |
+| **Configuration File** | `.cursor/project.config.json` or `.github/project.config.json` | Project settings, platform config, and notification settings |
+| **Unified Dispatcher** | `scripts/post-review.py` | Single script with all platform logic embedded - transforms standard output and posts to Git platforms |
+| **Frontend Checklist** | `references/frontend.md` | 100+ checks for React, Vue, Angular, etc. |
+| **Backend Checklist** | `references/backend.md` | 70+ checks for API, database, security |
+| **Mobile Checklist** | `references/mobile.md` | 110+ checks for iOS and Android |
+| **Automation Checklist** | `references/automation.md` | 40+ checks for E2E tests |
+
+> **Note:** All file paths under `references/` and `scripts/` are relative to the skill directory (`.cursor/skills/pr-review/` or `.github/skills/pr-review/`).
+
+## 3. Setup Guide
+
+### Step 1: Create Configuration File
+
+Create `.cursor/project.config.json` (or `.github/project.config.json`) and customize:
+
+```json
+{
+  "baseBranch": "main",
+  "platform": "github",
+  "platformConfig": {
+    "github": {
+      "apiUrl": "https://api.github.com",
+      "owner": "your-org",
+      "repo": "your-repo"
+    },
+    "gitea": {
+      "apiUrl": "https://gitea.example.com/api/v1",
+      "owner": "your-org",
+      "repo": "your-repo"
+    },
+    "gitlab": {
+      "apiUrl": "https://gitlab.com/api/v4",
+      "projectId": "your-project-id"
+    },
+    "bitbucket": {
+      "apiUrl": "https://api.bitbucket.org/2.0",
+      "workspace": "your-workspace",
+      "repoSlug": "your-repo"
+    }
+  },
+  "enableCommentPosting": true,
+  "enableNotification": true
+}
+```
+
+**Configuration Options:**
+
+- `enableCommentPosting` (boolean, default: `true`) - Controls whether inline comments should be posted to the git platform
+- `enableNotification` (boolean, default: `false`) - Controls whether Google Chat notifications should be sent
+
+**Operation Modes:**
+
+The script supports flexible operation modes based on your configuration and token availability:
+
+1. **Full Mode** - Posts inline comments + sends notification
+   - Config: `enableCommentPosting: true`, `enableNotification: true`
+   - Requires: Platform token configured
+   - Use case: Production environment with full features
+
+2. **Comment-Only Mode** - Posts inline comments, no notification
+   - Config: `enableCommentPosting: true`, `enableNotification: false`
+   - Requires: Platform token configured
+   - Use case: CI/CD without notification spam
+
+3. **Notification-Only Mode** - Skips inline comments, only sends notification
+   - Config: `enableCommentPosting: false`, `enableNotification: true`
+   - OR: `enableCommentPosting: true` (but no token), `enableNotification: true`
+   - No platform token needed
+   - Use case: Testing, environments without git tokens, or notification-only setups
+
+### Step 2: Set Environment Variables
+
+The script uses standardized environment variable names. Configure based on your operation mode:
+
+**For Comment Posting (Required if `enableCommentPosting: true`):**
+
+```bash
+# GitHub
+export GITHUB_TOKEN="your-github-token"
+
+# GitLab
+export GITLAB_TOKEN="your-gitlab-token"
+
+# Gitea
+export GITEA_TOKEN="your-gitea-token"
+
+# Bitbucket
+export BITBUCKET_TOKEN="your-bitbucket-token"
+export BITBUCKET_USERNAME="your-bitbucket-username"
+```
+
+**For Notifications (Required if `enableNotification: true`):**
+
+```bash
+# Google Chat notifications
+export GOOGLE_CHAT_WEBHOOK_URL="your-webhook-url"
+```
+
+**Token Requirements by Mode:**
+
+| Mode | Platform Token | Webhook URL |
+|------|----------------|-------------|
+| Full Mode | ✅ Required | ✅ Required |
+| Comment-Only Mode | ✅ Required | ❌ Not needed |
+| Notification-Only Mode | ❌ Optional | ✅ Required |
+
+**Tip:** If you only want notifications without posting comments, you can skip the platform token entirely by setting `enableCommentPosting: false` in your config.
+
+### Step 3: Verify Git Setup
+
+```bash
+git remote -v
+git fetch origin
+```
+
+## 4. How to Use
+
+### Basic Workflow
+
+1. **User prompts the AI agent** with a PR review request (e.g., "Review PR #42")
+2. **AI agent recognizes the intent** and invokes the `pr-review` skill with the PR number
+3. **Skill executes the review workflow:**
+   - Fetches the PR code using Git commands
+   - Compares PR branch with base branch
+   - Detects tech stack and loads domain-specific checklist
+   - Analyzes code changes against the checklist
+   - Generates standard review output JSON (saves to `review.json` in project root)
+   - **Shows preview and asks for confirmation** (if `requireConfirmation: true`)
+   - Calls `python post-review.py` (if user confirms or auto-post enabled)
+   - Returns to the previous branch (cleanup)
+4. **post-review.py handles posting:**
+   - Reads platform from `project.config.json`
+   - Transforms standard review to platform-specific format
+   - Posts inline comments to Git platform via API
+   - Sends Google Chat notification (if `enableNotification` is true)
+   - Cleans up by deleting `review.json` after successful posting
+5. **AI agent returns results** to the user
+
+### Trigger Examples
+
+The AI agent will invoke the `pr-review` skill when it detects prompts like:
+
+```
+Review PR #42
+Please review pull request 123
+Can you check PR number 15?
+Review the changes in pull request #8
+Check this PR for issues: #99
+```
+
+### Git Commands Executed by Skill
+
+The skill executes these Git commands internally:
+
+```bash
+# Fetch the PR branch
+git fetch origin pull/[PR_NUMBER]/head:pr-[PR_NUMBER]
+
+# Checkout the PR branch
+git checkout pr-[PR_NUMBER]
+
+# Get list of changed files compared to base branch
+git diff ${BASE_BRANCH} --name-only
+
+# Get detailed line-by-line differences with 3 lines of context
+git diff ${BASE_BRANCH} --unified=3
+
+# After review is complete, return to previous branch
+git checkout -
+
+# Optionally delete the PR branch to clean up local workspace
+git branch -D pr-[PR_NUMBER]
+```
+
+Where `${BASE_BRANCH}` is read from `project.config.json` (e.g., `main`).
+
+**Note:** The `git checkout -` command returns you to the branch you were working on before the PR review started, ensuring your local workspace is restored to its original state.
+
+## 5. Confirmation Workflow
+
+### Interactive Mode (Default)
+
+When `requireConfirmation: true`, the skill shows a summary before posting:
+
+```
+📊 PR #42 Review Summary
+
+Found:
+- 2 Critical Issues ❌
+- 1 Warning ⚠️
+- 0 Suggestions 💡
+
+📝 Full review saved to: review.json
+📋 Review Status: REQUEST_CHANGES
+🎯 Platform: GitHub | Files: 5 | Total Comments: 3
+
+Do you want to post these 3 comments to GitHub? (yes/no)
+```
+
+**User Options:**
+- `yes` → Posts comments immediately
+- `no` → Saves review.json, doesn't post (user can manually post later)
+
+### Notification-Only Mode Examples
+
+When running in notification-only mode (no git token configured or `enableCommentPosting: false`):
+
+**Example 1: Testing without posting to PR**
+```json
+{
+  "platform": "github",
+  "enableCommentPosting": false,
+  "enableNotification": true
+}
+```
+Result: Review is generated, notification sent to Google Chat, but no comments posted to GitHub PR.
+
+**Example 2: Environment without git access**
+```json
+{
+  "platform": "github",
+  "enableCommentPosting": true,  // Would post if token available
+  "enableNotification": true
+}
+```
+With no `GITHUB_TOKEN` set: Script skips comment posting automatically, sends notification only.
+
+**Example 3: Dry run for testing**
+```bash
+python post-review.py --dry-run
+```
+Result: Shows transformed output for all platforms, doesn't post anything.
+
+## 6. Standard Review Output Format
+
+The PR Review Skill generates a **standard JSON format** that is platform-agnostic. The unified dispatcher script then transforms this standard output to the platform-specific API format.
+
+### Standard Output Schema
+
+```json
+{
+  "prNumber": 42,
+  "status": "REQUEST_CHANGES",
+  "summary": "Found 2 critical issues and 1 warning.",
+  "statistics": {
+    "filesReviewed": 5,
+    "totalComments": 3,
+    "criticalCount": 2,
+    "warningCount": 1,
+    "suggestionCount": 0
+  },
+  "comments": [
+    {
+      "path": "src/utils/api.ts",
+      "line": 15,
+      "category": "Security",
+      "severity": "critical",
+      "title": "Hardcoded API Key",
+      "body": "API keys should never be committed to the repository.",
+      "recommendation": "Use environment variables instead",
+      "codeSnippet": "const API_KEY = process.env.API_KEY;"
+    }
+  ],
+  "metadata": {
+    "reviewedAt": "2026-02-03T15:30:00Z",
+    "baseBranch": "main",
+    "sourceBranch": "feature/new-feature",
+    "commitSha": "abc123def456"
+  }
+}
+```
+
+### Comment Categories & Severity
+
+| Category | Severity | Description |
+|----------|----------|-------------|
+| `Security` | critical | Vulnerabilities, secrets, injection risks |
+| `Bug` | critical | Runtime errors, crashes, logic flaws |
+| `Pattern` | warning | Violations of project coding standards |
+| `Type` | warning | Type safety issues |
+| `Performance` | warning | Inefficient code patterns |
+| `Readability` | suggestion | Code clarity improvements |
+| `Naming` | suggestion | Naming convention violations |
+
+### Review Status Values
+
+| Status | When to Use |
+|--------|-------------|
+| `APPROVE` | No issues found, code looks good |
+| `REQUEST_CHANGES` | Critical issues or bugs found |
+| `COMMENT` | Only minor suggestions or warnings |
+
+## 7. Platform Transformation
+
+The unified dispatcher (`post-review.py`) contains embedded logic for all platforms, transforming the standard review output to each platform's specific API format.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              Standard Review Output (JSON)                  │
+│  - prNumber, status, summary, statistics, comments[]        │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│        post-review.py (Unified Dispatcher)                  │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │ 1. Reads platform from project.config.json            │  │
+│  │ 2. Reads standard environment variables               │  │
+│  │    (GITHUB_TOKEN, GITLAB_TOKEN, etc.)                 │  │
+│  │ 3. Transforms to platform-specific format             │  │
+│  │ 4. Posts to API using embedded platform logic         │  │
+│  │ 5. Sends Google Chat notification (if enabled)        │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                              │
+│  Embedded Platform Handlers:                                │
+│  ┌──────────────┬──────────────┬──────────────┬──────────┐  │
+│  │ GitHub       │ Gitea        │ GitLab       │ Bitbucket│  │
+│  ├──────────────┼──────────────┼──────────────┼──────────┤  │
+│  │ line → line  │ line →       │ line →       │ line →   │  │
+│  │ side: RIGHT  │ new_position │ position.    │ inline.to│  │
+│  │ event:       │ event:       │ new_line     │ content. │  │
+│  │ APPROVE      │ APPROVED     │ + SHA values │ raw      │  │
+│  └──────────────┴──────────────┴──────────────┴──────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Platform API Differences
+
+| Feature | GitHub | Gitea | GitLab | Bitbucket |
+|---------|--------|-------|--------|-----------|
+| **Approval event** | `APPROVE` | `APPROVED` | Separate `/approve` endpoint | Separate `/approve` endpoint |
+| **Line field** | `line` | `new_position` | `position.new_line` | `inline.to` |
+| **Single review** | ✅ Yes | ✅ Yes | ❌ No (separate discussions) | ❌ No (separate comments) |
+| **Requires SHA** | ❌ No | ❌ No | ✅ Yes (base, head, start) | ❌ No |
+
+### Usage
+
+```bash
+# Post review (reads review.json from project root, platform from config)
+python {PR_REVIEW_SKILL_PATH}/scripts/post-review.py
+
+# Dry run mode (transform only, do not post)
+python {PR_REVIEW_SKILL_PATH}/scripts/post-review.py --dry-run
+```
+
+Where `{PR_REVIEW_SKILL_PATH}` is the absolute path to the pr-review skill folder (e.g., `.cursor/skills/pr-review` or `.github/skills/pr-review`).
+
+**Note:** The script automatically:
+- Reads `review.json` from the project root
+- Detects platform from `project.config.json` (searches `.github/` or `.cursor/`)
+- Uses standard environment variable names (GITHUB_TOKEN, GITLAB_TOKEN, etc.)
+- Posts comments if `enableCommentPosting` is `true` and platform token is available
+- Sends notification if `enableNotification` is `true` in config
+- Supports notification-only mode when no git token is configured
+- Deletes `review.json` file after successful posting or notification (file cleanup)
+- Outputs JSON to stdout, errors to stderr (optimized for AI usage)
+
+**Git Cleanup:** After the review workflow completes, the skill automatically returns to your previous branch using `git checkout -`, restoring your workspace to its original state.
+
+## 8. Tech Stack Detection & Checklists
+
+The PR review skill automatically detects the project type and applies the appropriate checklist (same as self-review):
+
+### Detection Logic
+
+| Tech Stack | File Extensions | Checklist Applied |
+|------------|----------------|-------------------|
+| **Frontend** | `.tsx`, `.jsx`, `.vue`, `.css`, `package.json` | `references/frontend.md` (100+ checks) |
+| **Backend** | `.java`, `.go`, `.py` (API), `.sql` | `references/backend.md` (70+ checks) |
+| **Mobile** | `.swift`, `.kt`, `Podfile`, `AndroidManifest.xml` | `references/mobile.md` (110+ checks) |
+| **Automation** | `.spec.ts`, `Selenium`, `Test.java` | `references/automation.md` (40+ checks) |
+
+### Checklist Highlights
+
+**Frontend** - Performance, State Management, Accessibility, Security, SEO, Testing  
+**Backend** - API Design, Database, Security (OWASP), Performance, Observability, Testing  
+**Mobile** - Threading, Lifecycle, Memory, Security, Networking, Platform-Specific  
+**Automation** - Stability, Selectors, Isolation, Error Handling, CI Readiness
+
+### Severity Classification
+
+| Severity | Review Status | Description |
+|----------|---------------|-------------|
+| **critical** | `REQUEST_CHANGES` | Bugs, security vulnerabilities, breaking changes |
+| **warning** | `COMMENT` | Code quality, maintainability, performance issues |
+| **suggestion** | `COMMENT` | Best practices, patterns, optimizations |
+
+## 9. Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           User Request                                   │
+│                    "Review PR #42"                                       │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        AI Agent (Cursor/Copilot/Claude/etc)             │
+│  ┌───────────────────────────────────────────────────────────────────┐  │
+│  │ 1. Parse user request to extract PR number                        │  │
+│  │ 2. Recognize intent: PR review request                            │  │
+│  │ 3. Invoke pr-review skill with PR number parameter                │  │
+│  └───────────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         pr-review Skill                                  │
+│  ┌───────────────────────────────────────────────────────────────────┐  │
+│  │ 1. Read configuration from project.config.json                    │  │
+│  │ 2. Fetch PR code: git fetch origin pull/42/head:pr-42             │  │
+│  │ 3. Checkout PR: git checkout pr-42                                │  │
+│  │ 4. Get diff: git diff main --unified=3                            │  │
+│  │ 5. Detect tech stack and load domain-specific checklist           │  │
+│  │ 6. Analyze code changes against checklist + project standards     │  │
+│  │ 7. Generate STANDARD review output JSON (save to review.json)     │  │
+│  │ 8. Show preview and ask for confirmation (if required)            │  │
+│  │ 9. Call: python post-review.py (if confirmed/auto)                │  │
+│  │ 10. Cleanup: git checkout - (return to previous branch)           │  │
+│  └───────────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│              post-review.py (Unified Dispatcher)                         │
+│  ┌───────────────────────────────────────────────────────────────────┐  │
+│  │ 1. Read project.config.json                                       │  │
+│  │ 2. Detect platform (github, gitea, gitlab, bitbucket)             │  │
+│  │ 3. Read standard env vars (GITHUB_TOKEN, GITLAB_TOKEN, etc.)      │  │
+│  │ 4. Transform using embedded platform logic → POST to API          │  │
+│  │ 5. Check enableNotification → Send Google Chat notification       │  │
+│  │ 6. Cleanup: Delete review.json file after successful posting      │  │
+│  └───────────────────────────────────────────────────────────────────┘  │
+│                                                                          │
+│  ┌───────────────────────────────────────────────────────────────────┐  │
+│  │ Embedded Platform Handlers:                                       │  │
+│  │ - post_github_review()   → GitHub Reviews API                     │  │
+│  │ - post_gitea_review()    → Gitea Reviews API                      │  │
+│  │ - post_gitlab_review()   → GitLab Discussions API                 │  │
+│  │ - post_bitbucket_review() → Bitbucket Comments API                │  │
+│  └───────────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      Return Results to AI Agent                          │
+│             AI Agent communicates outcome to user                        │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## 10. References
+
+| Resource | Possible Locations |
+|----------|-------------------|
+| **Skill Definition** | `.cursor/skills/pr-review/SKILL.md` or `.github/skills/pr-review/SKILL.md` |
+| **Configuration File** | `.cursor/project.config.json` or `.github/project.config.json` |
+| **Unified Dispatcher** | `{SKILL_PATH}/scripts/post-review.py` |
+| **Frontend Checklist** | `{SKILL_PATH}/references/frontend.md` |
+| **Backend Checklist** | `{SKILL_PATH}/references/backend.md` |
+| **Mobile Checklist** | `{SKILL_PATH}/references/mobile.md` |
+| **Automation Checklist** | `{SKILL_PATH}/references/automation.md` |
+
+> **Note:** `{SKILL_PATH}` refers to `.cursor/skills/pr-review/` or `.github/skills/pr-review/` depending on your project setup.
+
+## 11. Skill Invocation
+
+The AI agent automatically invokes this skill when it detects PR review requests in the user's prompt. The skill is registered in the agent's skill registry and can be triggered by patterns like:
+
+- "Review PR #[number]"
+- "Check pull request [number]"
+- "Analyze PR [number]"
+- "Review pull request #[number]"
+
+No manual skill invocation is required - the AI agent handles skill selection based on user intent.