mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-07-22 15:51:18 -07:00
docs: add comprehensive CI failure investigation reports and UX contribution guide
This commit is contained in:
Keith Guerin
@@ -0,0 +1,142 @@
|
||||
# Gemini CLI: PR Tooling & Automation Guide
|
||||
|
||||
This document provides a comprehensive overview of the specialized skills,
|
||||
custom commands, and extension tools available for managing Pull Requests within
|
||||
the Gemini CLI project. These tools are designed to automate verification,
|
||||
enforce standards, and streamline the review-to-merge lifecycle.
|
||||
|
||||
---
|
||||
|
||||
## 1. Built-in Agent Skills (`.gemini/skills/`)
|
||||
|
||||
These skills are available globally within the workspace and provide structural
|
||||
workflows for different phases of the PR lifecycle.
|
||||
|
||||
### **A. `pr-creator`**
|
||||
|
||||
- **Purpose**: Guides the creation of high-quality PRs.
|
||||
- **Workflow**:
|
||||
1. Verifies current branch is not `main`.
|
||||
2. Enforces a descriptive commit message following Conventional Commits.
|
||||
3. Locates and applies the repository's `.github/PULL_REQUEST_TEMPLATE.md`.
|
||||
4. **Mandatory**: Runs `npm run preflight` locally before pushing.
|
||||
5. Uses `gh` CLI to create the PR from a temporary description file.
|
||||
- **Key Principle**: Never push to `main`; never ignore the PR template.
|
||||
|
||||
### **B. `code-reviewer`**
|
||||
|
||||
- **Purpose**: Conducts professional, multi-dimensional code reviews.
|
||||
- **Target**: Can review remote PRs (`gh pr checkout`) or local uncommitted
|
||||
changes.
|
||||
- **Analysis Pillars**: Correctness, Maintainability, Readability, Efficiency,
|
||||
Security, Edge Cases, and Testability.
|
||||
- **Key Principle**: Execute `npm run preflight` early to catch automated
|
||||
failures before performing human-level analysis.
|
||||
|
||||
### **C. `async-pr-review`**
|
||||
|
||||
- **Purpose**: Executes a background review job to avoid blocking the main
|
||||
session.
|
||||
- **Mechanism**: Uses an "Agentic Asynchronous Pattern" where a background shell
|
||||
script invokes a headless `gemini -p` instance.
|
||||
- **Workflow**: Creates an ephemeral worktree, runs preflight, and generates a
|
||||
`final-assessment.md`.
|
||||
- **Key Principle**: Prevents git lock conflicts by using isolated worktrees in
|
||||
`.gemini/tmp/async-reviews/`.
|
||||
|
||||
### **D. `pr-address-comments`**
|
||||
|
||||
- **Purpose**: Helps the author systematically resolve feedback.
|
||||
- **Workflow**: Uses `scripts/fetch-pr-info.js` to gather all comments and
|
||||
provides a checklist (✅ for resolved, [number] for open threads).
|
||||
- **Key Principle**: The agent summarizes but waits for user guidance before
|
||||
fixing issues.
|
||||
|
||||
---
|
||||
|
||||
## 2. UX Extension Skills (`ux-extension/`)
|
||||
|
||||
These skills are part of the specialized UX team extension and prioritize
|
||||
"finish line" polish and TUI design principles.
|
||||
|
||||
### **A. `_ux_finish-pr`**
|
||||
|
||||
- **Purpose**: Expert PR maintenance and final polish.
|
||||
- **Core Principle**: **"Always maintain a clean, focused diff by resolving
|
||||
merge conflicts early and squashing into a single feature commit."**
|
||||
- **Unique Features**:
|
||||
- **TDD Fallback**: If a fix fails 2-3 times, it mandates creating a local
|
||||
reproduction test case.
|
||||
- **Snapshot Review**: Mandates manual review of updated `.snap` or `.svg`
|
||||
files after running tests with `-u`.
|
||||
- **Force-Push safety**: Uses `--force-with-lease`.
|
||||
|
||||
### **B. `_ux_git-worktree`**
|
||||
|
||||
- **Purpose**: Implements the **Base Folder Strategy**.
|
||||
- **Rules**: All work happens in sibling directories (e.g., `main/`,
|
||||
`feature-name/`).
|
||||
- **Workflow**: Automates `git worktree add` and semantic PR checkouts (e.g.,
|
||||
`pr-123-fix-logo`).
|
||||
- **Key Principle**: Prevents macOS sandbox interference by including
|
||||
`main/.git` in the trusted environment.
|
||||
|
||||
### **C. `_ux_designer`**
|
||||
|
||||
- **Purpose**: Ruthlessly enforces the **v1.0 Design Principles**.
|
||||
- **Principles**:
|
||||
1. **Signal over Noise**: Mandates collapsible components
|
||||
(`<ExpandableText>`).
|
||||
2. **Coherent State**: Global state belongs in the "Bottom Drawer" (Footer).
|
||||
3. **Intent Signaling**: Long-running tasks must telegaph progress via
|
||||
spinners.
|
||||
4. **Strategic Color**: Functional use of color only; no "rainbow" text.
|
||||
|
||||
---
|
||||
|
||||
## 3. Custom Commands (`.gemini/commands/`)
|
||||
|
||||
These shortcuts inject specific context or trigger focused agent loops.
|
||||
|
||||
- **`/pr-review <PR_NUMBER>`**: Triggers the `oncall/pr-review.toml` prompt. It
|
||||
automates checkout, runs `npm run preflight`, and drafts a professional
|
||||
approval/feedback message.
|
||||
- **`/review-and-fix <target>`**: Initiates the "Pickle Rick" worker loop. It
|
||||
conducts a review, identifies findings, and then spawns a manager-worker loop
|
||||
to fix every issue until validation (`npm run build`, `test`, `lint`,
|
||||
`typecheck`) passes.
|
||||
- **`/frontend`**: Injects the complete source code of `packages/cli` and key
|
||||
core files, along with the `Strict Development Rules`.
|
||||
- **`/prompt-suggest`**: Analyzes agent failures and suggests high-level system
|
||||
prompt improvements to prevent recurrence.
|
||||
|
||||
---
|
||||
|
||||
## 4. How to Use These Tools Correctly
|
||||
|
||||
To prevent the "recursive failure loop" identified in the pattern investigation,
|
||||
follow these usage rules:
|
||||
|
||||
1. **Start with Worktrees**: Always use `_ux_git-worktree` to check out a PR.
|
||||
This keeps your `main` branch clean and avoids sandbox issues.
|
||||
2. **Use `/frontend` for UI Tasks**: This ensures the agent is aware of the
|
||||
`Strict Development Rules` (e.g., no `any`, use `waitFor` correctly).
|
||||
3. **Run `npm run preflight` via `pr-creator`**: Never manually push a PR.
|
||||
Always call the `pr-creator` skill, as it forces the full validation suite.
|
||||
4. **Finish with `_ux_finish-pr`**: When a PR is "done," use this skill to
|
||||
squash commits, resolve final conflicts with `main`, and verify snapshots in
|
||||
a neutral environment.
|
||||
5. **Don't Bypass Hooks**: Never use `git commit --no-verify`. If pre-commit
|
||||
hooks fail, use `_ux_finish-pr` to diagnose the root cause.
|
||||
|
||||
---
|
||||
|
||||
## 5. Summary of PR verification lifecycle
|
||||
|
||||
| Phase | Tool/Skill | Command |
|
||||
| :--------------- | :----------------- | :----------------------------- |
|
||||
| **Checkout** | `_ux_git-worktree` | `worktree-manager.sh pr <#> ` |
|
||||
| **Fixing** | `review-and-fix` | `/review-and-fix staged` |
|
||||
| **UI Audit** | `_ux_designer` | `Audit <Component.tsx>` |
|
||||
| **Final Polish** | `_ux_finish-pr` | `activate_skill _ux_finish-pr` |
|
||||
| **Submission** | `pr-creator` | `activate_skill pr-creator` |
|
||||
Reference in New Issue
Block a user