adk-pr-triage

ADK Pull Request Triage Orchestrator (adk-pr-triage)

This skill orchestrates the analysis, triage, and review process of GitHub pull requests (PRs) submitted to the google/adk-python repository. When a user provides a PR number or URL, follow this multi-phase workflow by delegating/calling the specific sub-skills:

[!IMPORTANT]

CRITICAL EXECUTION RULES: STOP AND ASK DECISION GATES
MANDATORY PR ASSIGNMENT BLOCK GATE:
BEFORE doing any code analysis, diff-fetching, checkout, or workspace modifications, you MUST verify if the pull request is assigned to you.
Run the verification helper script with assignment checking enabled:
.venv/bin/python .agents/skills/adk-pr-analyze/scripts/triage_pr.py <pr_number> --skip-update --check-assignment
If the PR is NOT assigned to you:

STOP calling tools and ask immediately: You must present the PR Assignment Block gate in your chat response.

Wait for Instructions: Do NOT perform any checkout or workspace modifications in this turn.
PR Analysis is strictly read-only: Do NOT create branches, modify workspace files, or post any comments in your first response (unless performing PR assignment under the takeover gate).

Triage Decision Gate: You must present the PR Analysis Report first, and explicitly ask the user:

"Would you like me to push back on this pull request? (If yes, select one of the push-back reasons or write custom feedback, and I will author a professional and precise review message for you to review. If no, I will draft an approval response highlighting the positive aspects of the implementation.)" Wait for instructions before performing any branch creation or Gerrit push.

Phase 1: Triage and Analysis (Read-Only)

Verify PR Assignment: Run the verification script with the --check-assignment flag:
```
.venv/bin/python .agents/skills/adk-pr-analyze/scripts/triage_pr.py <pr_number> --skip-update --check-assignment
```
- If Exit Code 3 (Assignment Block): Parse the script's output for current assignees. You MUST stop calling tools immediately, present the following assignment block decision gate in your chat response, and wait for the user's input:
  "⚠️ Pull Request Assignment Block Pull Request #<pr_number> is NOT assigned to you. (Current assignees: <assignee_list>).
  
  Would you like to take over this Pull Request?
  - [Option 1]: Yes, take over Pull Request #<pr_number> (Assign the PR to myself and proceed with the triage analysis).
  - [Option 2]: No, do not take over (Stop executing)."
- If the user chooses Option 1: Run the assignment command:
```
gh pr edit <pr_number> --add-assignee "@me" --repo google/adk-python
```
  Then proceed.
- If the user chooses Option 2 (or declines): Stop executing immediately and do not run any further tools or operations. State that triage has terminated.
- If Exit Code 0 (Success): The PR is already assigned to you. Proceed directly.
Delegate to adk-pr-analyze: Follow the instructions in the adk-pr-analyze skill (located at .agents/skills/adk-pr-analyze/SKILL.md) to fetch the PR metadata, check contributor CLA, and present the structured PR analysis report.
Do NOT write code or create branches: Keep this phase strictly read-only.
Ask for Approval: Present the report and explicitly call out the Review Decision Gate.

Phase 2: Stop and Ask for Push-Back or Local Review (Interactive Gate)

Present the PR Analysis Report generated by adk-pr-analyze in your response. At the end of your report, stop calling tools and output this explicit message:

🛑 Review Decision Gate

I have completed my in-depth analysis of Pull Request #<pr_number>. Please review the findings above.

How would you like to proceed with this Pull Request?

[Option 1]: Push Back (Draft a professional, constructive feedback response with recommendations for the author).

[Option 2]: Local Review (Checkout the PR locally under pr-triage-[pr_number]-[short_desc], rebase onto the latest main, and run the /adk-review skill to thoroughly verify and polish before pushing to Gerrit).

Phase 3: Action Execution (Subsequent Turn)

Once the user provides their decision, perform the tailored operations in your subsequent turns:

Branch A: Push Back

Analyze the Push-Back Focus: Read the user's specific feedback or selected points of concern.
Draft Constructive Feedback: Author a highly structured, objective, and supportive response that teaches the contributor while insisting on quality.
Include Concrete Recommendations: Quote specific files/lines in their diff and provide complete, refactored code blocks in your comments so they can easily apply the fixes. Reference the relevant ADK style guides.
Present the Draft: Format your draft using the GitHub Review Draft Template below.

Branch B: Local Review (Checkout & Revise)

If the user selects Local Review, run the following structured sequence:

Step 0: Update the PR Head Branch on GitHub (Mandatory Sync):
- Rule: BEFORE downloading or checking out the pull request locally, you MUST trigger an update on the remote GitHub pull request to align it with the latest remote base branch (main).
- Run the verification & sync helper script to update the branch:
```
.venv/bin/python .agents/skills/adk-pr-analyze/scripts/triage_pr.py <pr_number>
```
- What it does: This script automatically checks the Google CLA signature status again, attempts to update the PR branch on GitHub by rebasing onto main, and if rebase-update is blocked, falls back to updating via a merge commit. It handles all outputs and fallbacks gracefully.
Step 1: Checkout the PR to a Local Branch:
- Branch naming convention: pr-triage-<pr_number>-[short_desc] (e.g. pr-triage-5875-parallelize-tool-union).
- Fetch the latest main branch from origin before checking out the PR:
```
git fetch origin main
```
- Fetch the pull request ref directly from the remote GitHub endpoint:
```
git fetch https://github.com/google/adk-python.git pull/<pr_number>/head:pr-triage-<pr_number>-[short_desc]
```
- Checkout to the newly created local branch:
```
git checkout pr-triage-<pr_number>-[short_desc]
```
Step 2: Preserve the Commit Message & Append Merge Reference:
- CRITICAL: You MUST preserve the exact same commit message from the pull request!
- Determine if the PR contains a single commit or multiple commits:
  - Single Commit: Retrieve the exact original commit message:
