---
name: tmppr-issue-workflow
description: Use when working on a tmppr issue end-to-end — pickup, worktree, PR, commit cadence, blockers, debug, review, ship. Uses git for code/branch ops and tmppr CLI for issue/PR/CI ops. No wrappers.
---

# tmppr issue workflow

## Division of labor

- **git** for: worktree, branch, commit, push, log, diff, fetch.
- **tmppr** for: issue ops (`tmppr issue …`), PR ops (`tmppr pr …`), CI inspection (`tmppr ci …`), reviews (`tmppr review`, `tmppr thread`).

If you find yourself wanting a tmppr verb that doesn't exist, the answer is almost always a plain git command.

## Phase 1 — Pickup

```
tmppr issue show <id>
```

- Refuse to start if `dependsOn` contains any open issue.
- If `linkedPullRequests` already includes an open PR by a different actor, **STOP** — that's the soft lock. Pick a different ticket or jump to Phase 9.

## Phase 2 — Setup the work surface (git only)

Pick a branch name like `<handle>/issue-<id>`. From the main checkout:

```
git worktree add ../<repo>-worktrees/issue-<id>-<handle> -b <handle>/issue-<id>
cd ../<repo>-worktrees/issue-<id>-<handle>
git commit --allow-empty -m "wip: starting issue #<id>"
```

## Phase 3 — Open the PR + claim the issue (tmppr only)

```
tmppr pr open --push --draft --base main --head <handle>/issue-<id> \
    --title "<short summary>" --body "Refs #<id>"
tmppr issue edit <id> --assignees <handle>
```

- Open it as a **draft** (`--draft`) — CI won't run until you mark it ready in Phase 8, so you can push freely.
- `--push` pushes the branch as part of `pr open` — one round-trip.
- `Refs #<id>` in the body auto-links via existing tmppr issue↔PR machinery.
- The assignee + open linked PR are the visible "I'm on it" markers.

## Phase 4 — Implementation loop (git only)

Commit after each meaningful unit. Push every commit — the PR's commit log IS the live activity feed on the issue page.

Comment cadence: alongside the commit cadence, post a short milestone comment at each meaningful step (what you found / what you're doing next / any blocker) with `tmppr comment conversation <pr-id> "…"` (or `tmppr issue comment <id> "…"` before the PR exists).

```
git add -A
git commit -m "<prefix>: <message>"
git push
```

Message prefixes:

- `test: …` — failing test added
- `feat: …` — implementation slice
- `fix: …` — bug fix
- `refactor: …` — behavior-preserving rewrite
- `wip: …` — checkpoint

## Phase 5 — Blockers (tmppr for the escalation surface, git for the work)

```
tmppr issue comment <id> -b "blocked: <why>"
tmppr issue edit <id> --labels blocked,<existing-labels>
```

If the blocker is a discrete unit of work, file it and wire the dependency:

```
NEW=$(tmppr issue create --title "…" --body "…" --format json --filter-output 'issue.id')
tmppr issue depend <id> --on $NEW
```

## Phase 6 — Debug a failing CI run

```
tmppr ci runs --pr <pr-id>     # which runs/checks failed
tmppr ci log <check-id>        # full log for a failing check
```

Reproduce in the worktree using git + your usual local toolchain. Push the fix. Each fix commit is auditable on the PR.

## Phase 7 — Code review (when you're the reviewer)

```
tmppr pr show <pr-id>
tmppr pr diff <pr-id>
tmppr ci runs --pr <pr-id>     # only if checks failed
tmppr thread reply <thread-id> --body "…"
tmppr review submit <pr-id> APPROVE --body "…"   # or REQUEST_CHANGES | COMMENT
```

## Phase 8 — Ship

First flip the draft to open so CI + review run:

```
tmppr pr mark-ready <pr-id>    # enable CI + review (drafts don't run CI)
```

Include `Closes #<id>` in a commit message somewhere on the branch so the issue auto-closes on merge. Then:

```
tmppr pr ship <pr-id>          # approves + merges + ff main in one
```

Or, if reviewer separation is needed:

```
tmppr pr merge <pr-id>
```

Close with a final comment ending in a `Next: <suggested next step>` line (e.g. `Next: monitor the post-merge CI run`).

## Phase 9 — Resume abandoned work

If you find an open PR + branch with no commits for >30 min and the prior actor isn't around:

```
git fetch tmppr
git checkout <branch>
# continue from Phase 4
```

Or close it cleanly and restart:

```
tmppr pr close <pr-id>
# then back to Phase 2
```

## Hard rules

- Always work in the worktree, never the main checkout.
- Push every commit (long pauses look like abandonment).
- Phase-1 soft-lock check: don't dupe a branch that's already open under another actor.
- If you need a tmppr command that doesn't exist, you're almost certainly reaching for a git command. Use that instead.
