A PR Diagram Review Packet Before Architecture Changes Merge

Architecture changes are hard to review from a pull request alone. A diff can show which files moved, which endpoint changed, and which tests ran, but it rarely shows whether the system still makes sense as a whole. Before a significant architecture change merges, the reviewer needs a small packet of evidence: the diagram, the API contract check, the CI state, and the unresolved review comments.

This workflow turns a pull request into that packet. It uses diagrams to make the proposed shape visible, OpenAPI checks to catch contract drift, GitHub Actions evidence to avoid guessing about failing checks, and review-comment follow-up so the merge decision is not based on stale threads.

In Short

For architecture-heavy pull requests, do not ask reviewers to infer the system shape from file diffs alone. Ask for a packet: one current diagram, one contract-drift check, one CI summary, and one pass over unresolved review comments. GitHub’s pull request and Actions documentation are the source of record for the review and CI surfaces, while the OpenAPI Specification defines the contract language when API behavior is part of the change.

The packet should be small enough to read during normal review. It should not become a second design doc. Its job is to answer what changed, what depends on it, what checks say, and what humans still object to.

Who this is for

This is for engineering teams that let agents or automation prepare non-trivial pull requests, especially changes that alter service boundaries, internal APIs, routing, data flow, or deployment shape.

It is not only for large organizations. A small team can benefit from this packet when a change touches enough files that reviewers start saying, “I think I understand it.” That sentence is a warning sign. The goal is to replace intuition with a few inspectable artifacts.

Starter workflow

Start from the pull request, not from an abstract architecture exercise. Use Render pull request architecture diagrams with PR Lens to turn the changed files and relationships into a diagram the reviewer can inspect. The diagram should label the components affected by the PR and make dependency direction obvious. If the picture is too broad, narrow it to the changed path.

Next, check whether the architecture change includes API movement. If it changes routes, schemas, status codes, auth boundaries, or generated clients, run Gate pull requests on OpenAPI breaking changes. Treat the result as a review gate, not a trivia report. If the change is intentionally breaking, the packet should say where that decision is documented and which clients are expected to update.

Then inspect automation evidence. GitHub Actions is useful because it attaches check runs to the pull request, but a red check still needs interpretation. Use Inspect failing GitHub Actions checks and plan fixes with gh-fix-ci to summarize which checks failed, where the failure happened, and whether the fix belongs in this branch or in the pipeline.

Finally, close the loop on human review. Use Address GitHub PR review comments from the current branch with gh-address-comments after the diagram and checks are current. That order matters because comment resolution should happen against the final evidence, not an earlier draft of the branch.

Recommended ASE skills

The core packet starts with PR Lens for the diagram. It is the skill that makes architecture impact visible before the reviewer digs through changed files. Pair it with the OpenAPI breaking-change gate whenever the PR touches API contracts. The official OpenAPI specification is the reference point for what contract shape means; use the skill to bring that check into the pull request flow.

For CI evidence, use gh-fix-ci to inspect GitHub Actions failures and turn them into a concrete repair plan. GitHub’s Actions documentation explains the check-run surface, but the review packet needs the practical answer: whether the branch is broken, the workflow is flaky, or the failure is unrelated.

For the final human loop, use gh-address-comments to work through review comments from the current branch. A merge packet is not complete if reviewers have unresolved concerns, even when the diagram and CI are clean. For a structured summary, add Review pull requests with structured summaries, checks, and follow-up prompts using PR-Agent. The minimum stack is PR Lens, OpenAPI gate, gh-fix-ci, gh-address-comments, and one structured-review pass.

What to watch

Watch for diagrams that look polished but do not correspond to the actual diff. The diagram should be regenerated or updated late enough in review that it reflects the branch under consideration. A stale diagram is worse than no diagram because it gives reviewers false confidence.

Watch for contract checks that are treated as advisory when they should block merge. If a pull request breaks an API, the reviewer needs to know whether the break is approved, versioned, documented, and tested. Do not bury that decision in a passing CI summary.

Also watch for comment cleanup that only marks threads resolved. The useful output is not a green conversation list; it is the branch change, explanation, or explicit reviewer decision that justifies resolution. Keep the packet focused on evidence a maintainer can verify.

FAQ

Does every pull request need a diagram?

No. Use this packet when the change affects architecture, dependencies, service boundaries, API contracts, or deployment behavior. A small bug fix usually needs tests and review, not a diagram.

What if the OpenAPI check reports a breaking change that the team wants?

Keep it in the packet and label it intentional. The reviewer should see the compatibility decision, migration note, and client impact before merge. The problem is not every breaking change; the problem is an accidental one.

Should an agent resolve review comments automatically?

It can prepare fixes and responses, but the merge owner should still inspect the final branch. For architecture changes, the human decision point belongs after the diagram, contract check, CI evidence, and comment pass are all current.