Branch Review

Use this when the user asks whether a branch is production-ready, merge-ready, an actual improvement, or asks for a branch/PR review or PR summary grounded in the current diff.

Goal

Return a concrete merge-readiness verdict based on the code, tests, and current validation state. Findings lead. Summaries are secondary.

What the user wants to know:

• Is the work COMPLETE?
• Is the work CORRECT?
• Is the work SAFE to merge and release?
• Is the work a REAL improvement, either for the user experience or the codebase?
• Was anything important missed that should have been included?

Read-Only First Pass

Unless the user explicitly asks for fixes, begin in review mode.

1. Do not reread injected AGENTS.md files. Use .agents/README.md only when the diff spans an ambiguous workflow, and docs/README.md only when the owning contract is unclear.
2. Check repository state with read-only git commands:
   • git status --short
   • git branch --show-current
   • git diff --stat origin/main...HEAD
   • git diff --name-only origin/main...HEAD
   • git diff --stat
   • git diff --name-only
   • git diff --cached --stat
   • git diff --cached --name-only
   • git ls-files --others --exclude-standard
3. If the user provides a different base or range, use that instead of origin/main...HEAD.
4. If origin/main...HEAD cannot be resolved, inspect remotes/default branch state with read-only git commands and state the exact base assumption before reviewing.
5. Review both committed branch changes and working-tree changes. Do not ignore modified, staged, or untracked files just because origin/main...HEAD is empty.
6. Read any changed docs/plans that claim completion. Treat them as hints, not proof.

Contract Audit

For every meaningful change, inspect the owning contract:

Required Checks

Look for these before considering the branch ready:

• Every review claim cites evidence gathered in the current turn (file:line or command output) or is explicitly marked [unverified] / [assumed].
• Cluster-data paths carry clusterId through requests, scopes, caches, state, events, navigation, persistence keys, and actions.
• Object references crossing boundaries carry clusterId, group, version, kind, and concrete namespace/name when applicable.
• Object catalog remains the source of truth for discovery, existence, GVK/GVR identity, Browse namespace metadata, and cluster listings; namespace LIST rows remain owned by the namespaces refresh domain.
• Backend status semantics are projected as status, statusState, statusPresentation, and optional statusReason where primary status is rendered.
• Relationship navigation uses ResourceLink.ref and catalog-backed identity, not frontend kind/name reconstruction.
• List/table payloads are served from refresh snapshot/query paths, not backend/resources detail/action services.
• Refresh domain metadata, behavior classes, timing, backend registrations, frontend registrations, diagnostics, and tests align through the shared domain contract.
• Query-backed resource stream WebSocket messages remain liveness signals; rows, filtering, sorting, facets, totals, and page metadata stay on the HTTP snapshot/query path.
• Snapshot/query payloads and stream signals agree on identity, scope, liveness, and permission behavior for the same table/list surface.
• Permission-denied or restricted-RBAC behavior remains visible in diagnostics.
• Auth, recovery, runtime operation, stream, and cleanup behavior stays scoped to the affected cluster.
• YAML read/save/merge/ownership flows preserve full cluster and GVK identity and the shared field-policy contract.
• Shared contracts do not add parallel frontend/backend enums, descriptors, schemas, or registries without parity tests.
• Frontend resource reads use dataAccess, app-shell/persisted-state reads use appStateAccess, and direct fetch remains confined to the refresh client.
• New frontend UI uses existing components, CSS files, tokens, aliases, and GridTable where applicable.
• Tests cover the changed behavior at the closest useful level.

Validation Sequence

Run focused tests first when the branch has clear areas:

• Backend shared/resource-model/refresh changes: focused mise exec -- go test packages.
• Frontend changes: targeted Vitest specs and mise exec -- npm run typecheck --prefix frontend.
• Runtime operations/logs/shell/port-forward/drain: focused backend workflow tests plus affected frontend lifecycle/orchestrator tests.
• Broad frontend/shared changes: consider mise exec -- wails3 task qc:knip.

Before a final "ready" verdict on non-documentation or non-comment-only work, run:

mise exec -- wails3 task qc:prerelease
git diff --check
git status --short

If mise exec -- wails3 task qc:prerelease cannot run or fails, report the exact command and first concrete failure. Do not call the branch ready.

mise exec -- wails3 task qc:prerelease includes qc:lint-fix, so inspect changed files afterward.

For documentation-only or comment-only branches, mise exec -- wails3 task qc:prerelease may be skipped, but still run git diff --check and git status --short before the verdict.

Output Format

For review findings:

1. Findings first, ordered by severity.
2. Each finding includes file/line, problem, impact, and concrete fix direction.
3. Then open questions or assumptions.
4. Then validation state.
5. Then short summary/verdict.

For no findings:

• Say that no merge-blocking issues were found.
• State exactly what was validated.
• State residual risk or untested areas.

For PR summaries:

• Use the real diff/range.
• Describe user-visible behavior and operational impact.
• Avoid touched-file inventories, commit hashes, and unverified claims.