diff -r d350e9491c79 -r 3b51feb34062 skills/mercurial-basics/SKILL.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/skills/mercurial-basics/SKILL.md	Sun May 03 15:28:01 2026 -0500
@@ -0,0 +1,139 @@
+---
+name: mercurial-basics
+description: Use when working in any Mercurial repository for inspection or local commits — `hg status`, `diff`, `log`, `add`, `commit`, `parents`, `heads`, `branches`, `bookmarks`, `phase`. Triggers on any `hg ...` command or when `.hg/` is in the working directory.
+---
+
+# Mercurial basics
+
+## When this applies
+
+Use when:
+- The working directory contains `.hg/` (or any ancestor does).
+- About to run any `hg` command.
+- About to perform an operation that has both git and hg equivalents and the repo is hg.
+
+Do not use for:
+- Pulling, merging, conflict resolution → see `mercurial-sync-and-merge`.
+- Bookmarks and the PR workflow → see `mercurial-bookmarks-and-prs`.
+- Amending or rewriting history → see `mercurial-history-rewriting`.
+
+## Identity comes from ~/.hgrc
+
+**Never pass `-u` to `hg commit`.** Identity is configured globally in `~/.hgrc`:
+
+```ini
+[ui]
+username = Name <email@example.com>
+```
+
+`hg commit -u "..."` is for impersonation and will create commits with the wrong author. Always:
+
+```sh
+hg commit -m "your message"
+```
+
+## Inspection commands
+
+| Need | Command |
+|---|---|
+| What changed in working dir | `hg status` |
+| Diff of unstaged changes | `hg diff` |
+| Recent commits | `hg log` (or `hg log -l 10` for limit) |
+| Working dir parent revision | `hg parents` |
+| All current heads | `hg heads` |
+| Named branches | `hg branches` |
+| Bookmarks (≈ feature branches) | `hg bookmarks` |
+| Phase of a revision | `hg phase -r <rev>` |
+| Who wrote each line | `hg annotate <file>` (git users: `blame`) |
+
+## Reading `hg log` output
+
+Default format shows changeset hash, branch (if not `default`), tag, user, date, and summary:
+
+```
+changeset:   42:a1b2c3d4e5f6
+branch:      myfeature
+tag:         tip
+bookmark:    work-in-progress
+user:        Alice <alice@example.com>
+date:        Mon May 02 09:00:00 2026 -0500
+summary:     feat: add the thing
+```
+
+For terser output: `hg log --template '{node|short} {bookmarks} {branch} {desc|firstline}\n'`
+
+## Commit messages
+
+The Isurus convention (and a generally good rule) is:
+
+- **First line:** imperative summary, **under 72 characters**. Examples: `feat: add language stats to repo sidebar`, `fix: handle nil reviewer in PR template`, `chore: bump dependency X to v2`.
+- **Body (optional):** explain *why* the change is being made. The diff already shows *what*. One blank line between summary and body.
+- **Category prefix** (`feat:`, `fix:`, `docs:`, `chore:`, `test:`, `refactor:`) is convention in this codebase — match what `hg log` shows.
+
+Keep each commit focused. If a single change touches unrelated areas, split into separate commits.
+
+## Adding files
+
+```sh
+hg add path/to/file       # explicit
+hg add                    # add all untracked files (use carefully)
+```
+
+Mercurial does not have a staging area. Files are tracked or not; commits include all changes to tracked files. To commit only some changes, use `hg commit path/to/file1 path/to/file2`.
+
+## .hgignore syntax
+
+`.hgignore` lives at the repo root. Default syntax is `glob`:
+
+```
+syntax: glob
+
+# Build artifacts
+dist/
+*.o
+
+# Switch syntax for a section
+syntax: rootglob
+binary-at-root-only
+
+# Switch back
+syntax: glob
+**/*.swp
+```
+
+`syntax: rootglob` matches only at the repo root (useful for binary names that must not match files in subdirectories).
+
+## Phase awareness
+
+Every changeset has a phase: `draft`, `public`, or `secret`. The phase governs what's safe to rewrite:
+
+- **draft** — local or pushed-but-not-merged. Safe to amend, uncommit, rewrite.
+- **public** — published and considered immutable.
+- **secret** — never pushed.
+
+In a non-publishing repo (like Isurus), pushed changesets stay draft until merged into the canonical branch. This is what makes `hg amend` safe during code review. See `mercurial-history-rewriting` for the rewriting rules.
+
+To check: `hg phase -r <rev>`. To see your tip: `hg phase -r tip`.
+
+## Common workflow examples
+
+Inspect what's changed and commit:
+
+```sh
+hg status
+hg diff
+hg add new-file.go
+hg commit -m "feat: add new thing"
+```
+
+See recent history on a bookmark:
+
+```sh
+hg log -l 5 -B my-feature
+```
+
+Diff between two revisions:
+
+```sh
+hg diff -r REV1 -r REV2
+```