# ship-it iterate — one issue, end-to-end

You are running ONE iteration of the ship-it AFK loop. Implement, verify, and ship exactly one issue, then exit. The outer shell loop will pick the next one.

**Mode: AFK.** Do not ask questions. If the issue is genuinely undecidable from its body + linked PRD + grilling notes already in the issue or repo, drop a comment on the issue with the specific question, label it `needs-decision`, and exit with status=needs-decision. Do not guess at user intent.

Variables provided below this prompt: `ISSUE_NUMBER`, `TRACKER_CLI` (`gh` or `tea`), `TRUNK_BRANCH`, `REPO_ROOT`.

## Steps

1. **Read the issue.**
   - GitHub: `gh issue view $ISSUE_NUMBER --json number,title,body,labels`
   - Gitea: `tea issues $ISSUE_NUMBER --output json`
   - Parse: `Slice — layers touched`, `Scope`, `Acceptance criteria`, `Slice check`, `Notes`, linked PRD path.
   - If `Acceptance criteria` is missing or non-testable → exit status=needs-decision with reason "acceptance criteria not testable".

2. **Branch from latest trunk.**
   `git fetch origin && git switch -c "slice/${ISSUE_NUMBER}-<short-kebab-slug>" "origin/$TRUNK_BRANCH"`

3. **Write the failing e2e test first.** Anchored at the OUTERMOST layer named in `Slice — layers touched` (HTTP endpoint, UI smoke, dashboard query, log assertion — whatever the acceptance criterion observes). Run it. Confirm it fails for the right reason. If you can't write an e2e test for this slice, that's a sign the acceptance criterion isn't really observable end-to-end → exit status=needs-decision.

4. **Implement layer by layer.** Walk the `Slice — layers touched` list. Make the minimal change at each layer to satisfy the slice — do not gold-plate, do not refactor adjacent code, do not "improve" things outside scope. Re-run the e2e test after each layer change.

5. **Run the broader test suite.** Catch regressions caused by the slice. Fix any test that was green before and is now red — do not skip or mark tests. If a test was already red before your changes, leave it (note in PR body).

6. **Outermost-layer smoke check.** The 30-second-demo check: hit the endpoint with curl, query the dashboard, tail the log, load the page. Observe what the acceptance criterion observes. Capture the output (curl response body, log snippet, query result) — you'll paste it into the PR body as evidence.

7. **Commit.** One commit per slice (or a tight series — no WIP commits, no fixup commits, no "address review" before review exists). Read the repo's recent `git log` to match commit style. Message ends with `Closes #${ISSUE_NUMBER}`.

8. **Push and open PR.**
   - GitHub: `git push -u origin HEAD && gh pr create --fill`
   - Gitea: `git push -u origin HEAD && tea pr create --title "..." --description "..."`
   - PR body must include:
     - Each acceptance criterion as a checked `- [x]` line.
     - The smoke-check evidence (curl output / log snippet / screenshot path) in a fenced block.
     - `Closes #${ISSUE_NUMBER}` (so the issue auto-closes on merge).

9. **Wait for CI and decide merge.**
   - Poll: `gh pr checks --watch` (or `tea pr status`).
   - **All green + branch protection allows direct merge** → `gh pr merge --squash --delete-branch`. Verify the merge commit landed on trunk.
   - **All green + branch protection requires human review** → leave PR open. Comment `Ready for review — all acceptance criteria verified, smoke check passed.` on the issue. Exit status=shipped with the PR number.
   - **Red CI** → one fix-and-push cycle. Read the failing log, fix the actual cause (do not skip the test). If still red after the second attempt: label issue `ci-failed`, comment with the CI excerpt, leave PR open, exit status=failed with reason "ci-red".

10. **Return to trunk.** `git switch $TRUNK_BRANCH && git pull --ff-only`. If the slice was merged, run the smoke check one more time against integrated trunk. If it fails there → revert the merge, label `regression`, exit status=failed with reason "regression-on-trunk".

## Boundaries

- Never force-push, never rewrite shared history, never delete branches you didn't create.
- Never bypass branch protection (`--admin`) or skip CI hooks (`--no-verify`).
- Never auto-merge a PR whose CI is red or pending.
- Never close an issue without the outermost-layer smoke check passing.
- Never modify CI/CD config, IaC, or production data unless the slice's `layers touched` explicitly names that layer.
- Never invent acceptance criteria. If they're vague, label `needs-decision`.
- Never assign issues or change milestones.

## Final output line

The shell loop greps for this exact line to determine outcome. Print it as the LAST line before exiting, on its own line, no decoration:

```
ITERATION_RESULT: status=<shipped|failed|needs-decision> issue=#<N> pr=<#N|none> reason=<short single-line reason>
```

Examples:
```
ITERATION_RESULT: status=shipped issue=#142 pr=#287 reason=merged-to-main
ITERATION_RESULT: status=shipped issue=#143 pr=#288 reason=open-for-review
ITERATION_RESULT: status=failed issue=#144 pr=#289 reason=ci-red-after-retry
ITERATION_RESULT: status=needs-decision issue=#145 pr=none reason=acceptance-criteria-not-testable
```