Finalize

/finalize — Pre-push Local-CI Gate

This skill is the final local gate before pushing and opening a PR.

In the dev loop, deep bug-finding and code cleanup are /quality's job (the loop default) and test-suite work is /test's. /finalize is optional: run it when you want a full local CI gate before /ship pushes — a final simplification sweep plus typecheck/lint/sharded-tests/build/doc-validation.

It guarantees three outcomes:

1. A final code-simplification sweep is complete (/quality already did the heavy lifting)
2. Docs changed by /test are still valid
3. Local CI checks pass

It does not guarantee that remote PR review is complete after a push. GitHub's first visible check list can look quiet before delayed checks, bot reviews, and inline comments arrive. After pushing a finalized branch, hand off to /ship or an equivalent PR poll loop. Use the ship-lane cadence: poll immediately after a push, wait 270s if CI has not registered, wait 720s while CI is running, and wait 1800s only when CI is done and the PR is just waiting on review.

Usage: /finalize

Execution Mode: Autonomous

This command runs end-to-end without user interaction. Do NOT:

• Ask the user to confirm, choose, or approve anything.
• Pause between phases to request direction.
• Stop on non-fatal warnings — log them and continue.
• Request clarification on ambiguous simplifications — skip the risky ones and note in the final report.
• Ask before reverting your own work (e.g., Phase 3i drift check reverts simplifier edits silently).

Outputs are exactly two things: the Phase 4 summary, and fatal-error messages (typecheck, lint, build, or self-caused test failures). Every other decision is made by the agent based on the rules in this file.

Guardrails (read once, apply everywhere)

• Do NOT touch the public Mintlify site: docs.json and any root-level *.mdx, plus the root-level dirs chat/, tools/, changelog/, configuration/, computer-use/, context-packs/, getting-started/, guides/, automations/, lanes/, cto/. Exception: the SDK tab (sdk/*.mdx and the SDK entries in docs.json) is in scope when the branch changed packages/sdk, packages/chat-ui, MCP honesty, or the apps/ade-cli embedded profile / parentDeathWatchdog — keep those pages aligned, do not rewrite other Mintlify product pages. Internal docs under docs/ are in scope.
• Do NOT modify docs/OPTIMIZATION_OPPORTUNITIES.md — append-only, human-curated.
• Do NOT run apps/mcp-server checks; the MCP server was removed. The agent surface is apps/ade-cli.
• Do NOT skip the sharded test run or substitute project-subset runs for it. /finalize is the gate that runs the full suite.
• Do NOT use bare pkill -f vitest / pkill -f node. Always scope to apps/desktop, apps/ade-cli, or apps/web.
• Do NOT declare remote PR review clean from /finalize alone — see Phase 3j handoff.
• Do NOT let a simplification break Windows. Parity is a default requirement for all new code, so every Phase 2 rewrite is subject to ../quality/references/windows-quirks.md — a "cleaner" === path comparison, a child.kill() replacing terminateProcessTree, a hand-built shell string replacing structured argv, or a lock check narrowed to EEXIST are all regressions, not simplifications. Platform branches that look redundant usually are not.
• Do NOT treat a Windows-host local run as authoritative. WINDOWS_PORT.md records that POSIX-only fixtures, Unix-socket browser tests, chmod assertions, and some SQLite teardown races fail on a Windows host by design; compare against that baseline before calling the gate red.

Pipeline Overview

Phase 1: Analyze & Prepare Code Simplification         (lead)
Phase 2: Code Simplification                           (agents)
Phase 3: CI sync + local verification                  (lead)
Phase 4: Summary                                       (lead)

Phase 1: Analyze & Prepare Code Simplification

1a. Get changed source files

git diff main --name-only | grep -E '\.(ts|tsx)$'

1b. Pre-filter for simplification

git diff main --numstat | awk '$1+$2 > 10 {print $3}' | grep -E '\.(ts|tsx)$'

Exclude from simplification:

• Tiny changes (<10 lines added+removed)
• Test files (*.test.ts, *.test.tsx)
• Config files (*.config.*, *.cjs)
• Generated files, lock files

1c. Split into simplifier batches

• < 5 files -> 1 batch
• 5-15 files -> 2 batches
• 16+ files -> 3 batches

Keep related files together (service + its types + its callers).

1d. Capture branch context for agents

git diff main --stat | tail -20
git log main..HEAD --oneline

1e. Snapshot pre-Phase-2 file list (used by 3i drift check)

git diff main --name-only | sort > /tmp/finalize-branch-files.txt

Phase 2: Code Simplification

Spawn 1–3 simplifier agents based on batch size from Phase 1c. Use TeamCreate when available; parallel Agent calls otherwise. Per the global git-worktrees policy, do not pass worktree isolation — all agents work in the main directory.

Use subagent_type: "code-simplifier:code-simplifier" for each batch (note the full namespaced form — plain "code-simplifier" is not a valid agent type).

Prompt each with:

• The list of files in their batch
• Branch context (what feature/area was changed)
• Instructions: focus on recently modified code, don't refactor untouched code
• Explicit safety rule: before removing code that looks dead (unused helpers, "unused" local components, stale state), grep for references including the file's colocated *.test.ts(x) neighbor. Test expectations often lag behind feature refactors — removing "unused" code can silently break a test suite that will only light up in Phase 3e. When in doubt, leave it and note in the report.
• Diff-only scope: git diff main -- <file> first; if zero diff, do not edit (a previous run tried to simplify files it thought were modified, and wasted time on unchanged code).
• Typecheck after every file: cd apps/desktop && npx tsc --noEmit -p . 2>&1 | head -20.

Wait for all simplifier agents to complete before moving to Phase 3.

Docs, mobile, CLI, and TUI parity reviewers have moved to /test — they should run before /finalize. Do not re-spawn them here.

Phase 3: CI Sync + Local Verification

3a. CI sync

Read .github/workflows/ci.yml and verify:

• Any new source directories are covered by existing test patterns
• Any new apps/packages would need new CI jobs (unlikely for typical changes)
• The ci-pass gate job includes all required jobs in its needs array

3b. Install dependencies (all apps)

Run in parallel — ensures lock files are in sync with package.json (mirrors CI's npm ci):

cd apps/desktop && npm install
cd apps/ade-cli && npm install
cd apps/web && npm install

After install, check for uncommitted lock file changes — a dirty lock file means package.json was modified without regenerating the lock, which will break CI's npm ci:

git diff --name-only -- '*/package-lock.json'

This is a hard gate: if any lock file is dirty, stage it (git add <path>) and report it in the Phase 4 summary so the user commits it before pushing. Do not proceed past 3b with dirty lock files.

3c. Typecheck all apps

Run in parallel to match CI jobs (typecheck-desktop, typecheck-ade-cli, typecheck-web):

cd apps/desktop && npm run typecheck
cd apps/ade-cli && npm run typecheck
cd apps/web && npm run typecheck

3d. Lint desktop

Mirrors the lint-desktop CI job: errors fail, and so does any ade-ui/* warning count that grows past lint-baseline.json (see docs/design/notices.md).

cd apps/desktop && npm run test:lint-tooling && npm run lint:ci