publish-pr

name	publish-pr
description	Publish the current branch and open (or update) a GitHub pull request for the taskctl repo
disable-model-invocation	true

publish-pr

Publish the current branch and create — or update — a GitHub pull request, using this repo's conventions and PR-description templates.

Steps

1. Pre-publish gate (this repo requires it before every PR):
   • Run the prepare task and confirm it is clean: go run . --output json --no-input prepare, then check the tree is clean (prepare rewrites formatting/generated files — an unexpected diff means something drifted, fix it before continuing).
   • Run the docs-sync agent so README.md and docs/ reflect the change set.
2. Inspect git state:
   • git status --short --branch
   • git diff --stat
   • git log --oneline --decorate -10
   • git diff main...HEAD --stat
3. Commit any uncommitted relevant changes:
   • Stage only the relevant files; write a concise commit matching repo style (conventional prefixes: feat:, fix:, chore:, …).
   • Do not amend unless explicitly requested.
4. Push the current branch with upstream: git push -u origin HEAD. Never force-push unless explicitly requested.
5. Pick the template from signals (see below).
6. Compose title and body (see templates and writing rules) from the whole branch diff (main...HEAD) and chat history — summarize all changes, not just the latest commit.
7. Create or update the PR with the GitHub CLI:
   • Check whether a PR already exists for the branch (gh pr view --json url,title or gh pr list --head <branch>).
   • If it exists — update the description to reflect the current change set.
   • If not — gh pr create and pass the body via a HEREDOC.
   • If the CLI cannot be used, fall back to the GitHub MCP tool.
8. Return the PR URL.

Choosing the template

Detect the change type from signals, in order:

• Conventional-commit prefixes in git log (fix: → bug fix; feat: → feature).
• Diff shape: a small targeted change correcting behavior → bug fix; new capability / new files / new commands → feature.

Branch names carry no prefix in this repo (see Default assumptions), so don't rely on them. If the signals conflict or are absent, ask which template to use before writing the body.

Templates

Every section except Overview is optional — include it only when it carries real content. Never add a section just to fill the shape; an empty or padded section is worse than an absent one.

Feature

## Overview

- High-level outcome: what this adds and for whom.

## Goal

- Why this work exists; the user or product problem it addresses.

## Decisions

- Key implementation choices and trade-offs; scope boundaries.

## Architecture

- Only when the change introduces or reshapes structure worth explaining (new packages, data flow, extension points). Skip for self-contained features.

Bug fix

## Overview

- What was broken and the observable symptom.

## Root cause

- Why it happened — the actual defect, not just the symptom.

## Decisions

- Notable choices in the fix; alternatives considered; scope boundaries.

## Fix

- What changed to resolve it. Skip when the Overview + Root cause already make the fix self-evident.

Writing rules

• Keep the title concise and outcome-focused; use the matching conventional prefix (feat: …, fix: …).
• Prefer intent over implementation detail. Do not turn the body into a changelog or restate code changes already visible in the diff.
• Call out product or architecture decisions when they matter.

Default assumptions

• Base branch is main.
• Do not use branch prefixes (feat/, fix/, chore/, …) — use plain branch names (e.g. pipeline-task-variables, not fix/pipeline-task-variables). No GitHub issues keys.
• Use the GitHub CLI for PR creation; return the PR URL.