review-changes

name	review-changes
user-invocable	true
description	Reviews the microservices touched by a set of changes - by default the whole current feature branch versus its merge-base with main, plus any uncommitted work. Runs the review-microservice skill on each changed microservice and the review-architecture skill scoped to those microservices and their graph neighbors, then consolidates one report. Use before merging a branch or before committing working-tree changes.

This skill composes the two review skills over a diff. It does not re-implement their checks - it resolves what changed, then drives review-microservice per changed microservice and review-architecture scoped to the changed set. The separation of concerns between the two is deliberate: per-microservice internals come from review-microservice, cross-cutting concerns from review-architecture, and this skill must not duplicate either.

Workflow

Copy this checklist and track your progress:

Change review:
- [ ] Step 1: Resolve the diff scope
- [ ] Step 2: Map changed files to microservices
- [ ] Step 3: Review each changed microservice
- [ ] Step 4: Architectural review scoped to the changed set
- [ ] Step 5: Consolidate the report

Step 1: Resolve the Diff Scope

Determine which files changed. The default depends on the current branch; an explicit argument overrides it.

First identify the current branch and the repository's default branch:

branch=$(git rev-parse --abbrev-ref HEAD)
git status --porcelain                          # staged, unstaged, and untracked (always part of the scope)

Use the repository's actual default branch if it is not main (check git symbolic-ref refs/remotes/origin/HEAD or git remote show origin); substitute it for main below.

• On a feature branch (not the default branch) - the default. Review the whole branch plus uncommitted work, the pre-merge review:

  base=$(git merge-base main HEAD)
  git diff --name-only "$base" HEAD             # committed on this branch
  

  Union that with the working-tree list.
• On the default branch (main) - there is no feature branch to diff, so default to the changes since the last tagged release, plus uncommitted work:

  tag=$(git describe --tags --abbrev=0 2>/dev/null)
  git diff --name-only "$tag" HEAD              # only if a tag was found
  

  If git describe finds no tag (empty output / non-zero exit), fall back to reviewing the uncommitted work only.
• uncommitted argument - regardless of branch, narrow to just the working tree (git status --porcelain, including untracked files) and skip any committed-diff.

If the resolved file list is empty, report that there is nothing to review and stop.

State the mode (branch-vs-default, since-last-release, or uncommitted-only), the base commit or tag, and the resolved file list to the user before proceeding.

Step 2: Map Changed Files to Microservices

For each changed file, walk up the directory tree to the nearest ancestor containing a manifest.yaml - that directory is the owning microservice. Collect the distinct set of changed microservices.

Also note, separately from that set:

• Changes to main/main.go, config.yaml, env.yaml, or main/topology.mmd - these are application-composition changes that feed the architectural review in Step 4 even when no microservice directory changed.
• Changes to framework packages (connector/, service/, application/, and the other library packages listed in the repository's root CLAUDE.md). These are out of scope for this skill, which reviews microservices. List them so the user knows they were seen and skipped, and suggest a plain code review for them.

Present the changed-microservice set and the out-of-scope list. If the set is empty but composition files changed, proceed to Step 4 only.

Step 3: Review Each Changed Microservice

For each microservice in the changed set, run the review-microservice skill's full workflow on that directory, one microservice at a time, in this context. Do not launch subagents to review microservices in parallel unless the user explicitly asks to run the reviews concurrently or asks for a faster review; the default is sequential and in-context. Review the whole microservice, not only its changed files - a change frequently breaks or leaves stale something elsewhere in the same directory (a new endpoint that should have updated a shared helper, a renamed field a sibling handler still reads, a test that no longer covers the new path).

When ranking findings, put the ones that touch changed lines first; whole-service findings that predate this branch come after, labelled as pre-existing so the reader can tell regressions from latent issues.

Keep each microservice's findings under its own heading for the consolidated report.

Step 4: Architectural Review Scoped to the Changed Set

Run the review-architecture skill, but scope its findings. Build the full system map (Step 1 of that skill is cheap - it reads manifests), then focus the cross-cutting checks on:

• the changed microservices, and
• their immediate graph neighbors - the microservices that call them or that they call (from the downstream sections and *api imports). A change breaks coupling at the edges, so a neighbor one hop away is in scope; the rest of the system is context, not audited.

Prioritize the architectural checks most sensitive to a diff: newly introduced dependency cycles, new or removed downstream edges and whether the manifests still match the code, new events and their pairing, boundary shifts (an endpoint or table that moved between microservices), main/main.go startup-group ordering for added microservices, and cross-service workflow wiring when a workflow or task changed. Report system-wide findings that the changed set introduced or made worse; do not re-report unrelated latent architecture issues elsewhere in the system.

Step 5: Consolidate the Report

Merge the per-microservice reports from Step 3 and the scoped architectural report from Step 4 into one document. De-duplicate: if the same underlying issue surfaced in both a per-service and the architectural pass, keep the more specific statement once and drop the other. Order everything by severity (Critical, then Warning, then Info), and within a severity put change-introduced findings ahead of pre-existing ones.

# Change Review

## Summary
Scope (branch-vs-default, since-last-release, or uncommitted-only), the base commit or tag, the changed
microservices, and out-of-scope changes noted. Overall assessment and the count of findings by severity.

## Per-Microservice Findings

### {hostname}
(the review-microservice report for this microservice, change-introduced findings first)

(repeat for each changed microservice)

## Architectural Findings
(the review-architecture report, scoped to the changed set and its neighbors)

## Conclusion
Prioritized action items, change-introduced issues first.

Present the consolidated report to the user.