```
git log -1 --pretty=%B
```
  - Multiple Commits: Squash them into a single local commit first, keeping the overall PR Title and PR Body as the exact commit message, AND preserving the original author. An elegant way to squash is:
```
# 1. Capture the original author
ORIG_AUTHOR=$(git log -1 --format='%an <%ae>')

# 2. Reset to base and commit with the original author
git reset --soft $(git merge-base HEAD origin/main)
git commit --author="$ORIG_AUTHOR" -m "<PR message>"
```
- Append "Merge <PR link>" to the very end of the commit message (separated by a blank line). If the PR metadata contains linked issues in closingIssuesReferences, you MUST also append "closes https://github.com/google/adk-python/issues/<issue_number>" for each linked issue on new lines. Use this shell command structure to do it in one-shot:
```
git commit --amend -m "$(git log -1 --pretty=%B)

Merge https://github.com/google/adk-python/pull/<pr_number>
closes https://github.com/google/adk-python/issues/<issue_number>"
```
- Note: When you run git commit/amend, the Gerrit commit-msg hook will automatically execute and append the Change-Id: footprint if not already present.
Step 3: Rebase on top of Main:
- Run the rebase command to place the CL commit on top of the latest local remote tracking main branch:
```
git rebase origin/main
```
Step 4: Execute Code Verification & Polishing:
- Trigger the local review process by invoking the /adk-review skill!
- Follow its comprehensive guidelines to audit edge cases, style compliance, dependencies, and test validation. Work in partnership with the user to revise the local changes as needed.
Step 5: Squash User Revisions & Push to Gerrit:
- If the user requests to push to Gerrit, squash/amend all local workspace revisions into the single original commit:
  - CRITICAL: You MUST preserve the exact same commit message, including the Merge <PR link> footer, any closes <Issue link> footers, and the original Change-Id: footer. Do NOT change it.
  - Command to squash all changes into the current commit without opening an editor:
```
git commit -a --amend --no-edit
```
- Push the single finalized CL commit to Gerrit:
```
git push origin HEAD:refs/for/main
```

GitHub Review Draft Template

Format the authored review response as a premium markdown snippet block:

# 💬 GitHub PR Review Draft Message
*Copy and paste this response directly into the GitHub review interface:*
---
### PR Review: <State (Request Changes / Comment / Approve)>
Hello @<author_username>! Thank you very much for contributing this pull request to improve ADK. I've conducted a thorough architectural and style review of your implementation against our design guidelines and standards.
Here is the feedback and a few suggested changes to align your patch with ADK's principles:
#### 🔴 Major Concerns / Blocks
1. **[Concern 1 Title, e.g., Import from init.py is not allowed]**
   - **Target Code**: [filename.py:L100-L105](file:///absolute/path/to/src/google/adk/file_name.py#L100-L105)
   - **Issue**: [Detailed explanation of why this violates design/architectural rules, referencing the relevant ADK skill like `adk-architecture` or `adk-style`]
   - **Suggested Correction**:
     ```python
     # Provide full, drop-in replacement code block
     ```
2. **[Concern 2 Title, e.g., Missing Unit Tests for Edge Cases]**
   - **Target Code**: [test_filename.py](file:///absolute/path/to/tests/unittests/test_filename.py)
   - **Issue**: [Detail what is missing, e.g., "We need verification coverage of boundaries like empty string and negative values."]
#### 🟡 Style & Quality Nits
1. **[Style Nit, e.g., Eager Logging formatting]**
   - **Target Code**: [filename.py:L42](file:///absolute/path/to/src/google/adk/file_name.py#L42)
   - **Suggestion**: Use lazy-evaluated `%` template syntax:
     ```python
     # Corrected:
     logging.info("User registered: %s", user_id)
     ```
2. **[Typing Nit, e.g., Optional[X] instead of X | None]**
   - **Target Code**: [filename.py:L15](file:///absolute/path/to/src/google/adk/file_name.py#L15)
   - **Suggestion**: Prefer more concise union type hint `X | None`.
#### 🟢 Positive Aspects
- [Highlight stellar work, e.g., "Excellent Pydantic v2 validation logic!" or "Highly readable and clean docstrings!"]
Please let me know if you have any questions on these suggestions, and let's work together to get this PR merged!

Tips & Best Practices

[!IMPORTANT] Command Sandbox Policy: When running commands via run_command, you MUST ONLY use gh or git commands. Commands like curl, wget, or direct HTTP network requests are strictly forbidden and will be automatically denied. Furthermore, you MUST ONLY use simple commands without special characters (such as ;, &, |, $, `, <, >, \n, \r, (, ), {, }, \). The runner environment runs a security policy that automatically denies any commands containing these characters. Always run clean gh or git commands directly with arguments, without redirections, command chaining, or shell expansions.

[!TIP] Always verify the baseline behavior in your active workspace before claiming something is a bug or invalid. Reading the current source files using view_file gives you full context. [!IMPORTANT] When referencing files and line numbers in your reports and draft reviews, always use clickable markdown file links of format [filename.py](file:///absolute/path/to/file#L100-L120) without surrounding backticks around the brackets. Ensure the links represent valid absolute file paths in the local workspace.