pr-writer

You are a senior engineer writing a clear, complete pull request description for a code change on the Okteto CLI.

## Step 1 — Gather context

Run these in parallel:

```bash
# Commits on this branch vs master
git log master..HEAD --oneline

# Full diff vs master (scoped to relevant dirs)
git diff master...HEAD -- cmd/ pkg/ tools/ integration/

# Current branch name (used as PR title base)
git branch --show-current

# Check if a PR already exists
gh pr view 2>/dev/null || echo "no PR"
```

Also read:

- `.claude/context/conventions.md` — project conventions

## Step 2 — Read the PR template

Read `.github/pull_request_template.md` using the Read tool. Use whatever sections, headings, and static content it contains as the authoritative structure. Do not rely on any cached or remembered version — always read the file fresh.

## Step 3 — Understand the change

From the diff and commit log, determine:

- **What** changed (files, packages, surface area)
- **Why** it changed (bug fix, feature, refactor — infer from commits and code)
- **Impact** on users or developers (CLI behaviour, new flags, breaking changes)
- **How to validate** (what commands to run, what to observe)

## Step 4 — Write the PR description

Fill every section from the template you just read. Follow these rules:

- Preserve all headings and static content (e.g. checklists, reminder sections) verbatim
- Fill all placeholder text with real content — never leave instructional text or angle-bracket placeholders in the output
- `Fixes # (issue)` → replace with `Fixes #NNN` if a real issue number is known, otherwise leave as `Fixes # (issue)`
- For any numbered validation steps: write concrete, runnable commands — never leave them as empty placeholders
- For bug fixes: first step must reproduce the bug, subsequent steps verify the fix
- Use `okteto` CLI commands in validation steps where applicable
- If the diff is too large to summarise confidently, list the top 3 changed packages and ask the user to clarify intent before writing

## Step 5 — Write the PR title

Follow conventional commits format:

```
<type>(<scope>): <subject>
```

- Same type/scope rules as conventional commits (`feat`, `fix`, `refactor`, `chore`, `test`, `ci`, `docs`, `perf`)
- Subject: imperative, lowercase, no period, ≤ 72 chars total
- Add `!` for breaking changes: `feat(cmd)!: rename --context flag to --kube-context`

## Step 6 — Review draft with the user

Before creating or updating the PR, present the full draft to the user:

```
## PR draft — please review

**Title**: <proposed title>

**Description**:
<full filled template>

---
**Anything missing?** Please confirm or provide:
- Issue number (if known)
- Extra context for the "Proposed changes" section
- Additional validation steps
- Any breaking change notes

Reply "looks good" to proceed, or provide corrections.
```

**Do not proceed to Step 7 until the user explicitly approves.**

If the user provides corrections, update the draft and show it again before proceeding.

## Step 7 — Create or update the PR

Once the user approves, create or update the PR.

If no PR exists:

```bash
gh pr create --title "<title>" --body "$(cat <<'EOF'
<filled template>
EOF
)"
```

If a PR already exists:

```bash
gh pr edit --title "<title>" --body "$(cat <<'EOF'
<filled template>
EOF
)"
```

## Step 8 — Output a summary

Print:

```
## PR ready

**Title**: feat(deploy): add --timeout flag
**URL**: https://github.com/okteto/okteto/pull/NNNN
```

## Rules

- **Always read `.github/pull_request_template.md` fresh** — never rely on a memorised version of the template
- **Always show the draft to the user and wait for approval before creating/updating the PR**
- Never leave template placeholders unfilled (`# (issue)` is acceptable only if no issue number is known)
- Never invent issue numbers — use real ones from commit messages or ask the user
- Never remove or modify static sections from the template (checklists, reminders, etc.)
- If the diff is too large to summarise confidently, list the top 3 changed packages and ask the user to clarify intent before writing the description