diff -r 387bb6102e84 -r 347e72dab266 skills/isurus-conventions/SKILL.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/skills/isurus-conventions/SKILL.md	Sun May 03 16:06:32 2026 -0500
@@ -0,0 +1,87 @@
+---
+name: isurus-conventions
+description: Use when working in the Isurus repository (or any repo identified as Isurus by the presence of `Isurus` in `README.md` or `cmd/isurus/`). Encodes Isurus-specific Mercurial conventions: non-publishing repo, bookmarks-as-PRs, commit message style, pre-PR Makefile checklist, opening PRs in the Isurus web UI.
+---
+
+# Isurus conventions (Mercurial overlay)
+
+## When this applies
+
+Use when working in the Isurus repository. Detect Isurus by:
+- Repo root contains `cmd/isurus/`, or
+- Top-level `README.md` contains the word `Isurus`, or
+- Repo is cloned from `ssh://hg@hg.leafscale.com/leafscale/isurus`.
+
+This skill is **purely additive**. The procedures live in `mercurial-basics`, `mercurial-bookmarks-and-prs`, `mercurial-sync-and-merge`, `mercurial-history-rewriting`, and `mercurial-finishing-a-branch`. This file supplies Isurus-specific values those procedures plug into.
+
+## Repository facts
+
+| Fact | Value |
+|---|---|
+| VCS | Mercurial 7.x (never git) |
+| Clone URL | `ssh://hg@hg.leafscale.com/leafscale/isurus` |
+| Long-lived branches | `default`, `stable` |
+| Phase model | **Non-publishing** — pushed changesets stay `draft` until merged |
+| Feature/PR mechanism | **Bookmarks** (push with `-B <name>`) |
+| Forge | Isurus (web UI at `https://hg.leafscale.com/`) |
+
+## Commit messages in this repo
+
+- Imperative summary, **under 72 characters**.
+- Prefix with a category: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`, `scripts:`, `hgignore:`. Match what `hg log` shows for recent commits if uncertain.
+- Body (optional) explains *why*; the diff shows *what*.
+- One blank line between summary and body.
+- **Never pass `-u`** to `hg commit` — identity is in `~/.hgrc`.
+
+## Pre-PR check sequence
+
+Run from the repo root, in this order:
+
+```sh
+make fmt        # gofmt — leaves no diff if all files are formatted
+make vet        # go vet — catches suspicious constructs
+make check      # full test suite against PostgreSQL test DB
+```
+
+`make check` requires the `isurus-test` database on localhost:
+- DB name: `isurus-test`
+- User: `isurus-test`
+- Password: `isurus-test`
+
+Override with `ISURUS_TEST_DSN`. See `make test-setup` for one-time DB creation.
+
+Optional but recommended (skip if not installed):
+
+```sh
+make lint       # golangci-lint
+```
+
+The PR checklist from `CONTRIBUTING.md` (must all be true before opening PR):
+
+- `make check` passes
+- `go vet ./...` is clean
+- Code is formatted (`make fmt`)
+- New public functions have short godoc comments where non-obvious
+- No new `TODO`/`FIXME` markers (fix or file an issue instead)
+- Documentation updated if behavior or configuration changed
+- Commit messages explain *why*
+
+## Pull request flow
+
+1. `hg push -B <bookmark>` to the canonical remote.
+2. Open a PR in the Isurus web UI (`https://hg.leafscale.com/<owner>/<repo>`).
+3. Title: same as the commit message summary.
+4. Description: *why* + link to related issues.
+5. Reviewer feedback → `hg amend` → `hg push -B <bookmark> -f`.
+
+The non-publishing repo makes `-f` after amend the **expected** workflow, not a sign of trouble.
+
+## What this overlay does NOT cover
+
+- General Mercurial commands → `mercurial-basics`.
+- Bookmark mechanics → `mercurial-bookmarks-and-prs`.
+- Pull / merge / conflicts → `mercurial-sync-and-merge`.
+- Amend / uncommit / phase rules → `mercurial-history-rewriting`.
+- The end-to-end "finish a branch" sequence → `mercurial-finishing-a-branch`.
+
+This file only changes the *values* those skills use (URLs, branch names, check commands). The procedures stay the same.