/skill

Name

pr

Description

Write the pull request for the current branch: the merge mode (squash or rebase), a title that is the changelog line when squashed, and a description per the Pull requests rules, all checked with tools/commit-lint. Also writes GitHub issues from two templates: a feature as a story with a definition of done, a bug with steps to reproduce and expected and actual behaviour. Use when asked to write, draft or open a PR or an issue, to produce a PR title or squash message, or to choose how to merge a PR.

# Pull request

A PR is squash merged or rebase merged, never with a merge commit. Squashed,
the title becomes the commit subject on main and the release-notes line.
Rebased, every commit lands as it is and each subject is a release-notes line.
`docs/agent/dev.md` ("Commits: the subject is the changelog", "Pull requests")
holds the rules; this file is the procedure. dev.md wins.

## 1. Read the branch

```bash
git fetch origin
git log --reverse --format='%h %s%n%b' origin/main..HEAD
git diff --stat origin/main...HEAD
```

Read the diff wherever a subject does not state the user-visible change. Report a
non-empty `HEAD..origin/main` as "branch is behind". Do not rebase unasked.

## 2. Squash or rebase

Count the entries a release-notes reader sees: commits of a shown type (`feat`,
`fix`, `security`, `perf`, `docs`) plus any commit carrying `!`, `Upgrade:` or
`BREAKING CHANGE:`. Tests, refactors and chores serving one of those add no entry.

- One visible entry: squash. The title is that entry.
- Several, and every commit stands alone and passes commit-lint: rebase. Say
  so in the handover, and write the title as the lead change; it is not a
  changelog line.
- Several, but mixed with fixups or work in progress: report it. The branch
  needs cleaning into coherent commits, or splitting. Do not rebase unasked.

Never write a title containing "and".

## 3. Title

- Format: `type(scope)!: subject`. Types and scopes come from the dev.md tables.
- The scope names what a reader recognises, a stacklet or a bot, never a file.
- Imperative, lowercase after the colon, no full stop, no identifiers.
- Name the concrete change, not its effect: `add an install hint to restart
  core on the first start`, not `say how to finish the agent's first start`.
- Limit 72 characters as commit-lint counts them; dev.md asks for under 70. The
  ` (#N)` appended at merge does not count.
- Use `!` only when the user must act. The description then carries `Upgrade:`
  or `BREAKING CHANGE:`.
- Single-commit branch whose subject passes: reuse that subject.

## 4. Description

```
## Summary
- <user-visible change, and why>

Upgrade: <required action, as markdown>
Refs: #127
```

- One to three bullets. Footers only when they apply.
- Start with the situation the PR answers, then what it changes: "The agent
  is beta. After its first `./stack up agent`, it can sign in only after a
  core restart." then "The hints shown after `./stack up agent` tell the
  admin to run `./stack restart core`, then `./stack restart agent`."
- Plain technical English: state what the change does. No paraphrase such
  as "now say so" or "provide the required information".
- No "Test plan" section. Test output and measurements go in a PR comment.
- No em dashes. Use a comma, colon, period or parentheses.
- No `Co-Authored-By`, no "Generated with" line, no tool link: this repository is
  public and commit-lint rejects all three.

## 4b. Read the diff as a reviewer

Check the new and touched code against `docs/agent/dev.md`, "Clean code:
what a reviewer checks". Fix what breaks a rule before opening the PR, or
say in the handover which rule it breaks and why.

## 5. Check

```bash
python3 tools/commit-lint --title "<title>"
python3 tools/commit-lint --body "<description>"
python3 tools/commit-lint --range origin/main..HEAD
```

CI runs the third over every commit in the PR. Fix and re-run until all three
pass. Rewording a pushed commit needs a force push: request approval first.

Output: the title, the description in a code block, the three results.

## 6. Open

Pushing and opening a PR need explicit approval, for every push. With approval:

```bash
git push -u origin HEAD
gh pr create --base main --title "<title>" --body-file <file>
```

Add `--draft` when asked. Never merge.

## Merge

State the merge mode when handing the PR over.

Squash: the repository builds the squash body from the branch's commit
messages, not from the PR description. A footer written in the description
reaches main only when the merge uses the description as the body: the merge
dialog, or `gh pr merge --squash --body-file`.

Rebase: `gh pr merge --rebase`. The commits land unchanged, so their footers
are the ones that count; one written only in the description is lost.

## Issues

Work that is not done in this branch goes into a GitHub issue: something
found mid-task, a follow-up, a bug to fix later. One issue per piece of
work. Every issue ends with a definition of done, the checks that prove it
is finished. Pick the template by kind.

**Title.** A feature says what becomes possible, in the imperative:
"Give CLI plugins a secret lookup instead of a snapshot of every secret".
A bug says the symptom as a reader meets it: "Paperless login returns 500
on a first-time signup". No class or function names unless a reader
types them.

### Feature: a story with a definition of done

```
## Story
As <an admin | a family member | a stacklet author>, I want <capability>,
so that <outcome>.

## Context
What exists today and why it is not enough. Point at the code
(`lib/stack/stack.py`, `stacklets/<id>/...`), ADRs and PRs.

## Proposal
The change, at the level a reviewer can argue with.
Out of scope: <what this issue does not cover>.

## Definition of done
- [ ] <an observable check: a command and its result, or a behaviour>
- [ ] <a caller-side test that states the behaviour>
- [ ] <docs updated: `docs/stack-reference.md` for framework behaviour>
```

Example: an admin wants the provider's "My apps" page to show an icon per
service. Done when `stack up id` sets a logo on every registered client
that has none, `stack up id` a second time uploads nothing, and a test
drives both runs against a stand-in for the provider's API.

### Bug: steps to reproduce, expected and actual behaviour

```
## Summary
What breaks, for whom, in one sentence.

## Steps to reproduce
1. <from a known state: which stacklets are up, which mode>
2. <the action>
3. <what to look at>

## Expected behaviour
What should happen, and where that is promised (a doc, a test, a spec).

## Actual behaviour
What happens. Error text verbatim and trimmed.

## Environment
`./stack version`, macOS version, OrbStack or Docker Desktop, port or
domain mode, the stacklets involved.

## Cause
If known: the file and why. Otherwise leave the heading out.

## Definition of done
- [ ] <a test that fails before the fix and passes after it>
- [ ] <the steps above now give the expected behaviour>
```

Example: steps "bring up `id` and `docs` in domain mode, open the docs
login, choose the provider button as a user whose account is not linked
yet". Expected: Paperless creates the account and logs in. Actual:
`500`, with `MultipleObjectsReturned` in the Paperless log. Done when a
test pins one provider entry per client id.

### Rules

- Examples and reproduction steps use the demo family and example
  domains (`home.example.family`), never a real instance, name, address
  or log excerpt with personal data. This repository is public.
- No em dashes. No secrets, tokens or passwords, also not in logs.
- Opening an issue publishes it: ask first. With approval:
  `gh issue create --title "<title>" --body-file <file>`.
- A commit or PR that resolves the issue carries `Closes: #N`; one that
  only relates to it carries `Refs: #N`.