neru-create-pr

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

SKILL.md

GitHub

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 ., because 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:

    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, since 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, decided by the title's type 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, and 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 they do not apply. Put None. under Related Issues when there is nothing to link.
  • UI-visible changes (overlays, hints, grid) get a screenshot or short recording. Use just build, then ./bin/neru launch.

Writing the Description

Short: two or three short paragraphs at most.

  • Always open with This PR <verb> ..., such as fixes, adds, removes or 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, with one sentence for any deliberate limitation. Deeper detail, such as trade-offs, measurements and 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, such as config options (added, renamed, removed, new default or accepted values), commands, subcommands, flags or environment variables, spell the changes 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, and 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, such as a removed/renamed option or command, narrowed accepted values, a changed default or meaning, or a 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, since "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, so 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, because 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 there is no need to rewrite history with force-pushes.