evizi-kit 1.0.0

package/kits/shared/skills/push-code/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: push-code
+description: Push current code changes to the Git remote repository. Verifies git identity, stages changes, generates a conventional commit message from the diff, and pushes to the current branch. Use this skill whenever the user wants to push code, commit and push, save changes to remote, git push, send code upstream, ship code, deploy changes to a branch, or sync local work with the remote. Triggers on requests like "push the code", "commit and push", "push my changes", "push to remote", "ship it", "save my work to git", "upload my changes", "sync to remote", even if they don't explicitly mention git — if they clearly want their local changes sent to a remote repository, use this skill.
+---
+
+# Push Code
+
+Push current code changes to the Git remote with auto-generated conventional commit messages and clear status reporting.
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| commit_message | string | No | If provided, use this instead of auto-generating. Respect the user's wording. |
+| branch | string | No | Target branch to push to. Defaults to the current branch. |
+
+## Quick Start
+
+1. Verify git is available and identity is configured
+2. Check current branch and working tree status
+3. Guard against pushing directly to protected branches
+4. Stage changes (only unstaged files when nothing is pre-staged)
+5. Generate a conventional commit message from the diff
+6. Push to remote, setting upstream if needed
+7. Report final status
+
+## Workflow
+
+### Step 1: Verify Git Configuration
+
+Check git availability and identity — without a configured identity, commits will either fail or be attributed incorrectly, which causes problems for the whole team.
+
+```bash
+git --version
+git config user.name
+git config user.email
+```
+
+**If git is not installed** → Stop and inform the user to install git.
+**If username or email is empty** → Stop and provide configuration commands:
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+```
+
+### Step 2: Check Branch and Status
+
+```bash
+git branch --show-current
+git status --porcelain
+```
+
+- Record the current branch name for later steps
+- If the output of `git branch --show-current` is empty, the repo is in **detached HEAD** state → Stop and tell the user to checkout a branch first (`git checkout -b <branch-name>`)
+- If there are **no changes** (both working tree and staging area are clean) → Inform the user and stop (this is not an error)
+
+### Step 3: Protected Branch Guard
+
+Before making any changes, check whether the current branch is a protected branch like `main`, `master`, or `develop`. Pushing directly to these branches bypasses code review and can break the build for the entire team.
+
+```bash
+BRANCH=$(git branch --show-current)
+```
+
+If `$BRANCH` is `main`, `master`, or `develop`:
+- **Stop** and warn the user: "You're on `[branch]`, which is typically a protected branch. Create a feature branch first with `git checkout -b <feature-branch>`."
+- Only proceed if the user explicitly confirms they want to push to this branch.
+
+### Step 4: Stage Changes
+
+Staging is context-sensitive — if the user has already carefully staged specific files, blindly running `git add -A` would undo their curation by pulling in everything else too.
+
+```bash
+git diff --cached --name-only
+```
+
+- **If there are already staged files** → Respect the user's staging. Do not add more files. Proceed to Step 5.
+- **If nothing is staged** → Stage all changes:
+  ```bash
+  git add -A
+  ```
+
+### Step 5: Generate Commit Message and Commit
+
+Generate a descriptive commit message based on the actual changes. Start with the stat summary to understand scope, then read the full diff for detail:
+
+```bash
+git diff --cached --stat
+git diff --cached
+```
+
+**Handling large diffs:** If the diff exceeds ~500 lines, rely on `--stat` plus `--cached --name-only` to understand the change scope rather than reading every line. Focus the commit message on the high-level intent.
+
+**Handling binary files:** Binary files show up in `--stat` but not in the text diff. Mention them in the commit body if relevant (e.g., "update logo asset").
+
+Create a commit message following **conventional commits** format:
+
+- **Subject line** (max 72 chars): concise summary of the overall change
+- **Prefix**: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`, `style:`, `ci:`, `build:`
+- If changes span multiple concerns, use the most dominant category
+- For multi-file changes, add a body with bullet points explaining each logical group
+
+**Examples:**
+- `feat: add user authentication middleware`
+- `fix: resolve null pointer in payment processing`
+- `refactor: extract shared validation logic into utils`
+- `docs: update API endpoint documentation`
+- `chore: update dependencies and config files`
+
+If the user provided a `commit_message` parameter, use that instead of auto-generating.
+
+```bash
+git commit -m "<message>"
+```
+
+If the commit fails (e.g., pre-commit hooks reject it), stop and report the hook output so the user can fix lint/format issues.
+
+### Step 6: Push to Remote
+
+First check whether the branch has an upstream tracking reference — without one, `git push` will fail with a confusing error about no tracking information.
+
+```bash
+git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null
+```
+
+- **If upstream exists** → Push normally:
+  ```bash
+  git push
+  ```
+- **If no upstream** → Set upstream and push:
+  ```bash
+  git push --set-upstream origin $(git branch --show-current)
+  ```
+
+### Step 7: Report Status
+
+**On success:**
+
+```
+✅ Push Completed
+
+- Branch: [branch_name]
+- Commit: [short_hash] — [commit message]
+- Files changed: [count]
+- Pushed to: origin/[branch_name]
+```
+
+**On failure:**
+
+```
+❌ Push Failed
+
+- Step: [which step failed]
+- Error: [error message]
+- Suggested fix: [actionable guidance]
+```
+
+## Error Handling
+
+Each git step depends on the previous one succeeding — a failed stage means the commit will be wrong, and a failed commit means there's nothing to push. Stop at the first failure and report clearly so the user can fix the root cause rather than chasing cascading errors.
+
+| Scenario | Action |
+|----------|--------|
+| Git not installed | Stop, inform user to install git |
+| Identity not configured | Stop, provide `git config` commands |
+| Detached HEAD | Stop, suggest `git checkout -b <branch-name>` |
+| On protected branch | Warn user, stop unless they explicitly confirm |
+| No changes to commit | Inform user, stop gracefully |
+| Staging fails | Report error, stop |
+| Commit fails (pre-commit hook) | Show hook output, suggest fixing lint/format issues, re-stage, commit again |
+| Commit fails (other) | Report error, stop |
+| Push fails — auth error | Suggest PAT (HTTPS) or SSH key setup |
+| Push fails — rejected (behind remote) | Suggest `git pull --rebase origin [branch]`, resolve conflicts, retry |
+| Push fails — no upstream | Use `git push --set-upstream origin [branch]` (handled automatically in Step 6) |
+| Push fails — remote not found | Suggest `git remote add origin <url>` |

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

