---
name: submitting-pull-requests
description: Use when preparing, opening, or updating pull requests in this repo, including using tea, writing Conventional Commits PR titles, writing PR bodies, reporting validation, and rebasing branches that have conflicts.
---

# Submitting Pull Requests

## Core Rule

Open and update PRs with `tea`. The PR title and body must describe the net change across the whole branch, not only the last commit.

## Before Opening

1. Confirm the branch state:
   - `git status --short`
   - `git branch --show-current`
   - `git diff --stat`
2. Run the smallest relevant behavior verification for the touched areas.
   - Run targeted guardrails for the touched surfaces.
   - Before opening or updating a PR, run `make harness-fast` when feasible. Treat it as a fast aggregate smoke check, not a substitute for targeted tests or guardrails.
   - If `make harness-fast` fails, record the exact failing check, decide whether this branch caused it, and fix current-branch regressions before opening the PR. Report unrelated pre-existing failures in the PR body instead of raising baselines as a shortcut.
3. Check for formatting or conflict-marker issues:
   - `git diff --check`
   - `rg -n '^(<<<<<<<|=======|>>>>>>>)'`
4. Push the branch before using `tea`:
   - `git push -u origin <branch>`

## PR Title

Use Conventional Commits style:

```text
<type>(<scope>): <imperative summary>
```

Examples:

- `fix(auth): handle expired tokens`
- `feat(api): add workspace export`
- `docs(agents): document PR workflow`

Guidelines:

- Choose a common type such as `fix`, `feat`, `docs`, `test`, `refactor`, `perf`, `build`, or `chore`.
- Use a short scope that names the package, feature, or workflow.
- Write the summary as the user-visible or reviewer-visible outcome.
- Do not add a trailing period.
- Do not mention temporary branch names, task IDs, or implementation-only trivia unless they are part of the durable change.

## PR Body

Keep the body concise and reviewer-oriented:

```markdown
## Problem Summary
- ...

## What is changed and how it works?
- ...

## User Behavior Changes
- ...

## Tests
- `command` passed
- `command` passed
```

Include:

- The problem or motivation that makes the change necessary.
- The net change across all commits in the PR and enough implementation detail for review.
- User-facing behavior changes in their own section. If there are none, say so explicitly.
- Any API, storage, migration, or documentation impact.
- Exact verification commands and results.
- Tests not run, with the concrete blocker, when relevant.
- Conflict-resolution notes only when they matter for review, for example a non-trivial rebase.

Do not include:

- Chat history or private planning context.
- `Co-Authored-By` trailers.
- A commit-by-commit changelog unless the reviewer specifically needs it.

## Open With Tea

Use `tea pr create` or its equivalent `tea pulls create` from the branch worktree:

```bash
tea pr create --base <base-branch> --head <branch> --title "<title>" --description "<body>"
```

If multiline shell quoting would be error-prone, use `tea pr create` interactively and paste the same title/body content. After creation, report the PR URL.

## If The PR Has Conflicts

Resolve PR conflicts by rebasing the branch onto the target base branch:

```bash
git fetch origin
git rebase origin/<base-branch>
```

Then:

1. Resolve conflicts in the affected files.
2. Re-run `rg -n '^(<<<<<<<|=======|>>>>>>>)'` and the relevant verification.
3. Continue the rebase with `git rebase --continue`.
4. Push the updated branch with `git push --force-with-lease`.

Do not use a merge commit to resolve PR conflicts unless the user or repository explicitly asks for that workflow.