Merge Checks

Merge Checks

Audit code changes before or after a merge across 13 quality dimensions. Output: a prioritized task list grouped by file, ready to act on.

Git context

!bash -c 'script="$(find $HOME/.claude/plugins/cache -name gather-context.sh -path "*/merge-checks/*" 2>/dev/null | head -1)"; if [ -z "$script" ]; then echo "ERROR: merge-checks gather-context.sh not found. Try reinstalling the plugin."; exit 1; fi; bash "$script" '"$ARGUMENTS"

Phase 0 — Scope selection

Read the CONTEXT block above and determine what code to review. Then run the full analysis via precompute.sh.

Step 1: If an explicit argument was passed, auto-proceed.

If ARGUMENT is non-empty, show a one-line scope confirmation and run precompute:

"Scope: [description based on argument]"

Then run precompute via Bash (find the script the same way gather-context.sh was found, but search for precompute.sh):

bash "$precompute_script" "$ARGUMENT"

Skip to Phase 1.

Step 2: Compute signals from CONTEXT.

has_committed    = COMMITS_AHEAD > 0
has_uncommitted  = UNCOMMITTED_TOTAL > 0
is_mature        = BRANCH_AGE_HOURS > 72 OR COMMITS_AHEAD > 20
has_other_work   = RECENT BRANCHES or ACTIVE WORKTREES have activity < 24h old
                   AND current branch is cold (LAST_COMMIT_HOURS_AGO > 24 AND !has_uncommitted)

Step 3: Obvious cases — auto-proceed with scope message.

Show the scope message, run precompute via Bash, skip to Phase 1.

Step 4: Ambiguous cases — ask the user.

Triggers:

• Feature + has_committed + has_uncommitted
• Feature + has_committed + is_mature (even without uncommitted)
• Main + has_uncommitted + RECENT_MERGES > 0
• Any branch + has_other_work

Use AskUserQuestion with header: "Review scope" and a descriptive question that includes branch name, commit count, age, and uncommitted count from the CONTEXT.

Build 2-4 options dynamically from this pool (only include relevant ones):

Map the user's selection to the corresponding precompute.sh invocation. Run it via Bash.

Step 5: Run precompute.sh

Find and execute the script:

script="$(find $HOME/.claude/plugins/cache -name precompute.sh -path '*/merge-checks/*' 2>/dev/null | head -1)"
bash "$script" [ARGS]

The output contains all mechanical findings. Proceed to Phase 1.

Instructions

Work through three phases: classify the precompute findings, dispatch reasoning agents, compile report.

Severity levels:

Output format per file:

path/to/file.ext — 2 issues:
  [🔴] [check-type] actionable description with line reference
  [🔵] [check-type] actionable description with line reference

Phase 1 — Classify pre-computed findings

Read each section of the precompute output (from Phase 0) and produce issues. File reads are only needed for ### suppressions (to verify justification comments).

### debug-artifacts (Check 11)

• BLOCKER → 🔴 | WARN → 🟡 | (no debug artifacts found) → clean

### suppressions (Check 7)

• Per entry: check if an explanatory comment exists on the same line or immediately above (read the file)
• No justification → 🔴 | test mock casts (as unknown as typeof fetch) → 🔵 acceptable

### env-coverage (Check 10)

• MISSING per variable → 🟡 with exact name and file reference
• "no .env.example found" → 🟡 (suggest creating one)

### i18n (Check 6) — skip if I18N=false in FEATURES

• Multi-word natural language phrase, label, placeholder, error message, button text → 🔵
• Propose t('namespace.key') following the convention in existing locale files
• Skip: URLs, CSS classes, HTML attributes, technical identifiers

### i18n-consistency (Check 13) — skip if I18N=false or no I18N_DIR

• MISSING:<locale>:<key> → 🟡 (translation key exists in reference locale but missing from target)
• EXTRA:<locale>:<key> → 🔵 (key exists in target locale but not in reference — likely stale)
• (no i18n consistency issues) → clean

### stories (Check 3) — skip if STORIES=false

• MISSING: → 🔵 with 2-3 suggested story variants (empty state, typical usage, edge case)
• FOUND: → check if the component's props changed in this diff; if so → 🔵 (stories need updating)
• SKIP: → ignore

### tests (Check 5) — skip if TESTS=false

• MISSING: source > 80 lines → 🟡 | source ≤ 80 lines → 🔵
• INDIRECT: → 🔵 (only indirect coverage exists)
• FOUND: → no issue

### routes (Check 8) — skip if ROUTES_MANUAL=false

• NOT_REGISTERED: → 🔴

### migrations (Check 9) — skip if MIGRATIONS=false

• MISSING: → 🔴 (schema changed without migration; include suggested generator command)

### seeds (Check 4) — skip if SEEDS=false

• NOT_IMPORTED: → 🔵
• SKIP: → ignore

### shared-types — do not classify here; handled by the reasoning agent in Phase 2.

Phase 2 — Dispatch reasoning agents concurrently

Using the Task tool, launch all three agents in a single message (parallel execution). Before dispatching, read each instructions file to include its content in the agent prompt.

Wait for all three agents to return, then merge their findings with Phase 1 results.

Phase 3 — Compile with retry loop

3a — Aggregate and coverage check

Collect Phase 1 + Phase 2 results. Merge issues for the same file.

REPORTED     = union of all files mentioned in any output
EXPECTED     = every file in FILE MANIFEST
NOT_REVIEWED = EXPECTED − REPORTED

3b — Retry loop (max 1 retry)

Script-driven checks already guarantee 100% coverage via precompute.sh. Retry targets only reasoning agents (A, B, C).

IF NOT_REVIEWED is not empty:
  docs_gap     = NOT_REVIEWED ∩ doc files     → re-dispatch Agent A, scope = docs_gap only
  comments_gap = NOT_REVIEWED ∩ ADDED files  → re-dispatch Agent B, scope = comments_gap only
  shared_gap   = NOT_REVIEWED ∩ source files → re-dispatch Agent C, scope = shared_gap only

  Dispatch retry agents concurrently. Merge results. Re-run coverage check.

  Files still NOT_REVIEWED after 1 retry:
    ## path/to/file.ext  [not-reviewed]
      ⚠️  No agent reported on this file — review manually

3c — Final output format

## Merge check — [MODE]: [SCOPE]
## [N] issues across [M] files
## 🔴 [n] blockers  |  🟡 [n] should-fix  |  🔵 [n] nice-to-have

Skipped (not detected): [checks skipped due to FEATURES=false]
Clean (no issues): [checks where all files reported clean]

─────────────────────────────────────────────────────

## path/to/file/with/most/issues.ext  (N issues)
  - [🔴] [debug]    `debugger` at line 42 — remove before merge
  - [🟡] [tests]    No test file; 130 lines of sync logic — worth covering error paths
  - [🔵] [comments] Add JSDoc to syncExternalCalendarById() explaining the algorithm

## path/to/next/file.ext  (N issues)
  - [🔵] [i18n]     "Save changes" at line 89 — use t('common.save')

─────────────────────────────────────────────────────

Sort: 🔴 → 🟡 → 🔵 within each file. Files with most issues first.

Common Mistakes

Save report

After displaying the output, ask once:

"Would you like to save this report? It will be written to .claude/merge-checks/merge-checks-[branch]-[yyyy-mm-dd].md"

git branch --show-current   # → branch name (replace / with -)
date +%Y-%m-%d

Save to .claude/merge-checks/ if .claude/ exists, otherwise project root. Write the exact Step 3c output. No additions or removals. If no issues were found, skip this step.