---
name: pull-request
description: Use when starting new development tasks, creating pull requests, reviewing code, or managing PR feedback cycles on Gitea. Triggers on /pr commands or when user mentions PR, pull request, code review, or branch creation.
---

# PR Workflow

Standardized PR lifecycle for Gitea: start task → create PR → review → update → merge.

## Prerequisites

```bash
# One-time setup
brew install tea
tea login --url https://gitea.pipexerp.com
```

## Push 前必须检查 PR 状态 ⭐

**每次 `git push` 之前，必须检查当前分支关联的 PR 状态：**

```bash
BRANCH=$(git branch --show-current)
# 用 Gitea API 检查该分支的 PR（包括 open 和 closed）
# - PR 还 open → 正常 push
# - PR 已 merge → 禁止 push，切回 main 拉最新，新建分支重新提交
# - 无 PR → 正常 push（后续 /pr create 会创建）
```

**规则：**
- PR 已 merge 后**绝对不能**再往该分支 push
- 发现 PR 已 merge → 自动：`git checkout main && git pull` → 新建分支 → cherry-pick 或重新提交变更
- 向用户报告情况，不要静默处理

## Commands

### /pr start `<type>` `<REQ-id>` `<name>`

Start fresh branch from origin/main.

```bash
git fetch origin
git checkout -b <type>/REQ-<id>-<name> origin/main
```

**Types:** `feature`, `fix`, `refactor`

**Example:**
```bash
/pr start feature REQ-123 user-login
# Creates: feature/REQ-123-user-login from origin/main
```

### /pr create

Create PR on Gitea from current branch.

**Steps:**
1. **Check for existing PR first:**
   ```bash
   tea pr list --state open --head $(git branch --show-current)
   ```
   - If PR exists: Report existing PR URL and skip creation
   - If no PR: Continue to step 2

2. Get task ID from branch name or ai-proj session, ask if missing
3. Analyze commits with `git log origin/main..HEAD`
4. Generate title: `[REQ-xxx] Brief description`
5. Generate description (What + Why)
6. Push branch and create PR

```bash
# Check existing PR
BRANCH=$(git branch --show-current)
EXISTING_PR=$(tea pr list --state open --head "$BRANCH" 2>/dev/null | head -1)

if [ -n "$EXISTING_PR" ]; then
    echo "PR already exists: $EXISTING_PR"
    exit 0
fi

# Create new PR
git push -u origin HEAD
tea pr create --title "[REQ-123] Add user login" --body "$(cat <<'EOF'
## What
Added user authentication with session management.

## Why
Users need to log in to access protected features.
EOF
)" --head feature/REQ-123-user-login --base main
```

### /pr review `[url|number]`

Review a PR for code quality and tests.

**Checklist:**

| Check | Verify |
|-------|--------|
| Logic | Code does what it claims, edge cases handled |
| Readability | Clear naming, reasonable complexity |
| Patterns | Consistent with codebase conventions |
| Tests exist | New/changed code has test coverage |
| Tests pass | All tests green |

**Steps:**
1. Fetch PR details: `tea pr view <number>`
2. Get diff: `tea pr diff <number>`
3. Review against checklist
4. Summarize findings with file:line references
5. Recommend: approve or request changes

### /pr update

Address review feedback.

**Steps:**
1. Fetch PR comments: `tea pr view <number>`
2. Make requested changes
3. Commit with descriptive message
4. Push: `git push`
5. Comment on PR that changes are ready

```bash
git add -A && git commit -m "Address review feedback: fix edge case handling"
git push
tea pr comment <number> --body "Feedback addressed, ready for re-review."
```

### /pr list

Show open PRs for current repo.

```bash
tea pr list --state open
```

## Branch Naming

```
feature/REQ-123-user-login
fix/REQ-456-order-calculation
refactor/REQ-789-api-cleanup
```

Format: `<type>/REQ-<id>-<brief-description>`

## PR Format

**Title:**
```
[REQ-123] Brief description of change
```

**Description:**
```markdown
## What
One paragraph describing the change.

## Why
One paragraph explaining the motivation.
```

## ai-proj Integration

- Check session context for current task ID
- Extract from branch name if available: `feature/REQ-123-...` → `REQ-123`
- Ask user if not found: "What's the task ticket? (e.g., REQ-123)"
- Read-only: no status updates to ai-proj

## tea CLI Reference

| Command | Description |
|---------|-------------|
| `tea pr list` | List PRs |
| `tea pr create --title T --body B --head H --base main` | Create PR |
| `tea pr view N` | View PR details |
| `tea pr diff N` | View PR diff |
| `tea pr merge N` | Merge PR |
| `tea pr close N` | Close PR without merging |
| `tea pr comment N --body "..."` | Add comment |
| `tea pr review N --approve` | Approve PR |
| `tea pr review N --reject --body "..."` | Request changes |

## Workflow

```
/pr start feature REQ-123 user-auth
    ↓
(implement feature, commit changes)
    ↓
/pr create
    ↓
(reviewer: /pr review 42)
    ↓
(if changes needed: /pr update)
    ↓
tea pr merge 42
```

## Finishing a Branch

Verify tests pass, then create PR. Use after implementation is complete.

**Core principle:** Verify tests → Create PR → Done.

### Process

1. **Verify Tests** — Run project's test suite before creating PR:
   ```bash
   npm test / cargo test / pytest / go test ./... / mvn test
   ```
   - Tests fail → Stop, show failures, fix first. Cannot proceed.
   - Tests pass → Continue to step 2.

2. **Create PR** — Use `/pr create` (checks for existing PR, avoids duplicates). Report PR URL.

3. **Cleanup Worktree** (if applicable):
   ```bash
   git worktree list | grep $(git branch --show-current)
   # If in worktree, ask user to confirm removal
   git worktree remove <worktree-path>
   ```

**Never:** Create PR with failing tests. Skip test verification. Force-push without request.

## Plan Execution

Load plan → create branch → execute tasks in batches → report for review between batches.

### Process

1. **Load Plan**: Read plan file, review critically, raise concerns before starting
2. **Setup Branch**: Use `/pr start` or manual `git checkout -b <type>/<name> origin/main`
3. **Execute Batch**: Default 3 tasks per batch, mark in_progress → completed
4. **Report**: Show implementation + verification output. Say: "Ready for feedback."
5. **Continue**: Apply feedback, execute next batch, repeat
6. **Complete**: Use "Finishing a Branch" workflow above

### Stop Conditions

- Hit blocker (missing dependency, test fails, instruction unclear)
- Plan has critical gaps preventing starting
- Verification fails repeatedly

**Ask for clarification rather than guessing.**