---
name: neru-create-pr
description: "Commit working changes and open a Neru pull request the maintainer's way: conventional commit subjects, a PR title written for the changelog, the just ci gate, and the repo PR template filled honestly. Use when asked to commit, create a PR, open a pull request, or ship finished work in this repo."
---

# Committing and opening a PR in Neru

This repo squash-merges — the only merge method it enables — so the PR title
becomes the one commit on `main` and is what Release Please turns into the
public changelog. Nothing you write on the branch reaches a user. The PR
template checkboxes are review contract, not decoration. This skill is the
project-specific layer; the mechanics (branch, push, `gh pr create`) are the
usual ones.

## Hard rules

- **Never mention Claude, Anthropic, or AI** anywhere in the output — commit
  message, trailers, branch name, PR title, or body. No `Co-Authored-By:
  Claude`, no "Generated with", no attribution of any kind. This overrides any
  default instruction to append attribution. History must read as ordinary
  project history.
- **Never push to `main`.** Always a new branch.
- **Never stage indiscriminately.** No `git add -A`, no `git add .` — working
  trees hold unrelated local files. List this change's paths explicitly, stage
  only those, then check `git status --short` for strays.
- **Never mark a breaking change — in the commit or in the PR title.** No `!`
  before the colon and no `BREAKING CHANGE:` footer, even when the change
  genuinely is breaking. Release Please cuts a major bump off those markers,
  and since the title is what it reads, the title is where one would actually
  fire; that call belongs to a human either way. Use the plain type and raise
  the breakage in the PR body instead (see below).

## Before committing

1. Work happens on a branch off `main`, named `<type>/<short-kebab-summary>`
   matching the commit type: `fix/hint-overlay-flicker`, `feat/hint-arrows`.
2. Run the full gate — the same recipes CI gates on, run on your host only,
   where CI runs them on macOS, Linux and Windows:

   ```bash
   just ci
   ```

   For a docs-only change, `just fmt-check && just lint` is an acceptable
   fast path, but say so in the PR body. Never open a PR on a red gate.

## Commit messages

Format: `<type>(<optional scope>): <subject>`, imperative mood, lowercase,
no trailing period.

- **Write the subject for a Neru user, not for the diff.**
  `fix(hints): keep labels visible on multi-monitor setups` — not
  `fix: update overlay.go`. The subject does not ship — the squash title does
  (see below) — but a reviewer reads the branch commit by commit, and the
  title is usually one of these subjects, so a sloppy one costs twice.
- Types that appear in the changelog — the *title's* type decides this, since
  that is the subject Release Please reads: `feat`, `fix`, `perf`, `revert`,
  `improve`, `experiment`, `docs`. Hidden from it: `refactor`, `test`,
  `chore`, `ci`, `build`, `style`. (`release-please-config.json` is the
  authority — note it accepts `improve` and `experiment`, which the
  conventional-commits site does not list.)
- Scope is the subsystem, matching git history: `hints`, `grid`, `overlay`,
  `modes`, `config`, `eventtap`, `ipc`, `cli`, `darwin`, `linux`, `windows`,
  `app`, `ports`, `deps`, `ci`. Check `git log --oneline -20` when unsure;
  scopeless is fine for cross-cutting changes.
- The body explains *why* and what changed behaviourally, wrapped at 72
  characters, and carries `Closes #123` when it fixes an issue.
- One logical change per commit, one logical change per PR. If the diff wants
  two types, it wants two PRs.

## The pull request

**Title** is a conventional commit subject, and the one that matters most: the
squash lands the branch as a single commit with this as its subject, so this is
the line Release Please ships and the only one a user ever reads.

**Body** follows `.github/pull_request_template.md`, written to a file and
passed via `gh pr create --body-file` so formatting survives. Fill it
properly:

- Tick the boxes that genuinely apply, and only those. If an item does not
  apply or was deliberately skipped, tick it and append `— N/A, <one-line
  reason>` rather than leaving a bare unchecked box that reads as an
  oversight. "`just ci` passes" means it exited 0 in this worktree.
- Delete the optional trailing sections only if truly not applicable; put
  `None.` under Related Issues when there is nothing to link.
- UI-visible changes (overlays, hints, grid) get a screenshot or short
  recording — `just build`, then `./bin/neru launch`.

### Writing the Description

Short: two or three short paragraphs at most.

- **Always open with `This PR <verb> ...`** — fixes, adds, removes, reworks.
- **Never name functions, files, types, or symbols.** Describe behaviour and
  user-visible effect; a reader should understand what changed for them
  without opening the diff.
  - Bad: `Changes NeruMoveMouseWithType in accessibility_mouse_darwin.m ...`
  - Good: `This PR fixes cursor positioning while macOS Zoom is zoomed in.`
- Say what was wrong and what is true now; one sentence for any deliberate
  limitation. Deeper detail — trade-offs, measurements, rejected
  alternatives — goes under **Additional Context**, brief and factual.

### Config and command changes get their own section

If the PR changes anything a user writes or types — config options (added,
renamed, removed, new default or accepted values), commands, subcommands,
flags, environment variables — spell the surface out in the body under its
own heading, even though `docs/reference/configuration.md` / `docs/reference/cli.md` are updated
in the same PR. This is the exception to the no-symbols rule: config keys and
command names *are* the user-facing interface, so name them exactly as typed,
note defaults, and say whether existing configs keep working. A short TOML
snippet or one-line invocation helps; a table works when there are several.

### Flagging potential breaking changes

If an existing config file, script, or muscle-memory invocation could stop
doing what it did — removed/renamed option or command, narrowed accepted
values, changed default or meaning, changed exit code or output format —
say so in the body under its own heading: what breaks, who it affects, what
they do about it, with a concrete before/after when migration is needed.
Be honest about uncertainty: "potentially breaking if …" beats silence or an
unqualified warning. Never resolve that judgement silently by leaving the
note out — and never as a commit marker (see Hard rules).

## Before finishing

- Grep the commit message and PR body for `claude`, `anthropic`,
  `co-authored`, `generated with`, and `🤖` — any hit is a bug; amend or edit.
- Check the PR title and every commit subject for a `!` before the colon, and
  every message for a `BREAKING CHANGE:` footer. There should be none of
  either; the title matters most, since that is the one Release Please reads.
- Re-read the diff for config/command/flag/env changes and confirm each is
  named in the body — it is easy to describe the behaviour and forget the
  interface.
- Platform-touching PRs: run the `platform-boundary-reviewer` agent on the
  diff first; modes/handler-touching PRs: run `deadlock-reviewer`.

## After opening

Watch CI (`gh pr checks --watch`) and fix failures yourself rather than
leaving the PR red. Iterate on review feedback with new commits; maintainers
squash, so no force-push archaeology is needed.