/1-analyze

Step 1: Analyze (Discovery & Context)

> **Navigation**: [← Main Workflow](../workflow-steps.md) | [Step 2: Triage →](2-triage.md)

**Purpose**: Understand the PR/MR and gather all review comments.

**Platform Note**: Commands below show GitHub (`gh`) examples. Check session context for `git_platform:` and consult `Skill(leyline:git-platform)` for GitLab (`glab`) / Bitbucket equivalents.

**Skip when**: You're already familiar with the PR/MR and comments (e.g., you just received the review notification).

1.1 Identify Target PR/MR

# GitHub - Current branch or specified PR
gh pr view --json number,url,headRefName,body,title

# GitLab
glab mr view

1.2 Check and Add PR/MR Description (if missing)

Verify the PR/MR has a description and add one if it's missing:

   # Check if PR has a description
   PR_BODY=$(gh pr view --json body -q .body)

   # If empty or whitespace-only, generate and add description
   if [[ -z "$(echo "$PR_BODY" | tr -d '[:space:]')" ]]; then
     echo "PR is missing a description. Generating one..."

     # Gather information for description generation
     PR_TITLE=$(gh pr view --json title -q .title)
     COMMIT_MSGS=$(git log --oneline origin/main..HEAD --format="%s" | head -10)
     FILE_STATS=$(git diff --stat origin/main..HEAD | tail -1)
     CHANGED_FILES=$(git diff --name-only origin/main..HEAD | head -20)

     # Create a temporary file for the description
     TEMP_DESC=$(mktemp)

     # Generate the description with actual content
     # This should be done by analyzing the actual PR data, not using placeholders
     cat > "$TEMP_DESC" << 'TEMPLATE_EOF'
## Summary

[Analyze commits and changes to write 1-3 sentences explaining what this PR does]

## Changes

[Generate bullet list from commit messages and changed files - replace with actual changes]

## Test Plan

[Generate verification steps based on what was changed]

- [ ] Quality gates pass: `make test && make lint`

---
*PR description auto-generated by /fix-pr*
TEMPLATE_EOF

     # Add the description to the PR using REST API (more reliable than gh pr edit)
     # Get repo info for API call
     REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
     PR_NUM=$(gh pr view --json number -q .number)

     gh api "repos/${REPO}/pulls/${PR_NUM}" -X PATCH -F body=@"$TEMP_DESC" --silent

     # Clean up
     rm -f "$TEMP_DESC"

     echo "✓ PR description added"
   fi

**CRITICAL: Generate Real Content, Not Placeholders**

When implementing this step, you MUST: 1. **Analyze the actual PR data** - Don't just copy the template 2. **Write the description to a temp file** - This preserves formatting 3. **Use REST API instead of `gh pr edit`** - More reliable, avoids GraphQL permission issues

**Step-by-step implementation:**

   # 1. Gather PR metadata
   PR_TITLE=$(gh pr view --json title -q .title)
   COMMITS=$(git log origin/main..HEAD --format="%s")
   FILES=$(git diff --name-only origin/main..HEAD)
   STATS=$(git diff --stat origin/main..HEAD)

   # 2. Create temp file
   TEMP_DESC=$(mktemp)

   # 3. Write actual description (NOT placeholders!)
   cat > "$TEMP_DESC" << EOF
## Summary

${ACTUAL_SUMMARY_HERE}

## Changes

${ACTUAL_CHANGES_HERE}

## Test Plan

${ACTUAL_TEST_PLAN_HERE}

---
*PR description auto-generated by /fix-pr*
EOF

   # 4. Get repo/PR info for API call
   REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
   PR_NUM=$(gh pr view --json number -q .number)

   # 5. Apply using REST API (more reliable than gh pr edit)
   gh api "repos/${REPO}/pulls/${PR_NUM}" -X PATCH -F body=@"$TEMP_DESC" --silent

   # 6. Cleanup
   rm -f "$TEMP_DESC"

**Description Generation Guidelines:**

• **Summary**: 1-2 sentences explaining the purpose from commit messages
• **Changes**: Bullet list derived from:
• Commit message headlines
• Changed file paths (group by feature/module)
• Significant additions from git diff stats
• **Test Plan**: Basic verification steps:
• Unit tests for modified modules
• Integration tests if multiple modules changed
• Quality gates (lint, test, build)
• Use conventional commit type from branch name or commits (feat, fix, refactor, etc.)

**Common Formatting Issues and Solutions:**

❌ **WRONG - Escaped newlines in description:**

   "## Summary\n\nThis adds a feature\n\n## Changes\n\n- Item 1"

This happens when using `--body` with a string that gets JSON-escaped.

✅ **CORRECT - Using REST API with temp file:**

   # Write to file with real newlines
   cat > /tmp/pr-desc.md << EOF
## Summary

This adds a feature

## Changes

- Item 1
EOF

   # Use REST API (more reliable than gh pr edit which can silently fail)
   REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
   PR_NUM=$(gh pr view --json number -q .number)
   gh api "repos/${REPO}/pulls/${PR_NUM}" -X PATCH -F body=@/tmp/pr-desc.md

**Key Points:**

• Use REST API (`gh api ... -X PATCH`) instead of `gh pr edit --body-file`
• `gh pr edit` uses GraphQL which can silently fail due to token scope issues
• Write content to a temp file first to preserve formatting
• Use heredoc (<<EOF) or Write tool to create the file
• Verify the description renders correctly in the PR after applying

**Example Generated Description:**

   ## Summary

   Adds URL scheme validation to version_fetcher.py to prevent path traversal attacks.

   ## Changes

   - Add `_validate_https_url()` helper function for URL scheme validation
   - Apply validation before all `urllib.request.urlopen()` calls
   - Add security annotations (`# nosec B310`) after validation

   ## Test Plan

   - [x] Bandit security scan passes
   - [x] Validation rejects file:// and http:// schemes
   - [x] HTTPS URLs are accepted
   - [x] All pre-commit hooks pass

   ---
   *PR description auto-generated by /fix-pr*

1.3 Fetch Review Context

**CRITICAL: