evizi-kit 1.0.0

package/kits/shared/skills/pr-review/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: pr-review
+description: Review pull request code changes, analyze for bugs/security/quality issues, and post inline comments to Git platforms. Use this skill whenever the user mentions reviewing a PR, checking code changes, doing a code review, looking at a pull request or merge request, or giving feedback on submitted code. Triggers on requests like "Review PR #42", "Check the changes in PR 123", "Can you review my pull request?", "Look at this MR", "Code review for PR 15", "What do you think about this PR?", "Review the latest changes", or any variation involving PR/MR numbers or code review requests — even casual ones like "take a look at the PR" or "check my code".
+---
+
+# PR Review Skill
+
+## Overview
+
+This skill reviews pull request code by fetching the diff, analyzing it against domain-specific checklists and project standards, and posting structured inline comments to the Git platform. It supports GitHub, GitLab, Gitea, and Bitbucket.
+
+The goal is to catch real problems — bugs, security holes, logic errors — and surface them in a way that helps the author improve the code. A good automated review feels like feedback from a thoughtful colleague, not a linting tool.
+
+## Review Philosophy
+
+A PR review is a conversation, not an audit. The best reviews help the author ship better code faster. Keep these principles in mind throughout the review:
+
+### Signal over noise
+Every comment should earn its place. A review with 3 high-value comments is better than one with 15 comments where half are style nitpicks. Before adding a comment, ask: "Would a senior engineer on this team bother mentioning this?" If the answer is no, skip it.
+
+### Understand the change first
+Before diving into line-by-line analysis, read the commit messages and the full diff to understand *what* the author is trying to accomplish. This context prevents misguided comments like suggesting a refactor when the author is intentionally making a minimal hotfix.
+
+### Severity honesty
+Be honest about severity. If something is a genuine bug or security vulnerability, say so clearly. If something is a preference or stylistic suggestion, label it that way. Mislabeling suggestions as critical issues erodes trust in the review.
+
+### Constructive tone
+Write comments the way you'd want to receive them. Instead of "This is wrong", explain what the issue is and why it matters. Include a recommendation or code snippet when possible — showing the fix is more helpful than just pointing out the problem.
+
+**Example of a good comment:**
+> The `userId` from the request body is used directly in the SQL query, which opens this endpoint to SQL injection. Since this project uses Sequelize, you can use parameterized queries instead:
+> ```ts
+> const user = await User.findByPk(userId);
+> ```
+
+**Example of a bad comment:**
+> SQL injection vulnerability on this line.
+
+### What NOT to comment on
+- Pure formatting issues (that's what linters and formatters are for)
+- Personal style preferences that don't affect correctness or readability
+- Things already caught by CI (type errors, lint failures, failing tests) — this includes checklist items like console log removal, magic numbers, and naming conventions if the project has linters covering them
+- Obvious patterns that the author clearly chose intentionally
+
+## Input
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prNumber` | number | Yes | The pull request number to review |
+
+## Execution Steps
+
+### Step 1: Read Configuration
+
+Read `.documents-design/project.config.json` and extract `baseBranch` and `platform`. See `references/output-schema.md` for the full configuration format.
+
+### Step 2: Fetch and Checkout PR Code
+
+```bash
+git fetch origin pull/${PR_NUMBER}/head:pr-${PR_NUMBER}
+git checkout pr-${PR_NUMBER}
+```
+
+**Platform-Specific Fetch Commands:**
+
+| Platform | Fetch Command |
+|----------|--------------|
+| GitHub | `git fetch origin pull/${PR_NUMBER}/head:pr-${PR_NUMBER}` |
+| Gitea | `git fetch origin pull/${PR_NUMBER}/head:pr-${PR_NUMBER}` |
+| GitLab | `git fetch origin merge-requests/${MR_NUMBER}/head:mr-${MR_NUMBER}` |
+| Bitbucket | `git fetch origin pull-requests/${PR_NUMBER}/from:pr-${PR_NUMBER}` |
+
+### Step 3: Get Changed Files
+
+Use three-dot diff (`...`) to scope the review to only the PR's own commits. This matters because two-dot diff (`git diff A B`) shows the full tree difference including unrelated changes from other branches, while three-dot (`git diff A...B`) uses the merge-base to isolate only changes introduced by this PR.
+
+```bash
+git fetch origin ${BASE_BRANCH}
+git log origin/${BASE_BRANCH}..HEAD --oneline
+git diff origin/${BASE_BRANCH}...HEAD --name-only
+git diff origin/${BASE_BRANCH}...HEAD --unified=3
+```
+
+### Step 4: Detect Tech Stack and Load Checklist
+
+Determine the tech stack from changed file extensions and read the corresponding reference:
+
+| Tech Stack | Indicators | Reference |
+|------------|-----------|-----------|
+| **Frontend** | `.tsx`, `.jsx`, `.vue`, `.css`, `package.json` | `references/frontend.md` |
+| **Backend** | `.java`, `.go`, `.py` (API), `.sql` | `references/backend.md` |
+| **Mobile** | `.swift`, `.kt`, `Podfile`, `AndroidManifest.xml` | `references/mobile.md` |
+| **Automation** | `.spec.ts`, `Selenium`, `Test.java` | `references/automation.md` |
+
+The checklists are comprehensive, but treat them as a lens, not a scorecard. Don't force-apply every item — focus on checks relevant to the actual changes. A PR that modifies a single API endpoint doesn't need every database optimization check applied.
+
+### Step 5: Analyze Code Changes
+
+This is the core of the review. Work through the diff in two passes:
+
+**First pass — Understand intent and architecture:**
+- Read the full diff to understand what the PR accomplishes
+- Check if the overall approach is sound
+- Look for missing pieces (e.g., new API endpoint with no error handling, new feature with no tests)
+- Verify consistency with existing patterns in the codebase
+
+**Second pass — Line-by-line analysis:**
+Apply the domain checklist and general review criteria:
+
+1. **Bugs** — Runtime errors, null/undefined access, off-by-one errors, race conditions, logic flaws → category: `Bug`
+2. **Security** — Hardcoded secrets, injection risks (SQL, XSS, command), broken auth/authz, sensitive data exposure → category: `Security`
+3. **Breaking changes** — API contract changes, removed fields, changed behavior → category: `BreakingChange`
+4. **Performance** — N+1 queries, unbounded loops, missing pagination, expensive operations in hot paths → category: `Performance`
+5. **Code quality** — Type safety, error handling, naming clarity, unnecessary complexity → category: `Pattern`, `Type`, `Readability`, or `Naming`
+
+**Classify issues by severity:**
+- **critical** — Bugs, security vulnerabilities, breaking changes, data loss risks. These block the PR.
+- **warning** — Performance issues, missing error handling, maintainability concerns. Important but not blocking.
+- **suggestion** — Better patterns, minor optimizations, readability improvements. Take-it-or-leave-it.
+
+### Handling Large PRs
+
+For PRs with many changed files (20+), prioritize rather than trying to review everything equally:
+1. Focus depth on high-risk files: authentication, authorization, data access, payment, configuration
+2. Give lighter review to test files, documentation, generated code, and simple refactors
+3. Note in the summary that the PR is large and recommend splitting if the changes aren't cohesive
+
+### Avoiding False Positives
+
+A false positive is worse than a missed issue — it wastes the author's time and trains them to ignore future comments. Common false positive traps:
+
+- **Intentional patterns**: If the author clearly chose an approach deliberately (e.g., using `any` type with a `// TODO` comment), don't flag it unless it's a security risk
+- **Framework conventions**: Don't flag patterns that are idiomatic for the framework (e.g., React's `useEffect` dependency arrays, Angular's decorator patterns)
+- **Test code**: Test files have different standards — assertions that look like magic numbers, hardcoded values, and verbose setup are normal
+- **Generated code**: Don't review auto-generated files
+
+### Step 6: Generate Review Output
+
+Create `review.json` in the project root following the standard schema. See `references/output-schema.md` for the full schema definition and examples.
+
+Keep comments focused and actionable. Each comment should have:
+- A clear **title** that summarizes the issue in a few words
+- A **body** that explains the problem and why it matters
+- A **recommendation** with the suggested fix (when possible)
+- A **codeSnippet** showing the corrected code (when applicable)
+
+### Step 7: Show Preview and Get Confirmation
+
+Display review summary to the user:
+
+```
+PR #42 Review Summary
+
+Found:
+- 2 Critical Issues
+- 1 Warning
+- 0 Suggestions
+
+Review saved to: review.json
+Review Status: REQUEST_CHANGES (due to critical issues)
+Platform: GitHub | Files: 5 | Total Comments: 3
+
+Do you want to post these 3 comments to GitHub? (yes/no)
+```
+
+If the user declines, inform them the review is saved and can be posted later with:
+```bash
+python {PR_REVIEW_SKILL_PATH}/scripts/post-review.py
+```
+
+### Step 8: Post Review
+
+Run the dispatcher script which handles platform-specific API formatting and posting:
+
+```bash
+# Default repo
+python {PR_REVIEW_SKILL_PATH}/scripts/post-review.py
+
+# Target a specific repo
+python {PR_REVIEW_SKILL_PATH}/scripts/post-review.py --repo webApp
+```
+
+> `{PR_REVIEW_SKILL_PATH}` is the absolute path to the pr-review skill folder (e.g., `.cursor/skills/pr-review`, `.github/skills/pr-review`).
+
+The script reads `review.json` and `.documents-design/project.config.json`, transforms comments to the platform's API format, posts them, and optionally sends a Google Chat notification.
+
+### Step 9: Cleanup
+
+```bash
+git checkout -
+git branch -D pr-${PR_NUMBER}
+```
+
+## Reference Files
+
+- `references/output-schema.md` — Review JSON schema, configuration format, operation modes, and dependencies
+- `references/frontend.md` — Frontend review checklist (React, Vue, Angular, CSS)
+- `references/backend.md` — Backend review checklist (API, database, security)
+- `references/mobile.md` — Mobile review checklist (iOS, Android)
+- `references/automation.md` — Automation test review checklist (Selenium, Cypress, Playwright)

package/kits/shared/skills/pr-review/references/automation.md

@@ -0,0 +1,62 @@
+# Automation Test Review Checklist
+
+Use this checklist when reviewing E2E or integration tests (Playwright, Cypress, Selenium, WebdriverIO, etc.).
+
+> **Severity guide**: Each item is tagged with a default severity. Adjust based on context — a hard-coded wait in a quick smoke test is a suggestion, but in a CI-gating test suite it's a warning.
+> - ❌ = Critical
+> - ⚠️ = Warning
+> - 💡 = Suggestion
+
+## ⏱️ Stability & Waits (review first — #1 cause of flaky tests)
+- ❌ **No Hard Waits**: Avoid `sleep()`, `page.waitForTimeout()`, or fixed delays. Use dynamic waits (`waitForSelector`, `waitForResponse`, `expect().toBeVisible()`). Hard waits are the leading cause of flaky tests — they're either too short (test fails) or too long (suite is slow).
+- ⚠️ **Race Conditions**: Are async operations properly awaited? Missing `await` before Playwright/Cypress commands causes non-deterministic failures.
+- ⚠️ **Timeout Configuration**: Are explicit timeouts set on actions and assertions? Relying on framework defaults (30s/60s) masks slow tests.
+- ⚠️ **Network Waits**: Are tests waiting for API responses to complete before asserting on rendered data? (`waitForResponse`, `cy.intercept`)
+- 💡 **Retry on Assertion**: Are auto-retrying assertions used (`expect(locator).toHaveText()` in Playwright, `.should()` in Cypress) instead of manual retry loops?
+
+## 🎯 Selectors & Locators
+- ❌ **Stable Selectors**: Are selectors resilient to UI changes? Using CSS classes tied to styling (`.btn-primary`) or fragile XPath (`/div[3]/span[2]`) breaks when the UI is refactored.
+- ⚠️ **Selector Priority**: Follow: `data-testid` > `role` / ARIA > `id` > CSS > XPath (last resort)
+- ⚠️ **Unique Selectors**: Are selectors specific enough to match exactly one element? Ambiguous selectors cause tests to interact with the wrong element.
+- 💡 **Playwright Locators**: Prefer Playwright's built-in locators (`getByRole`, `getByText`, `getByTestId`) over raw CSS selectors — they auto-wait and provide better error messages.
+
+## 🧹 Isolation & Cleanup
+- ❌ **Test Independence**: Can each test run in isolation, in any order? Tests that depend on prior test state are fragile and impossible to parallelize.
+- ⚠️ **Teardown**: Does `afterEach`/`afterAll` clean up created data (even on failure)? Leaked test data poisons later runs.
+- ⚠️ **Own Test Data**: Does each test create its own seed data via API or fixtures? Shared data causes inter-test interference.
+- 💡 **Parallel Safe**: Can tests run in parallel without conflicts? (No shared mutable state, no port collisions)
+
+## 🔒 Security & Data
+- ❌ **No Hardcoded Secrets**: Are credentials, tokens, and API keys in environment variables or config, not in test code?
+- ⚠️ **Test Data Privacy**: Is PII/sensitive data anonymized or mocked?
+- 💡 **API Keys Separation**: Are test API keys separate from production?
+
+## 🐛 Error Handling & Debugging
+- ⚠️ **Screenshots on Failure**: Are screenshots/videos/traces captured automatically on test failure?
+- ⚠️ **Meaningful Assertions**: Do assertion messages explain WHAT failed and WHY? (`expect(count).toBe(5, 'Cart should have 5 items after adding')` not just `expect(count).toBe(5)`)
+- ⚠️ **Trace / Debug Logs**: Are critical user actions logged for troubleshooting? (`console.log('Clicked checkout button')`)
+- 💡 **Error Recovery**: Are expected transient failures (e.g., toast auto-dismiss) handled gracefully with retry or conditional logic?
+
+## 🧱 Code Quality & Patterns
+- ⚠️ **Page Object Pattern**: Is test logic separated from locators/selectors? Page Object Model (or equivalent abstraction) keeps tests readable and locators maintainable.
+- ⚠️ **Explicit Assertions**: Does every test action have a corresponding assertion? Actions without assertions pass even when the feature is broken.
+- ⚠️ **Descriptive Names**: Does the test name describe the behavior being verified? (`should show error when login with expired token` — not `test1` or `loginTest`)
+- ⚠️ **Given-When-Then / AAA**: Is test structure clear? (Arrange preconditions → Act on the system → Assert expected outcome)
+- 💡 **Positive & Negative Tests**: Does the test verify both success and error scenarios?
+- 💡 **DRY Helpers**: Are repeated setup sequences (login, navigate, seed data) extracted to reusable helpers?
+
+## 🌐 Environment & CI
+- ❌ **CI Ready**: Will the test run in headless mode without display dependencies? (No `headless: false` left in CI config)
+- ⚠️ **Environment Agnostic**: Does the test work across environments (dev/staging/prod) using config — not hardcoded URLs or ports?
+- ⚠️ **Test Duration**: Does each test complete in a reasonable time? (< 2 min per E2E test, < 10 min total suite for CI gating)
+- 💡 **External Dependencies**: Are external APIs/services mocked or stubbed to avoid flakiness from third-party outages?
+- 💡 **Test Reporting**: Are results reported in a format CI can parse (JUnit XML, HTML report)?
+
+## 📊 Test Data Management
+- ⚠️ **Data Setup via API**: Are test preconditions set up via API calls rather than through the UI? API setup is faster and more reliable.
+- 💡 **Fixtures / Factories**: Are reusable data factories or fixture files used for test data generation?
+- 💡 **Database Seeding**: For complex scenarios, is the database seeded directly rather than clicking through UI flows?
+
+## ♿ Accessibility (Optional)
+- 💡 **A11y Validation**: Are basic accessibility rules checked during E2E flows (e.g., axe-core integration)?
+- 💡 **Keyboard Navigation**: Can critical flows complete using keyboard only?

package/kits/shared/skills/pr-review/references/backend.md

@@ -0,0 +1,95 @@
+# Backend Code Review Checklist
+
+Use this checklist when reviewing Backend, API, or Database code.
+
+> **Severity guide**: Each item is tagged with a default severity. Adjust based on context — a missing index on a rarely-queried column is a suggestion, but on a high-traffic endpoint it's a warning.
+> - ❌ = Critical
+> - ⚠️ = Warning
+> - 💡 = Suggestion
+
+## 🔒 Security — OWASP (review first)
+- ❌ **SQL Injection**: Are parameterized queries / prepared statements used? Raw SQL with string-concatenated user input is the most exploited web vulnerability.
+- ❌ **Authentication**: Are endpoints requiring auth properly protected?
+- ❌ **Authorization**: Does the user have permission to access this specific resource? (Check for IDOR — can user A access user B's data by changing an ID?)
+- ❌ **No Hardcoded Secrets**: Are credentials, API keys, and tokens in env vars or secret managers (not committed in code)?
+- ❌ **Password Hashing**: Are passwords hashed with bcrypt/Argon2? (MD5/SHA1 are broken for passwords)
+- ⚠️ **JWT/Token Validation**: Are tokens verified, checked for expiry, and scoped correctly?
+- ⚠️ **XSS Prevention**: Is user input sanitized before rendering in responses?
+- ⚠️ **Safe Error Messages**: Do error responses hide internal details? (No stack traces, SQL errors, or file paths to the client)
+- ⚠️ **Sensitive Data in Logs**: Is PII redacted from logs and error messages?
+- ⚠️ **CORS Configuration**: Are CORS headers restrictive? (`Access-Control-Allow-Origin: *` in production is almost always wrong)
+- ⚠️ **CSRF Protection**: Are state-changing endpoints protected from cross-site request forgery?
+- ⚠️ **File Upload Security**: Are uploaded files validated for type, size, and content? Are they stored outside the web root?
+- 💡 **Rate Limiting Headers**: Do rate-limited endpoints return `Retry-After` and `X-RateLimit-*` headers?
+
+## ✅ Input Validation & Data
+- ❌ **Input Validation**: Are all API inputs validated at the boundary? Unvalidated input is the root cause of injection attacks.
+- ⚠️ **Type Checking**: Are input types validated (string, int, email format, UUID)?
+- ⚠️ **Boundary Checks**: Are ranges validated (min/max length, value ranges, array sizes)?
+- ⚠️ **Required Fields**: Are required fields enforced?
+- 💡 **Business Rules**: Are domain-specific rules validated (e.g., quantity > 0, date in future)?
+
+## 🌐 API Design & HTTP
+- ⚠️ **HTTP Status Codes**: Are correct codes used? (200, 201, 400, 401, 403, 404, 409, 500)
+- ⚠️ **REST Principles**: Do endpoints follow REST conventions (GET reads, POST creates, PUT/PATCH updates, DELETE removes)?
+- ⚠️ **Response Format**: Is JSON structure consistent across endpoints (same envelope, error format)?
+- 💡 **API Versioning**: Is the API versioned (e.g., `/v1/users`) for breaking changes?
+- 💡 **Content-Type**: Are proper content-type headers set on requests and responses?
+
+## 💾 Database & Queries
+- ❌ **Transactions**: Are multi-step updates wrapped in transactions? Partial writes corrupt data.
+- ⚠️ **N+1 Queries**: Are loops triggering individual DB calls? (Use `JOIN`, batch loading, or `IN` clause)
+- ⚠️ **Connection Management**: Are DB connections properly closed/returned to pool?
+- ⚠️ **Pagination**: Do list endpoints paginate large datasets? Unbounded queries can OOM.
+- 💡 **Indexing**: Are foreign keys and frequently-queried/filtered columns indexed?
+- 💡 **Query Optimization**: Are slow queries analyzed (EXPLAIN) for missing indexes or full scans?
+- 💡 **Query Limits**: Are queries limited with a ceiling (e.g., `LIMIT 1000`) as a safety net?
+
+## ⚡ Performance & Scalability
+- ⚠️ **Timeouts**: Are external API calls wrapped with timeouts? A hanging dependency can cascade.
+- ⚠️ **Rate Limiting**: Are public endpoints protected from abuse/DDoS?
+- 💡 **Caching**: Are expensive or frequently-read queries/responses cached appropriately?
+- 💡 **Lazy Loading**: Are large objects (files, blobs) loaded only when requested?
+- 💡 **Async Processing**: Are long-running tasks offloaded to queues/workers instead of blocking the request?
+
+## 🧱 Error Handling & Resilience
+- ⚠️ **Error Handling**: Are errors caught, logged with context, and returned with appropriate HTTP status?
+- ⚠️ **Idempotency**: Can create/update operations be safely retried without side effects? (Important for payment flows, webhooks)
+- 💡 **Graceful Degradation**: Does the service handle dependency failures without cascading?
+- 💡 **Circuit Breakers**: Are failing external services circuit-broken?
+- 💡 **Retry Logic**: Are transient failures retried with exponential backoff and jitter?
+
+## 📊 Observability & Monitoring
+- ⚠️ **Logging**: Are errors logged with enough context (`request_id`, `user_id`, `timestamp`)?
+- ⚠️ **Structured Logs**: Are logs in structured format (JSON) for parsing by log aggregators?
+- 💡 **Tracing**: Can requests be traced across services (trace_id/span_id)?
+- 💡 **Health Checks**: Does the service expose `/health` and `/ready` endpoints?
+- 💡 **Metrics**: Are key metrics exposed (latency, error rate, throughput)?
+
+## 🔄 Concurrency & State
+- ❌ **Race Conditions**: Are concurrent updates handled? (e.g., optimistic locking, `SELECT ... FOR UPDATE`)
+- ⚠️ **Concurrency Safety**: Is shared state protected (locks/mutex) in async or multi-threaded code?
+- 💡 **Stateless Design**: Is the service stateless for horizontal scaling?
+
+## 🧪 Testing
+- ⚠️ **Unit Tests**: Are business logic and edge cases tested?
+- ⚠️ **Error Scenarios**: Are error paths tested (not just happy path)?
+- 💡 **Integration Tests**: Are database and API interactions tested end-to-end?
+- 💡 **Test Isolation**: Do tests use isolated data and clean up after themselves?
+
+## 🔄 Migrations & Deployments
+- ❌ **Backward Compatible**: Can old code run with new schema during rolling deployment? Dropping a column that old code still reads causes outages.
+- ⚠️ **Migration Rollback**: Can database migrations be safely rolled back?
+- 💡 **Zero Downtime**: Does the change support rolling deployments?
+- ⚠️ **Breaking API Changes**: Are breaking changes properly versioned with deprecation notices?
+
+## 🏗️ Code Structure & Maintainability
+- ⚠️ **Separation of Concerns**: Is business logic separated from routing/controllers?
+- ⚠️ **DRY Principle**: Is duplicated code refactored?
+- 💡 **Magic Numbers**: Are hardcoded values extracted to constants/config?
+- 💡 **Naming Conventions**: Are variables, functions, and classes clearly named?
+
+## 📦 Dependencies
+- ⚠️ **Vulnerable Packages**: Are dependencies scanned for known CVEs?
+- 💡 **Version Pinning**: Are dependency versions locked/pinned?
+- 💡 **Unused Dependencies**: Are unused packages removed?

package/kits/shared/skills/pr-review/references/frontend.md

@@ -0,0 +1,103 @@
+# Frontend Code Review Checklist
+
+Use this checklist when reviewing Web Frontend code (React, Vue, Angular, Svelte, HTML/CSS).
+
+> **Severity guide**: Each item is tagged with a default severity. Adjust based on context — a missing error boundary in a settings page is a warning, but in a payment flow it's critical.
+> - ❌ = Critical
+> - ⚠️ = Warning
+> - 💡 = Suggestion
+
+## 🛡️ Security (review first)
+- ❌ **XSS Prevention**: Is `dangerouslySetInnerHTML` avoided or input sanitized? Unsanitized user content renders directly into the DOM.
+- ❌ **Sensitive Data Exposure**: Are tokens/passwords stored securely? (not in localStorage for auth tokens — use httpOnly cookies or secure session management)
+- ⚠️ **CSRF Protection**: Are CSRF tokens included in state-changing forms?
+- ⚠️ **Cookie Flags**: Are cookies set with `Secure`, `HttpOnly`, and `SameSite` flags?
+- ⚠️ **Third-Party Scripts**: Are CDN scripts verified with Subresource Integrity (SRI)?
+- 💡 **Content Security Policy**: Is CSP configured to limit script sources?
+
+## 🚨 Error Handling
+- ❌ **Error Boundaries**: Are error boundaries in place to catch component crashes? An uncaught error in a child component can take down the entire app.
+- ⚠️ **Fallback UI**: Is there graceful fallback for error states?
+- ⚠️ **Network Errors**: Are API failures handled with user-facing feedback and retry/fallback?
+- ⚠️ **Form Validation**: Are validation errors clearly displayed near the relevant fields?
+- 💡 **Error Messages**: Are messages user-friendly (not raw error objects or stack traces)?
+
+## 🧩 Component Architecture
+- ⚠️ **Component Size**: Are components too large (>200 lines)? Should they be split?
+- ⚠️ **Single Responsibility**: Does each component do one thing well?
+- ⚠️ **Prop Drilling**: Are props passed through many levels? (Consider context/state management)
+- 💡 **Reusability**: Are common patterns extracted to shared components?
+
+## 🗄️ State Management
+- ❌ **Effect Cleanups**: Do `useEffect` hooks clean up listeners/timers/subscriptions? Missing cleanups cause memory leaks and stale state bugs.
+- ⚠️ **State Location**: Is state at the right level (not too high, not too low)?
+- ⚠️ **Derived State**: Is redundant state avoided (computed from existing state)?
+- ⚠️ **State Updates**: Are state updates immutable?
+- 💡 **Global State**: Is global state (Redux/Zustand/Context) used only when needed?
+
+## ⚡ Performance & Rendering
+- ⚠️ **Re-renders**: Are components re-rendering unnecessarily? (Check `useCallback`/`useMemo` in React, `computed` in Vue)
+- ⚠️ **Bundle Size**: Are large libraries imported efficiently? (`import map from 'lodash/map'` vs `import _ from 'lodash'`)
+- ⚠️ **Race Conditions**: Are stale requests cancelled (AbortController) to prevent rendering outdated data?
+- 💡 **Image Optimization**: Are images lazy-loaded with explicit dimensions (prevent CLS)?
+- 💡 **List Virtualization**: Are long lists (>100 items) virtualized?
+- 💡 **Code Splitting**: Are routes and large components code-split?
+- 💡 **Memoization**: Are expensive computations memoized?
+
+## ⏳ Loading & Async States
+- ⚠️ **Loading Indicators**: Are loading states shown for async operations?
+- ⚠️ **Optimistic Updates**: Are UI updates optimistic where appropriate?
+- 💡 **Skeleton Screens**: Are skeleton loaders used instead of spinners for better UX?
+- 💡 **Suspense / Streaming**: Is React Suspense, Vue async components, or framework streaming used appropriately?
+
+## 📝 Forms & User Input
+- ⚠️ **Controlled Components**: Are form inputs properly controlled?
+- ⚠️ **Validation**: Is client-side validation implemented for required fields and formats?
+- ⚠️ **Submit Protection**: Are submit buttons disabled during API calls to prevent double submission?
+- 💡 **Debouncing**: Are expensive operations (search, API calls) debounced/throttled?
+- 💡 **Success Feedback**: Is user notified of successful actions?
+
+## 🔄 Data & API Integration
+- ⚠️ **Error States**: Are API errors caught and displayed to user?
+- ⚠️ **Request Cancellation**: Are pending requests cancelled on unmount?
+- 💡 **Caching**: Are API responses cached (React Query, SWR, Apollo) to avoid redundant requests?
+- 💡 **Retry Logic**: Are failed requests retried with backoff?
+
+## 📱 Responsiveness & CSS
+- ⚠️ **Mobile Support**: Does the layout work on small screens (320px+)?
+- ⚠️ **Design Tokens**: Are CSS variables/design tokens used instead of hardcoded values?
+- 💡 **Touch Targets**: Are interactive elements at least 44x44px?
+- 💡 **Animations**: Are animations performant (use `transform`/`opacity`, avoid layout thrashing)?
+- 💡 **Dark Mode**: Is dark mode support considered?
+
+## ♿ Accessibility (a11y)
+- ⚠️ **Semantic HTML**: Are proper elements used (`<button>`, `<nav>`, `<main>`, not `<div>` for everything)?
+- ⚠️ **Alt Text**: Do all images have meaningful `alt` attributes?
+- ⚠️ **Keyboard Navigation**: Are interactive elements reachable via Tab?
+- ⚠️ **Focus Indicators**: Are focus styles visible (not `outline: none` without replacement)?
+- 💡 **Color Contrast**: Does text meet WCAG contrast ratios (4.5:1 for normal text)?
+- 💡 **ARIA Labels**: Are ARIA labels used where native semantics are insufficient?
+- 💡 **Heading Hierarchy**: Are headings (h1-h6) used in logical order?
+
+## 🔒 Type Safety
+- ⚠️ **TypeScript**: Are types defined for props, state, and functions?
+- ⚠️ **Any Types**: Is `any` avoided? (use `unknown` or proper types)
+- ⚠️ **Null Checks**: Are nullable values properly handled?
+- 💡 **Type Inference**: Are types inferred where possible (avoid redundant annotations)?
+
+## 🧪 Testing & Quality
+- ⚠️ **Unit Tests**: Are components tested for key behaviors?
+- ⚠️ **Test IDs**: Are `data-testid` attributes added for E2E testing?
+- 💡 **Accessibility Tests**: Are a11y rules tested (jest-axe, testing-library)?
+- 💡 **Edge Cases**: Are loading/error states tested?
+
+## 🏗️ Code Quality
+- ⚠️ **Console Logs**: Are debug `console.log` statements removed?
+- ⚠️ **DRY Principle**: Is duplicated code refactored?
+- 💡 **Magic Numbers**: Are hardcoded values extracted to constants?
+- 💡 **Naming Conventions**: Are variables, functions, and components clearly named?
+
+## 🔍 SEO & Meta (if applicable)
+- 💡 **Meta Tags**: Are title, description, and Open Graph tags set?
+- 💡 **Semantic HTML**: Are heading tags used hierarchically?
+- 💡 **Canonical URLs**: Are canonical tags set for duplicate content?

package/kits/shared/skills/pr-review/references/mobile.md

@@ -0,0 +1,108 @@
+# Mobile Code Review Checklist
+
+Use this checklist when reviewing iOS (Swift/SwiftUI) or Android (Kotlin/Jetpack Compose) code.
+
+> **Severity guide**: Each item is tagged with a default severity. Adjust based on context — a missing loading indicator on a debug screen is a suggestion, but on a checkout flow it's a warning.
+> - ❌ = Critical
+> - ⚠️ = Warning
+> - 💡 = Suggestion
+
+## 🔒 Security (review first)
+- ❌ **No Hardcoded Secrets**: Are API keys, tokens, and credentials stored in config/env — not committed in source code?
+- ❌ **Secure Storage**: Are sensitive credentials stored in Keychain (iOS) or Android Keystore — not SharedPreferences/UserDefaults?
+- ❌ **Deep Link Validation**: Are deep link parameters validated and sanitized to prevent injection attacks?
+- ⚠️ **Certificate Pinning**: Is SSL pinning implemented for sensitive API calls?
+- ⚠️ **Biometric Auth**: Is biometric authentication implemented with proper fallback (passcode)?
+- 💡 **Root/Jailbreak Detection**: Is rooted/jailbroken device detection implemented for sensitive flows?
+- 💡 **Screenshot Protection**: Is sensitive data hidden when app enters background (recent apps view)?
+- 💡 **Code Obfuscation**: Is ProGuard/R8 (Android) enabled for release builds?
+
+## 📱 Threading & Lifecycle
+- ❌ **Main Thread Safety**: Is heavy work (DB, network, computation, image processing) off the UI thread? Main-thread blocking causes ANRs (Android) and UI freezes (iOS).
+- ❌ **Lifecycle Cleanup**: Are observers, listeners, and subscriptions removed in `onDestroy`/`onDisappear`/`deinit`? Leaking these causes crashes and ghost updates.
+- ⚠️ **Memory Management**: Are strong reference cycles avoided in closures/listeners? (Use `[weak self]` in Swift, `WeakReference` in Kotlin)
+- ⚠️ **Configuration Changes**: Are configuration changes (rotation, dark mode, locale) handled without data loss?
+- ⚠️ **State Restoration**: Is state saved/restored correctly on process death?
+- 💡 **Permissions**: Are runtime permissions requested at appropriate times with clear explanation?
+
+## 🌐 Networking
+- ⚠️ **Timeout Configuration**: Are network requests configured with explicit timeouts?
+- ⚠️ **Error Handling**: Are network errors handled gracefully with user-friendly messages?
+- ⚠️ **Offline Mode**: Does the app handle "No Internet" states without crashing?
+- ⚠️ **Request Cancellation**: Are pending requests cancelled when leaving the screen?
+- 💡 **Retry Logic**: Are failed requests retried with exponential backoff?
+- 💡 **Response Validation**: Are API responses validated before use (null checks, type validation)?
+- 💡 **Network Reachability**: Is network status checked before making API calls?
+
+## 💾 Memory & Resources
+- ❌ **Memory Leaks**: Are retain cycles (iOS closures) and context leaks (Android activities in singletons) avoided?
+- ⚠️ **Image Handling**: Are bitmaps scaled/compressed before loading into memory? Full-resolution images in lists cause OOM.
+- ⚠️ **Image Caching**: Are images cached appropriately (Glide/Coil for Android, SDWebImage/Kingfisher for iOS)?
+- 💡 **Resource Files**: Are strings, colors, and dimensions in resource files (not hardcoded)?
+- 💡 **Memory Warnings**: Are memory warnings handled (iOS `didReceiveMemoryWarning`)?
+
+## ⚡ Performance
+- ⚠️ **List Recycling**: Are RecyclerView (Android) / LazyColumn (Compose) / List (SwiftUI) used for scrollable lists?
+- ⚠️ **Lazy Loading**: Are heavy resources loaded only when needed?
+- 💡 **App Launch Time**: Is cold start optimized? (Defer non-essential initialization)
+- 💡 **Smooth Animations**: Are animations smooth (avoid layout passes during animation)?
+- 💡 **Background Work**: Is WorkManager (Android) or BGTaskScheduler (iOS) used for background tasks?
+- 💡 **App Size**: Are unused resources and large assets optimized?
+
+## 🧭 Navigation & Architecture
+- ⚠️ **Navigation Patterns**: Is navigation consistent? (Navigation Component / Compose Navigation on Android, NavigationStack / Coordinator on iOS)
+- ⚠️ **Back Stack**: Is back navigation handled properly without stack corruption?
+- ⚠️ **Architecture Pattern**: Is MVVM / MVI followed consistently? Business logic should not live in Views.
+- 💡 **Dependency Injection**: Are dependencies injected (Hilt/Koin for Android, manual DI or Swinject for iOS)?
+- 💡 **Deep Linking**: Do deep links route to the correct screens?
+
+## 📱 UI/UX
+- ⚠️ **Safe Areas**: Does content respect notches, dynamic islands, and status bars?
+- ⚠️ **Loading States**: Are loading indicators shown for async operations?
+- ⚠️ **Error States**: Are error messages user-friendly with retry options?
+- ⚠️ **Keyboard Handling**: Does the keyboard not cover input fields? (Insets, scroll adjustment)
+- 💡 **Touch Feedback**: Do interactive elements show visual feedback when pressed?
+- 💡 **Empty States**: Are empty states designed with helpful messages?
+- 💡 **Pull to Refresh**: Is pull-to-refresh implemented where appropriate?
+
+## ♿ Accessibility
+- ⚠️ **Screen Reader**: Is content accessible to VoiceOver (iOS) / TalkBack (Android)?
+- ⚠️ **Content Descriptions**: Do images/icons have content descriptions?
+- ⚠️ **Touch Targets**: Are touch targets at least 44x44 points?
+- 💡 **Font Scaling**: Does UI support dynamic font sizes?
+- 💡 **Color Contrast**: Does text meet WCAG contrast requirements?
+
+## 🌍 Localization
+- ⚠️ **Hardcoded Strings**: Are all user-facing strings in resource files (Localizable.strings / strings.xml)?
+- 💡 **RTL Support**: Does layout support right-to-left languages?
+- 💡 **Date/Number Formatting**: Are dates/numbers formatted for locale?
+- 💡 **Plurals**: Are plural strings handled correctly?
+
+## 💾 Data Persistence
+- ⚠️ **Database**: Is Room (Android) or Core Data / SwiftData (iOS) used correctly?
+- ⚠️ **Migrations**: Are database migrations handled safely without data loss?
+- 💡 **Cache Management**: Is cached data invalidated when stale?
+- 💡 **Preferences**: Are SharedPreferences/UserDefaults used only for simple key-value data?
+
+## 🧪 Testing
+- ⚠️ **Unit Tests**: Are business logic and ViewModels tested?
+- 💡 **UI Tests**: Are critical user flows tested (Espresso/Compose Testing / XCUITest)?
+- 💡 **Mock Data**: Are network calls mocked for testing?
+- 💡 **Edge Cases**: Are error states and edge cases tested?
+
+## 📊 Analytics & Monitoring
+- ⚠️ **Crash Reporting**: Is crash reporting configured (Firebase Crashlytics / Sentry)?
+- 💡 **Analytics Events**: Are key user actions tracked?
+- 💡 **Performance Monitoring**: Is app performance monitored (launch time, screen load)?
+- 💡 **ANR Detection**: Are ANRs monitored (Android)?
+
+## 🏗️ Code Quality
+- ⚠️ **Naming Conventions**: Are classes, functions, and variables clearly named per platform conventions?
+- ⚠️ **DRY Principle**: Is duplicated code refactored?
+- ⚠️ **Deprecated APIs**: Are deprecated APIs replaced with modern alternatives?
+- 💡 **Magic Numbers**: Are hardcoded values extracted to constants?
+
+## 🛠️ Build & CI/CD
+- ⚠️ **Signing**: Are signing configs secure (not committed to repo)?
+- 💡 **Build Variants**: Are debug/release builds configured properly?
+- 💡 **Version Code/Number**: Are version codes incremented?