gemini-cli/pr_tools_documentation.md

# 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`    |