verify-architecture

Architecture Verification

Assess whether the approach taken on this branch is the right way to solve its problem. Specifically: does it fit existing codebase patterns and information flow, does it introduce unnecessary coupling or implicit dependencies, and is there a better alternative?

Phase 1: Summarize the Problem

If you do not already know what the changes on this branch are supposed to accomplish, STOP and ask the user before continuing.

Write a CONCISE description of the problem the branch is trying to solve, based on your knowledge of the work done so far. This description must contain ONLY the problem -- not any part of the solution. Describe what should work differently afterward, what is currently broken, or what structural problem exists in the code. Do not mention any mechanism, technique, data structure, or approach used to fix it. The analysis agent needs to evaluate the approach independently, so any hint about the implementation will bias its judgment.

Context

• Default base branch: !echo "${GIT_BASE_BRANCH:-main}" (use this unless the user specified a different one)
• Current HEAD: !git rev-parse HEAD

Phase 2: Validate the Diff

Spawn a validate-diff Agent. Provide the base branch name and the problem description from Phase 1.

Based on the agent's response:

• If the diff is empty, STOP and ask the user whether the work has been committed yet or whether the base branch is wrong.
• If it reports changes that don't belong to this branch (i.e., changes you didn't make / the implementer agent wouldn't have made), STOP. Downstream agents review the entire diff and will act on out-of-scope code -- regardless of how the extra changes got there (wrong base branch, stale local ref, a merge, or incidental edits). Proceeding wastes context and causes the analysis agent to review irrelevant code. There is no valid reason to skip this step, even if the extra changes are "expected." The available remedies are: (1) check whether a different base branch produces a clean diff (e.g., if the branch merged in another feature branch, that feature branch may be a better base), (2) ask the user for the correct base branch, or (3) ask which changes to focus on (then explicitly tell the analysis agent in Phase 3 to ignore the rest). Note that sometimes no clean merge base exists -- e.g., the merged branch was based on an older main, so comparing to either base shows unrelated changes. In that case, ask the user.
• If it reports the work looks incomplete, flag that to the user and ask whether to proceed anyway.

Phase 3: Spawn Analysis Agent

Resolve the base branch commit hash:

git rev-parse {base_branch}

Spawn a single analyze-architecture Agent. Provide:

• The problem description from Phase 1
• The base commit hash and feature branch tip hash

Phase 4: Report

Relay the agent's findings to the user. Report every point from the fit, unexpected choices, and verdict sections. Don't reproduce the structural footprint section on its own -- the user already knows what they built -- but reference specific details from it where needed to make the other points clear.

Phase 5: Create Verification Marker

After reporting, create the verification marker so the stop hook knows architecture has been verified for this branch. Get the current branch name and timestamp:

git rev-parse --abbrev-ref HEAD
date -u +%Y-%m-%dT%H:%M:%SZ

Replace any / in the branch name with _ (e.g., mngr/my-feature becomes mngr_my-feature). Then use the Write tool (without checking if the directory exists) to create .reviewer/outputs/architecture/{sanitized_branch_name}.md with the content Verified at {timestamp}.

Important: when to re-run

Architecture verification is per-branch, not per-commit. You do NOT need to re-run it after every commit. However, if you later make changes that fundamentally alter the approach (new abstractions, changed data flow, different module boundaries), you should run /verify-architecture again to confirm the new direction is sound.