- Backend: FastAPI app with all models, services, schemas, routes - Admin Panel: Next.js dashboard with all modules (CRM, POS, repairs, warranties, billing, notifications, etc.) - Ecommerce: storefront (submodule) + product catalog - AI Agents: .agents/ skill library for Antigravity IDE - Docs: architecture, billing, notification gateway markdown - Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
341 lines
16 KiB
Markdown
341 lines
16 KiB
Markdown
---
|
|
description: Unified PR review for frontend and backend repositories with functionality, code-quality, and flow analysis
|
|
---
|
|
|
|
# Review My PR
|
|
|
|
Use this workflow when the user asks to review a pull request by saying `frontend`, `backend`, `common`, `core`, or `milo`, or by providing a PR URL/number.
|
|
|
|
This is a **read-only review workflow**. Do not modify source files, switch the user's active branch, approve, merge, comment on, or close a PR. If fixes are requested after the review, use a separate implementation workflow.
|
|
|
|
## Non-negotiable rule
|
|
|
|
**You MUST NOT make any changes to the current workspace.** This includes but is not limited to:
|
|
|
|
- Switching, creating, or deleting branches
|
|
- Checking out PR branches or commits
|
|
- Modifying, creating, or deleting files
|
|
- Installing dependencies or running build commands that mutate the workspace
|
|
- Changing Git configuration or hooks
|
|
- Modifying generated artifacts (graphify-out, intentgraph-out, node_modules, build outputs)
|
|
|
|
**You MUST ONLY review the changes in the PR.** No changes are required or permitted during this workflow. If the user wants fixes, they will request them separately after the review.
|
|
|
|
## Supported inputs
|
|
|
|
Resolve the user's input as follows:
|
|
|
|
| User input | Repository |
|
|
| --- | --- |
|
|
| `frontend` / `ui` | `ReloPortal/reloportal-ui` |
|
|
| `backend` / `milo` / `milo-services` | `ReloPortal/reloportal-milo-services` |
|
|
| `common` | `ReloPortal/reloportal-common` |
|
|
| `core` | `ReloPortal/reloportal-core` |
|
|
| PR URL | Extract repository and PR number from the URL |
|
|
| Repository plus PR number | Use the specified repository and PR |
|
|
|
|
If the user provides only `backend`, inspect the open PRs in `reloportal-milo-services` first. If the user provides a specific repository, inspect only that repository.
|
|
|
|
## Phase 1 — Resolve the PR
|
|
|
|
### 1. Identify the repository
|
|
|
|
- Normalize aliases using the table above.
|
|
- If the input is ambiguous, ask whether the user means `common`, `core`, or `milo`.
|
|
- Do not infer a repository from the currently open editor file unless the user explicitly asks for that repository.
|
|
|
|
### 2. Find the latest open PR
|
|
|
|
Prefer GitHub CLI when available:
|
|
|
|
```bash
|
|
gh pr list --repo ReloPortal/<repository> --state open --limit 10 --json number,title,headRefName,baseRefName,author,updatedAt,isDraft,url
|
|
```
|
|
|
|
If `gh` is unavailable, unauthenticated, or cannot resolve the repository, use an available GitHub API or browser/API fallback. Do not expose or request secrets in command output.
|
|
|
|
If using Git refs as a fallback, fetch pull-request refs without changing the current branch:
|
|
|
|
```bash
|
|
git ls-remote origin 'refs/pull/*/head'
|
|
git fetch origin '+refs/pull/<number>/head:refs/remotes/origin/pr/<number>'
|
|
```
|
|
|
|
Use the most recently updated **open, non-merged PR** as the default candidate. A high PR number alone is not proof that it is the latest open PR.
|
|
|
|
### 3. Handle missing or multiple PRs
|
|
|
|
- If exactly one relevant open PR is found, report the selected PR and continue.
|
|
- If multiple plausible PRs are found, show a numbered list containing PR number, title, author, updated time, draft status, and URL. Stop and ask the user which PR to review.
|
|
- If no PR can be discovered, ask the user for a PR URL or number. Do not guess.
|
|
- If the user supplies a PR explicitly, use it even if it is not the latest PR, but verify that the repository and PR exist.
|
|
|
|
## Phase 2 — Establish the review baseline
|
|
|
|
Before reading implementation details:
|
|
|
|
1. Record the repository, PR number, URL, title, body, author, base branch, head branch, and head SHA.
|
|
2. Read the PR title and description as the primary statement of intent and acceptance criteria.
|
|
3. Determine the comparison base:
|
|
- Prefer the PR's declared base branch.
|
|
- For these repositories, expect `main_dev` unless the PR metadata says otherwise.
|
|
4. Fetch refs without checking out or altering the user's active branch.
|
|
5. Inspect:
|
|
|
|
```bash
|
|
git status --short --branch
|
|
git diff --stat <base-sha>...<head-sha>
|
|
git diff --name-status <base-sha>...<head-sha>
|
|
git log --oneline --decorate <base-sha>..<head-sha>
|
|
```
|
|
|
|
6. Check for unrelated local changes and do not include them in the review.
|
|
7. Group changed files by feature, layer, and user journey before reviewing individual hunks.
|
|
8. Read changed functions and their surrounding files fully. Do not review only isolated diff hunks.
|
|
|
|
## Phase 3 — Context and impact mapping
|
|
|
|
Follow the repository's context-first guidance before broad source exploration:
|
|
|
|
1. Run the available preflight checks:
|
|
|
|
```bash
|
|
intentgraph doctor
|
|
command -v graphify || true
|
|
test -f graphify-out/graph.json && echo "graphify OK" || echo "MISSING graphify"
|
|
test -f intentgraph-out/index.json && echo "intentgraph index OK" || echo "MISSING intentgraph index"
|
|
```
|
|
|
|
2. Query Intentgraph and Graphify with the PR title, feature terms, and changed symbols before using broad grep/find searches.
|
|
3. Load only bounded, relevant context. If a graph or index is unavailable, report that limitation and use targeted source inspection as a fallback.
|
|
4. Map:
|
|
- Entry points and callers.
|
|
- Imports and downstream consumers.
|
|
- API endpoints, request/response contracts, and shared types.
|
|
- Database entities, migrations, repositories, services, controllers, routes, and jobs for backend changes.
|
|
- Pages, components, hooks, Redux slices, selectors, and services for frontend changes.
|
|
- Tests that cover the affected behavior.
|
|
5. Identify the blast radius and any cross-repository contract dependencies. For example:
|
|
- `reloportal-common` entity or migration changes must be checked against `reloportal-core` and `reloportal-milo-services` consumers.
|
|
- `reloportal-milo-services` API changes must be checked against frontend callers and shared contracts.
|
|
- `reloportal-ui` service, type, route, or shared-component changes must be checked at every call site.
|
|
6. Run a second, refined context query after the initial mapping and discard unrelated results.
|
|
|
|
## Phase 4 — Three-level review
|
|
|
|
Perform all three levels unless the user explicitly asks for only one.
|
|
|
|
### Level 1 — Functionality and requirement correctness
|
|
|
|
Answer: **Does the PR do what its title, description, and acceptance criteria say it should do?**
|
|
|
|
Check:
|
|
|
|
- Every stated requirement is implemented, not just partially wired.
|
|
- The main success path works from entry point through persistence/API response/UI rendering.
|
|
- Inputs, outputs, field names, types, status transitions, and error contracts remain correct.
|
|
- Existing behavior is preserved unless the PR explicitly changes it.
|
|
- Null, empty, duplicate, boundary, retry, and partial-failure cases are handled.
|
|
- Authorization, role, tenant, supplier, client, and ownership checks are correct.
|
|
- Backend validation exists at the trust boundary; frontend validation is not treated as sufficient.
|
|
- New migrations are compatible with existing data and deployment order.
|
|
- Transactions, idempotency, soft deletes, retries, and concurrency behavior are correct where applicable.
|
|
- All affected dashboard, reporting, export, notification, and asynchronous paths are considered.
|
|
- The implementation does not silently normalize, rename, default, or discard contract fields.
|
|
|
|
Use severity:
|
|
|
|
- **Blocker:** The stated feature does not work or corrupts/losses data.
|
|
- **Critical:** A common valid input or required permission path fails.
|
|
- **High:** Important requirement or edge case is missing and likely affects users.
|
|
- **Medium:** The feature works but has a meaningful correctness gap.
|
|
- **Low:** Minor requirement ambiguity or low-impact inconsistency.
|
|
|
|
### Level 2 — Code quality, performance, scalability, and security
|
|
|
|
Review against repository rules first, then applicable industry standards.
|
|
|
|
#### All repositories
|
|
|
|
- Type safety: no unjustified `any`, unsafe casts, misleading optional fields, or duplicated structural types.
|
|
- Clear ownership and single responsibility for functions, modules, services, and components.
|
|
- Complexity: avoid accidental O(n²), repeated database queries, repeated serialization, and unnecessary work in loops or renders.
|
|
- Correct async behavior: independent work is parallelized where safe; failures are not swallowed; cleanup and cancellation are present where needed.
|
|
- Input validation, authorization, injection safety, sensitive-data handling, and safe error messages.
|
|
- Logging is useful, non-sensitive, and consistent with repository conventions.
|
|
- No dead code, unreachable branches, hidden side effects, magic values, or duplicated utilities.
|
|
- Public interfaces and shared abstractions remain backwards-compatible or update every consumer.
|
|
|
|
#### Backend (`common`, `core`, `milo`)
|
|
|
|
- Query correctness and efficiency: indexes, joins, pagination, N+1 behavior, selected columns, and query cardinality.
|
|
- Transaction boundaries, lock scope, rollback behavior, race conditions, and idempotency.
|
|
- Migration safety: forward-only behavior, existing-row compatibility, nullable/default strategy, index/constraint naming, rollback/roll-forward implications, and deploy ordering.
|
|
- Repository/service/controller/route separation and consistent validation/error handling.
|
|
- API compatibility, status codes, DTO/schema alignment, and authorization at the service boundary.
|
|
- Queue/job/event behavior, retry safety, duplicate delivery, and observability where relevant.
|
|
- Shared entity changes belong in `reloportal-common`; do not duplicate schema definitions in `reloportal-core`.
|
|
|
|
#### Frontend (`reloportal-ui`)
|
|
|
|
- React rendering behavior, hook dependencies, stale closures, cleanup, stable keys, and appropriate memoization.
|
|
- Ant Design and project component conventions, controlled/uncontrolled form behavior, loading/error/empty states, and accessibility.
|
|
- Redux only for shared data; selectors and state updates are correctly scoped and memoized where useful.
|
|
- Server-side pagination/search for tables; no accidental local filtering of paginated data.
|
|
- API calls use project service abstractions and endpoint constants.
|
|
- No frontend fallback chains or invented API values; use the exact API contract and explicit display sentinels.
|
|
- Bundle/render performance, unnecessary requests, race conditions, and optimistic update consistency.
|
|
|
|
Use severity:
|
|
|
|
- **Critical:** Security issue, data corruption, production crash, leak, or severe scalability failure.
|
|
- **High:** Significant performance, maintainability, type-safety, or reliability risk.
|
|
- **Medium:** Clear quality issue with limited current impact.
|
|
- **Low/Nit:** Readability or consistency improvement with no material risk.
|
|
|
|
### Level 3 — Flow, integration, regression, and test coverage
|
|
|
|
Answer: **Can the change be introduced without breaking the original product or technical flow?**
|
|
|
|
Trace the real journey in both directions:
|
|
|
|
1. User/event entry point.
|
|
2. Page/controller/route or job.
|
|
3. Hook/service/use case.
|
|
4. Repository/database/API or state update.
|
|
5. Downstream response consumers.
|
|
6. Notifications, exports, reports, dashboards, and follow-up workflows.
|
|
|
|
Check:
|
|
|
|
- Every caller of changed functions, methods, types, constants, endpoints, and shared components.
|
|
- Every consumer of changed request and response shapes.
|
|
- Existing status, role, tenant, and visibility gates.
|
|
- Existing create, read, update, delete, retry, cancel, submit, approve, reject, and resubmit flows.
|
|
- Cross-repository compatibility and package/version expectations.
|
|
- Migration and deployment sequencing, including old application/new schema and new application/old data windows.
|
|
- Feature flags, configuration, environment differences, and backward compatibility.
|
|
- Loading, empty, error, timeout, unauthorized, and partial-success states.
|
|
- Whether new or changed behavior has regression tests at the correct layer.
|
|
- Whether tests assert behavior and failure modes rather than implementation details.
|
|
- Missing tests for boundary conditions, authorization, persistence, API contracts, and end-to-end flow.
|
|
|
|
Use severity:
|
|
|
|
- **Blocker:** Existing user journey is broken, inaccessible, or causes data loss.
|
|
- **High:** Silent regression, incompatible contract, unsafe migration, or missing critical flow coverage.
|
|
- **Medium:** Fragile integration or missing meaningful regression test.
|
|
- **Low:** Minor test or documentation gap with no likely production impact.
|
|
|
|
## Phase 5 — Validation
|
|
|
|
Run only safe, relevant read-only validation commands for the repository and changed areas. Do not install dependencies or mutate generated artifacts without user approval.
|
|
|
|
Prefer:
|
|
|
|
- Targeted unit/integration tests for changed behavior.
|
|
- Existing test files for affected modules.
|
|
- Typecheck.
|
|
- Lint with the repository's configured command.
|
|
- Build or compile checks when practical.
|
|
- Migration/schema validation for database changes.
|
|
- API contract or browser checks for endpoint/UI changes.
|
|
- Coverage comparison when available.
|
|
|
|
Record commands that could not run and why. Do not treat a passing lint check as proof of functionality.
|
|
|
|
## Phase 6 — Findings and verdict
|
|
|
|
Findings must be evidence-based. Do not report speculative issues as defects.
|
|
|
|
For each finding include:
|
|
|
|
- Severity.
|
|
- Review level: Functionality, Quality, or Flow.
|
|
- Exact file and line range.
|
|
- What is wrong.
|
|
- Why it matters in this PR's actual flow.
|
|
- Concrete recommended fix.
|
|
- Confidence: Confirmed, Likely, or Needs verification.
|
|
|
|
Sort findings by severity, then by review level and file location.
|
|
|
|
Use this output format:
|
|
|
|
```text
|
|
## PR Review Summary
|
|
|
|
**Repository:** <repository>
|
|
**PR:** #<number> — <title>
|
|
**URL:** <url>
|
|
**Base:** <base branch / sha>
|
|
**Head:** <head branch / sha>
|
|
**Author:** <author>
|
|
**Files changed:** <count>
|
|
**Journeys / features touched:** <list>
|
|
|
|
## Review scope and evidence
|
|
|
|
- Requirements taken from: <PR title/body/linked issue>
|
|
- Context sources: <Graphify / Intentgraph / targeted source inspection>
|
|
- Validation run: <commands and outcomes>
|
|
- Validation not run: <commands and reasons>
|
|
|
|
## Findings
|
|
|
|
| Severity | Level | Location | Confidence | Finding | Impact | Recommended fix |
|
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
| Blocker/Critical/High/Medium/Low | Functionality/Quality/Flow | `file:line` | Confirmed/Likely/Needs verification | ... | ... | ... |
|
|
|
|
## Functionality assessment
|
|
|
|
- Requirements met: <summary>
|
|
- Requirements partially met: <summary>
|
|
- Edge cases checked: <summary>
|
|
- API/schema/data concerns: <summary>
|
|
|
|
## Code-quality assessment
|
|
|
|
- Performance and scalability: <summary>
|
|
- Maintainability and standards: <summary>
|
|
- Security and reliability: <summary>
|
|
|
|
## Flow and regression assessment
|
|
|
|
- Original journeys checked: <summary>
|
|
- Cross-repository consumers checked: <summary>
|
|
- Regression risks: <summary>
|
|
- Test coverage gaps: <summary>
|
|
|
|
## Positive observations
|
|
|
|
- <specific strengths worth preserving>
|
|
|
|
## Assumptions and follow-ups
|
|
|
|
- <only unresolved items or required verification>
|
|
|
|
## Verdict
|
|
|
|
- [ ] Ready to merge as-is
|
|
- [ ] Ready after Medium/Low improvements
|
|
- [ ] Changes required — fix High findings
|
|
- [ ] Do not merge — Blocker/Critical findings remain
|
|
|
|
**Recommended next action:** <concise action>
|
|
```
|
|
|
|
If there are no findings, explicitly state that no defects were identified within the reviewed scope and list important unverified areas.
|
|
|
|
## Rules
|
|
|
|
- Review the PR, not unrelated local changes.
|
|
- Use the PR description as intent, but verify it against code and tests.
|
|
- Never assume the highest PR number is the latest open PR.
|
|
- Never silently choose among multiple plausible PRs.
|
|
- Never alter the user's working branch or workspace files during discovery or review.
|
|
- Never fix findings during this workflow.
|
|
- Never make a finding without a concrete location and impact.
|
|
- Separate confirmed defects from assumptions and missing evidence.
|
|
- Review tests as part of the change, but do not excuse a defect because tests are absent.
|
|
- If the PR is too large for a reliable review, say so, review by feature area, and identify the unreviewed remainder.
|