evizi-kit 1.0.0

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

@@ -0,0 +1,246 @@
+# Self Review Skill
+
+## 1. Overview
+
+The **Self Review Skill** enables AI agents to automatically review code changes between the current Git branch and a configured target branch, providing a clear **Ready/Not Ready verdict** for PR creation. When a user requests a self-review, the AI agent invokes this skill to analyze changes and identify issues before creating pull requests.
+
+### Key Capabilities
+
+- **Pre-PR Verification**: Clear verdict on whether code is ready for pull request
+- **Automated Code Analysis**: Review code changes using Git diff
+- **Table-Based Reporting**: Scannable format for quick issue verification
+- **Quality Assurance**: Identify critical bugs, security issues, and code quality concerns
+- **Domain-Specific Review**: Applies tech stack-specific checklists (Frontend, Backend, Mobile, Automation)
+
+### How It Works
+
+When a user asks the AI agent to review their code (e.g., "Self-review for PROJ-123" or "Check my code before PR"), the agent:
+1. Recognizes the request and invokes the `self-review` skill
+2. The skill handles the entire code review workflow
+3. Returns a verdict and detailed report to the user
+
+## 2. Components
+
+| Component | File | Description |
+|-----------|------|-------------|
+| **Self Review Skill** | `.cursor/skills/self-review/SKILL.md` or `.github/skills/self-review/SKILL.md` | Skill definition and workflow for self-review process |
+| **Configuration File** | `.cursor/project.config.json` or `.github/project.config.json` | Project settings and target branch |
+| **Issue Template** | `templates/issues.template.md` | Table-based report format with verdict |
+| **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:** Paths for templates and references are relative to the skill directory (`.cursor/skills/self-review/` or `.github/skills/self-review/`).
+
+## 3. Setup Guide
+
+### Step 1: Create Configuration File
+
+Create `.cursor/project.config.json` (or `.github/project.config.json`):
+
+```json
+{
+  "baseBranch": "main"
+}
+```
+
+### Step 2: Verify Git Setup
+
+```bash
+git fetch origin
+git branch -a | grep main
+```
+
+## 4. How to Use
+
+### Basic Workflow
+
+1. **Make changes on your feature branch**
+2. **User prompts the AI agent** with a self-review request (e.g., "Self-review for PROJ-123")
+3. **AI agent recognizes the intent** and invokes the `self-review` skill
+4. **Skill executes the review workflow:**
+   - Reads configuration from `project.config.json` (searches `.cursor/` or `.github/`)
+   - Runs Git commands to compare current branch with target branch
+   - Detects tech stack and loads domain-specific checklist from `references/`
+   - Analyzes changes using the checklist
+   - Generates table-based report with verdict using `templates/issues.template.md`
+   - Saves review to `issues.md`
+5. **AI agent returns verdict** to the user: ✅ Ready / ⚠️ Ready with Warnings / ❌ Not Ready
+
+### Trigger Examples
+
+The AI agent will invoke the `self-review` skill when it detects prompts like:
+
+```
+Self-review for my code changes
+Check my code before PR
+Ready for PR?
+Review my changes
+self-review
+Is my code ready for PR?
+```
+
+### Verdict Logic
+
+The agent provides a clear decision on PR readiness:
+
+| Verdict | Criteria | Meaning |
+|---------|----------|---------|
+| **✅ Ready to Create PR** | Zero critical issues | Code is ready for pull request |
+| **⚠️ Ready with Warnings** | Zero critical, has warnings/suggestions | Can create PR, but consider addressing warnings |
+| **❌ Not Ready for PR** | One or more critical issues | Must fix critical issues before PR |
+
+### Report Format
+
+The agent generates a **table-based report** (no code snippets) with:
+
+1. **Verdict Section** - Clear Ready/Not Ready decision with message
+2. **Summary Table** - Files reviewed and issue counts by severity
+3. **Files Reviewed Table** - Each file's status, lines changed, and issue count
+4. **Issues Tables** - Critical, Warnings, and Suggestions in separate tables
+   - Each issue includes: #, File, Line, Category, Issue description, Recommendation
+
+**Template Variables:**
+- `[CURRENT_BRANCH]` - The current Git branch
+- `[TARGET_BRANCH]` - The target branch (from config)
+- `[VERDICT_STATUS]` - Ready/Not Ready status with icon
+- `[VERDICT_MESSAGE]` - Explanation message
+- `[FILES_COUNT]`, `[CRITICAL_COUNT]`, `[WARNING_COUNT]`, `[SUGGESTION_COUNT]` - Statistics
+- `[FILE_PATH]`, `[STATUS_ICON]`, `[ADDED]`, `[REMOVED]`, `[ISSUE_COUNT]` - Per-file details
+- `[ISSUE_ID]`, `[LINE_NUMBER]`, `[CATEGORY]`, `[ISSUE_DESCRIPTION]`, `[FIX_RECOMMENDATION]` - Per-issue details
+
+**Why No Code Snippets?**
+- Prevents confusion (AI uses git diff for context)
+- Faster scanning and verification
+- Focuses on actionable specifications
+- Cleaner, more compact format
+
+### Severity Levels
+
+| Level | Icon | Description | Examples |
+|-------|------|-------------|----------|
+| **Critical** | ❌ | Must fix before PR | Bugs, security vulnerabilities, breaking changes |
+| **Warning** | ⚠️ | Should fix | Code quality, readability, maintainability issues |
+| **Suggestion** | 💡 | Nice to have | Patterns, optimizations, best practices |
+
+### Git Commands Executed by Skill
+
+The skill executes these Git commands internally:
+
+```bash
+# Get list of changed files
+git diff <target-branch> --name-only
+
+# Get detailed line-by-line differences with 3 lines of context
+git diff <target-branch> --unified=3
+```
+
+Where `<target-branch>` is the value of `baseBranch` from `project.config.json` (e.g., `main`).
+
+## 5. Tech Stack Detection & Checklists
+
+The skill automatically detects your project type and applies the appropriate checklist:
+
+### 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
+
+## 6. Review Rules
+
+The self-review skill follows strict guidelines when analyzing code:
+
+### DO:
+- ✅ Read entire diff before analyzing
+- ✅ Provide specific line numbers in tables
+- ✅ Give actionable fix suggestions in "Recommendation" column
+- ✅ Generate clear verdict based on critical issues count
+- ✅ Use table format for all issues (no code snippets)
+- ✅ Set verdict to "❌ Not Ready" if any critical issues exist
+
+### DO NOT:
+- ❌ Include code snippets (AI will use git diff for context)
+- ❌ Report issues in excluded files
+- ❌ Report style-only issues as critical
+- ❌ Exaggerate severity levels
+- ❌ Approve (✅ Ready) when critical issues exist
+
+### Verdict Logic:
+- **✅ Ready to Create PR** - Zero critical issues
+- **⚠️ Ready with Warnings** - Zero critical, some warnings/suggestions
+- **❌ Not Ready for PR** - One or more critical issues
+
+## 7. Example Report Output
+
+```markdown
+# Self Review Report
+
+**Branch**: `feature/user-auth` → `main`  
+**Date**: 2026-02-04
+
+## 🎯 Verdict: ❌ Not Ready for PR
+
+Found 2 critical issues that must be fixed before creating a pull request.
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Files Reviewed | 5 |
+| Critical Issues | 2 ❌ |
+| Warnings | 3 ⚠️ |
+| Suggestions | 1 💡 |
+
+## Files Reviewed
+
+| File | Status | Lines Changed | Issues |
+|------|--------|---------------|--------|
+| `src/auth/login.ts` | ❌ Critical | +45 / -12 | 2 |
+| `src/utils/api.ts` | ⚠️ Warnings | +20 / -5 | 1 |
+
+## ❌ Critical Issues (Must Fix)
+
+| # | File | Line | Category | Issue | Recommendation |
+|---|------|------|----------|-------|----------------|
+| 1 | `src/auth/login.ts` | 42 | Security | Hardcoded API key found | Move to environment variables |
+| 2 | `src/auth/login.ts` | 58 | Bug | Unhandled promise rejection | Add try-catch or .catch() |
+```
+
+## 8. References
+
+| Resource | Possible Locations |
+|----------|-------------------|
+| **Skill Definition** | `.cursor/skills/self-review/SKILL.md` or `.github/skills/self-review/SKILL.md` |
+| **Configuration File** | `.cursor/project.config.json` or `.github/project.config.json` |
+| **Issue Template** | `{SKILL_PATH}/templates/issues.template.md` |
+| **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` |
+| **Issue Reports** | `issues.md` |
+
+> **Note:** `{SKILL_PATH}` refers to `.cursor/skills/self-review/` or `.github/skills/self-review/` depending on your project setup.
+
+## 9. Skill Invocation
+
+The AI agent automatically invokes this skill when it detects self-review requests in the user's prompt. The skill is registered in the agent's skill registry and can be triggered by patterns like:
+
+- "Self-review for my code changes"
+- "Check my code before PR"
+- "Review my changes"
+- "Is my code ready for PR?"
+- "self-review"
+
+No manual skill invocation is required - the AI agent handles skill selection based on user intent.