From 45f6be00e7a4ee89ec35969dc97ddd1126882cf4 Mon Sep 17 00:00:00 2001 From: Keith Guerin Date: Tue, 24 Mar 2026 22:37:17 -0700 Subject: [PATCH] docs(ux): incorporate Jacob's protocol for diff minimization and automated audits --- packages/extensions/ux-extension/GEMINI.md | 15 ++++++++++----- .../ux-extension/skills/_ux_finish-pr/SKILL.md | 18 +++++++++++++----- 2 files changed, 23 insertions(+), 10 deletions(-) diff --git a/packages/extensions/ux-extension/GEMINI.md b/packages/extensions/ux-extension/GEMINI.md index 38b3d594d9..83cb5a0a84 100644 --- a/packages/extensions/ux-extension/GEMINI.md +++ b/packages/extensions/ux-extension/GEMINI.md @@ -25,14 +25,19 @@ underlying "rigor." ## 🚨 Standard Operating Procedures (Agent Only) 1. **Worktree Strategy**: ALWAYS use `_ux_git-worktree` for task isolation. -2. **Submission Rigor**: ALWAYS use `/_ux_finish-pr` for final pushes. Never +2. **Diff Minimization**: ALWAYS minimize diffs. Never move code between files + while making logic changes in the same step. Separate refactors + (zero-modification moves) into their own commits before applying logic + changes. +3. **Submission Rigor**: ALWAYS use `/_ux_finish-pr` for final pushes. This + includes running `/review-frontend` to perform an automated audit. Never push manually. -3. **UI Review**: Use `_ux_designer` to audit components against the v1.0 +4. **UI Review**: Use `_ux_designer` to audit components against the v1.0 principles. -4. **Remediation**: Use **`/review-and-fix`** if CI checks fail on GitHub to +5. **Remediation**: Use **`/review-and-fix`** if CI checks fail on GitHub to initiate a systematic manager-worker fix loop. -5. **No Shortcuts**: Never use `--no-verify`. Protect the PR from CI failures. -6. **Task Finality**: ALWAYS run `npm run build` or `npm run typecheck` to +6. **No Shortcuts**: Never use `--no-verify`. Protect the PR from CI failures. +7. **Task Finality**: ALWAYS run `npm run build` or `npm run typecheck` to verify structural integrity before declaring any task as "complete". ## Mandatory Workflow Triggers diff --git a/packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md b/packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md index ff5822970a..a76559a740 100644 --- a/packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md +++ b/packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md @@ -26,6 +26,7 @@ You are a senior co-author assistant. Your goal is to ensure this PR passes CI o ```bash npm run preflight ``` +- **Automated Audit**: You MUST run `/review-frontend ` and address any issues found. This provides an automated audit of your changes to catch common mistakes before a maintainer review. - **Constraint**: Passing individual tests is NOT enough. `preflight` ensures `tsc --build` passes, catching TypeScript inference bugs that unit tests miss. - **TDD Fallback**: If `preflight` fails, you must create a local reproduction test before attempting a fix. @@ -47,11 +48,18 @@ You are a senior co-author assistant. Your goal is to ensure this PR passes CI o ``` - **Diff Verification**: After reverting, run `git diff origin/main...HEAD` on the specific reverted files to ensure their diff is completely empty. -### 7. Final Submission -- **Commit Strategy**: Maintain a **Two-Tier** commit history to optimize for reviewer speed (30s vs 10m): - 1. **Tier 1 (Base)**: A single squashed Conventional Commit (e.g., `feat(ui): ...`) containing the core feature and all *previously addressed* review cycles. - 2. **Tier 2 (Latest)**: Separate, granular commits addressing only the **very last** round of reviewer feedback. - - **Action**: Use `git rebase -i` or `git reset --soft` to squash all older review-fix commits into the Tier 1 base. Ensure only the commits from the current (latest) review cycle remain as separate entries. +### 7. Diff Minimization & Refactor Isolation (Jacob's Protocol) +- **Mandatory Two-Step Process**: Never move code between files AND make logic changes in the same commit. +- **Refactor Commit**: If your task requires moving code or reorganization, create a "zero-modification" commit first. Verify that `npm run typecheck` passes but no functional logic has changed. +- **Logic Commit**: Apply logic changes or new features in a separate, follow-up commit. +- **Goal**: Ensure the diff for the refactor commit is purely about movement, and the diff for the logic commit is purely about behavior. + +### 8. Final Submission +- **Commit Strategy**: Maintain a structured commit history to optimize for reviewer speed (30s vs 10m): + 1. **Tier 1 (Base Refactor)**: A single commit for all "zero-modification" refactors (file moves, reorgs). + 2. **Tier 2 (Base Logic)**: A single squashed Conventional Commit (e.g., `feat(ui): ...`) containing the core feature logic and all *previously addressed* review cycles. + 3. **Tier 3 (Latest Feedback)**: Separate, granular commits addressing only the **very last** round of reviewer feedback. + - **Action**: Use `git rebase -i` or `git reset --soft` to organize commits into these tiers. Ensure refactors are ALWAYS isolated from logic. - **Push**: `git push origin HEAD --force-with-lease`. - **Link**: You MUST provide the full, clickable GitHub PR link (e.g., `https://github.com/google-gemini/gemini-cli/pull/23487`) as the final output of this skill. This allows the user to immediately verify the update.