@@ -0,0 +1,234 @@
+---
+name: self-review
+description: Perform automated pre-PR code review with clear verdict. Analyzes branch changes against the target branch, generates a table-based report with severity-categorized issues, and provides a Ready/Not Ready decision for PR creation. Use this skill whenever the user mentions self-review, reviewing code, checking changes before PR, asking if code is ready for PR or merge, wanting a code quality check, pre-merge review, or any variation of "review my branch". Also trigger for phrases like "check my diff", "anything wrong with my changes", "am I ready to merge", or "scan my code for issues" — even if the user doesn't explicitly say "self-review".
+---
+
+# Self Review Skill
+
+Review code changes between current branch and target branch, providing a clear verdict and structured feedback in table format for quick verification before creating a PR.
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `TICKET_ID` | string | No | If provided, `issues.md` is saved to `.tickets/{TICKET_ID}/issues.md`. If omitted, saved to the project root. |
+
+## Quick Start
+
+1. Read config from `project.config.json` in `.documents-design/`
+2. Run `git diff` against target branch
+3. Analyze changes for issues
+4. Generate report in `issues.md`
+
+## Workflow
+
+### Step 1: Load Configuration
+
+Read `project.config.json` from `.documents-design/`. Extract:
+- `baseBranch` - the branch to compare against
+- `excludePaths` (optional) - glob patterns for files to skip during review
+
+**If config missing:** STOP, ask user to create `project.config.json`
+
+### Step 2: Check for Untracked Files
+
+Before analyzing changes, check for untracked files that won't be included in the diff:
+
+```bash
+git ls-files --others --exclude-standard
+```
+
+**If untracked files found:**
+1. Run `git add <files>` for each untracked file automatically
+2. Inform the user:
+   ```
+   ℹ️ Staged X untracked file(s) for review:
+   - path/to/file1.ts
+   - path/to/file2.tsx
+   ```
+3. Proceed to Step 3
+
+**If no untracked files:** Proceed directly to Step 3.
+
+### Step 3: Get Changes
+
+**Use three-dot diff (`...`) to scope the review to only the current branch's own commits.**
+
+Two-dot diff (`git diff origin/main HEAD`) compares the full tree difference, which includes unrelated changes from other branches. Three-dot diff (`git diff origin/main...HEAD`) uses the merge-base, showing only changes introduced by the current branch's commits. This distinction matters when the branch was created from another feature branch — two-dot would include that feature branch's changes, while three-dot correctly isolates only the current branch's contributions.
+
+Run git commands to get changes between current branch and target branch:
+
+1. Fetch the latest target branch to ensure accurate diff:
+   ```
+   git fetch origin <target-branch>
+   ```
+
+2. List the branch's own commits (for scope verification):
+   ```
+   git log origin/<target-branch>..HEAD --oneline
+   ```
+
+3. Get list of changed files (three-dot):
+   ```
+   git diff origin/<target-branch>...HEAD --name-only
+   ```
+
+4. Get detailed line-by-line diff (three-dot):
+   ```
+   git diff origin/<target-branch>...HEAD --unified=3
+   ```
+
+**If no changes:** STOP, inform user.
+
+**Check for branch divergence:** After fetching, check how far the branch has diverged from the target:
+
+```bash
+git log HEAD..origin/<target-branch> --oneline | wc -l
+```
+
+If the target branch has new commits that the current branch doesn't have (i.e., the count is > 0), warn the user. The three-dot diff correctly reviews only the current branch's changes, but it cannot detect incompatibilities with new code on the target branch — for example, the target branch may have renamed a function the current branch still calls, deleted an API the current branch depends on, or introduced a duplicate implementation.
+
+```
+⚠️ Target branch has X new commit(s) since this branch diverged.
+The review covers your branch's changes only. It cannot detect conflicts or incompatibilities with the new code on <target-branch>.
+Consider rebasing before PR: git rebase origin/<target-branch>
+```
+
+Include this warning in the report header (below the verdict) so it's visible.
+
+**If large diff (>30 files or >2000 lines):** Prioritize review by focusing on:
+1. Files with the most additions/modifications first
+2. Source code over generated files, configs, or lock files
+3. Files that touch security-sensitive areas (auth, payments, data access)
+
+Mention in the report summary that the review was prioritized and which files were given deeper attention.
+
+### Step 4: Analyze
+
+#### 1. Identify Tech Stack
+
+Determine the project type by checking the extensions of **changed files** (not the entire repo):
+
+- **Frontend**: `.tsx`, `.jsx`, `.vue`, `.svelte`, `.css`, `.scss`
+- **Backend**: `.java`, `.go`, `.py`, `.rb`, `.cs`, `.sql`
+- **Mobile**: `.swift`, `.kt`, `Podfile`, `AndroidManifest.xml`
+- **Automation**: `spec.ts`, `spec.js`, `.test.ts`, `.test.js`, `Test.java`, `_test.go`
+
+A project can span multiple stacks — for instance, a full-stack change might include both `.tsx` and `.java` files. Identify all applicable stacks.
+
+#### 2. Load Domain Checklists
+
+Based on the detected stack(s), **read the corresponding reference file(s)**:
+
+| Stack | Reference File |
+|-------|----------------|
+| **Frontend** | `references/frontend.md` |
+| **Backend** | `references/backend.md` |
+| **Mobile** | `references/mobile.md` |
+| **Automation** | `references/automation.md` |
+
+For mixed-stack changes, load all relevant checklists and apply each to its corresponding files.
+
+#### 3. Load Project-Specific Guidelines
+
+Check `.documents-design/` for project-level documents that define conventions specific to this codebase. These take priority over generic checklists when they conflict — the project's own rules are what the PR reviewer will enforce.
+
+| Document | Path | What to check |
+|----------|------|---------------|
+| **Project Blueprint** | `.documents-design/*-project-blueprint.md` | Naming conventions, directory structure, selector strategy, architectural patterns. Flag violations as ⚠️ Warning. |
+| **Project Instructions** | `.documents-design/*-instructions.md` | Code patterns, templates, and idioms the project uses. Flag deviations as ⚠️ Warning — the code should match established patterns. |
+| **Best Practices** | `.documents-design/*-best-practices.md` | Coding standards, rules, and anti-patterns. Flag rule violations by their documented severity; anti-pattern violations are ⚠️ Warning. |
+
+**If none of these files exist:** Proceed with only the domain checklists. This is fine — not every project has these.
+
+**If found:** Read each document and extract the relevant conventions. During the review, check changed code against both the domain checklist AND project-specific rules. When reporting issues from project guidelines, use the category "Project Convention" so the developer knows the rule comes from the project's own docs, not a generic checklist.
+
+#### 4. Perform Review
+
+Read the entire diff before starting analysis — context across files often reveals issues that single-file review misses (e.g., an API endpoint added in the backend without corresponding frontend error handling).
+
+Focus on the **changed lines and their immediate context**, not the entire file. The goal is to catch issues introduced by this branch, not audit the whole codebase. However, do check whether changed code interacts poorly with surrounding unchanged code (e.g., a new function call that doesn't match an existing function signature).
+
+Classify issues by severity:
+
+- **❌ Critical** — Bugs, security vulnerabilities, breaking changes, data loss risks. These block the PR because they'd cause real harm if deployed.
+- **⚠️ Warning** — Code quality, readability, maintainability issues, missing error handling. These won't break production but make the code harder to work with over time.
+- **💡 Suggestion** — Patterns, optimizations, naming improvements. Nice to have but not worth blocking a PR.
+
+**Severity calibration matters.** Inflating severity wastes reviewer trust — if everything is "critical", the developer starts ignoring the report. Reserve critical for issues that would actually cause production incidents. Style-only concerns (naming, formatting) are suggestions at most. Missing null checks on internal code with guaranteed inputs are warnings, not critical. A SQL injection vector on user-facing input is genuinely critical.
+
+### Step 5: Generate Report
+
+**Output path:**
+- If `TICKET_ID` was provided: `.tickets/{TICKET_ID}/issues.md`
+- Otherwise: `issues.md` (project root)
+
+**Template:** `templates/issues.template.md`
+
+The report includes:
+1. **Verdict** — Clear decision: Ready / Not Ready for PR
+2. **Summary** — Count of files reviewed and issues by severity
+3. **Files Reviewed** — Table with file status, lines changed, and issue count
+4. **Issues by Severity** — Tables with file, line, category, issue, and recommendation
+5. **No code snippets** — Keep the report compact and scannable. The developer already has the diff; what they need is location + what's wrong + how to fix it.
+
+### Step 6: Show Summary in Chat
+
+After generating `issues.md`, display a concise summary in chat:
+
+```
+✅ Self-review complete! Generated issues.md at {output_path}
+
+📊 Summary:
+- Files Reviewed: X
+- ❌ Critical: X issues
+- ⚠️ Warnings: X issues
+- 💡 Suggestions: X issues
+
+Verdict: [✅ Ready to Create PR | ⚠️ Ready with Warnings | ❌ Not Ready for PR]
+[Action message based on verdict]
+```
+
+**Action messages:**
+- ✅ Ready: "All checks passed! You can create the PR."
+- ⚠️ Ready with Warnings: "Consider addressing warnings before PR."
+- ❌ Not Ready: "Fix critical issues before proceeding."
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `templates/issues.template.md` | Report format |
+| `references/frontend.md` | Frontend (React, Vue, Angular, etc.) checklist |
+| `references/backend.md` | Backend (API, database, security) checklist |
+| `references/mobile.md` | Mobile (iOS, Android) checklist |
+| `references/automation.md` | E2E / integration test checklist |
+
+### Project-Specific Files (loaded at runtime if present)
+
+| File | Purpose |
+|------|---------|
+| `.documents-design/*-project-blueprint.md` | Architecture, naming, directory structure, selector strategy |
+| `.documents-design/*-instructions.md` | Code patterns and templates from the codebase |
+| `.documents-design/*-best-practices.md` | Coding standards, rules, anti-patterns |
+
+## Configuration
+
+Required in `.documents-design/project.config.json`:
+
+```json
+{
+  "baseBranch": "main",
+  "excludePaths": ["*.lock", "*.generated.*"]
+}
+```
+
+`excludePaths` is optional — when provided, files matching these glob patterns are skipped during review.
+
+## Verdict Logic
+
+| Verdict | Criteria |
+|---------|----------|
+| **✅ Ready to Create PR** | Zero critical issues |
+| **⚠️ Ready with Warnings** | Zero critical, some warnings or suggestions |
+| **❌ Not Ready for PR** | One or more critical issues |

package/kits/shared/skills/self-review/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "self-review",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Self-review for PROJ-456",
+      "expected_output": "Loads config, runs three-dot diff, detects tech stack from changed files, loads correct domain checklist(s), generates issues.md at .tickets/PROJ-456/issues.md with verdict, shows summary in chat",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I just finished a full-stack feature that touches both React components and Java API endpoints. Can you check my changes before I create the PR?",
+      "expected_output": "Detects both frontend and backend stacks, loads both frontend.md and backend.md checklists, reviews .tsx files against frontend checklist and .java files against backend checklist, generates combined report",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Am I ready to merge? I've got like 50 files changed across the whole monorepo - mostly config updates but also some auth changes",
+      "expected_output": "Handles large diff gracefully with prioritization strategy, flags auth-related changes for deeper review, mentions in summary that review was prioritized, provides accurate verdict",
+      "files": []
+    }
+  ]
+}

package/kits/shared/skills/self-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 (blocks PR)
+> - ⚠️ = Warning (should fix)
+> - 💡 = Suggestion (nice to have)
+
+## ⏱️ 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/self-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 (blocks PR)
+> - ⚠️ = Warning (should fix)
+> - 💡 = Suggestion (nice to have)
+
+## 🔒 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?