ai-proj-helper/skills-dev/pull-request-plugin/skills/SKILL.md

name, description

name	description
pull-request	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

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

Push 前必须检查 PR 状态 ⭐

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

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.

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

Types: feature, fix, refactor

Example:

/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:

   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

# 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

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.

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:

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

   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):

   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.