@shllg/emend 0.0.0-stage → 0.1.0

package/dist/skills/emend-review/SKILL.md

@@ -0,0 +1,404 @@
+---
+name: emend-review
+description: Create and publish an emend review when asked to review plans, docs or code, or to group a large change for a reviewer. Use emend-feedback for comments on an existing review; this skill prepares the writeup, topics and first revision.
+---
+
+# Prepare an emend review
+
+This skill needs the `emend` command on `PATH`.
+If `emend` is not found, stop and tell the user to install emend. Do not try to install it.
+
+## Establish the review
+
+Identify the target branch and the work the reviewer should see. For code, set `base` to the
+full commit hash of the merge-base with that target branch. Set `head` to a full commit hash,
+or `worktree` when uncommitted changes belong in the review. Resolve the merge-base before
+publishing; a branch name is not a manifest commit. Resolve it with:
+
+```sh
+git merge-base <target> HEAD
+```
+
+If publish prints `git lookup failed`, resolve `base` again with `git merge-base` and check that the commit exists in this clone.
+
+Report the commit count the review covers, its scope and any missing context.
+For a review containing only docs, omit both `base` and `head` and use `--key` for its first publish.
+The first publication of a code review on a detached HEAD also needs `--key`.
+`--key` is only for a first publish; later revisions use `--review <review-id>`.
+
+Set file roles deliberately. A PRD changed by this work belongs in `diff`; a PRD supplied for
+reading belongs in `doc`. The same path can appear once in each role when both views matter.
+File extensions do not decide roles. Name each meaningful changed file and its topic; unassigned
+changes fall into Other changes. Never declare the reserved topic slug `other` yourself.
+
+Group the change by what the reader must decide. Give each topic a stable `slug`, short `title`,
+one-sentence `summary`, and `importance` from 0 to 99. The reserved Other changes topic uses 100.
+Lower importance sorts first. Lead with
+security boundaries, irreversible effects, removals and uncertain behavior. Mechanical changes
+belong later, regardless of file size or alphabetic order.
+
+Set `attention` on every topic. It never changes order.
+
+- `critical`: a security boundary, an irreversible effect, data loss, or a decision only the reviewer can make.
+- `review`: behaviour worth reading line by line.
+- `skim`: mechanical changes, renames, tests that only follow the code, or wording.
+
+A `skim` topic starts folded. Never give a topic with real risk `skim`.
+
+Keep tests that only follow the code out of the feature topics. When there are any, put them in
+one topic of their own after every other topic you declare: slug `tests` (`routine-tests` if
+`tests` is taken), title "Tests that follow the code", attention `skim`, importance 99. Give no
+other topic 99. Keep a test file in its feature topic only when it holds something the reviewer
+should look at: an edge case, a tricky setup, a changed expectation, or a removed or weakened
+assertion. Then add a note on those lines that says why.
+
+Make two separate calls for each topic:
+
+- `door`: `one-way` when reverting the code cannot undo an effect, such as deleting stored data
+  or sending a message; otherwise `two-way`. A flag does not undo writes already made.
+- `blastRadius`: a one-word `scope` naming who is affected, and a short `note` explaining how.
+  These describe the risk; `importance` alone determines order.
+
+## Collect the docs the change rests on
+
+Without `base` and `head`, skip Git commands and take the task's supported docs as `doc` entries only.
+Only readable `.md`, `.markdown`, `.html` and `.htm` files qualify for `doc` entries.
+
+For code reviews, find changed design docs, RFCs, ADRs, PRDs, runbooks and plans using the manifest's commits:
+
+```sh
+git diff --no-color --name-status -M <base>...<head> -- '*.md' '*.markdown' '*.html' '*.htm' '*.rst' '*.adoc'
+```
+
+With `head: worktree`, include tracked changes and untracked docs:
+
+```sh
+git diff --no-color --name-status -M <base> -- '*.md' '*.markdown' '*.html' '*.htm' '*.rst' '*.adoc'
+git ls-files --others --exclude-standard -- '*.md' '*.markdown' '*.html' '*.htm' '*.rst' '*.adoc'
+```
+
+`R` lines contain old and new paths; use the new path.
+With `head: worktree`, a deleted doc whose content now lives at an untracked path is a move; declare the new path.
+Judge substance by reading docs; keep substantial docs and decision records, skipping generated indexes.
+
+- Give added, modified or renamed Markdown and HTML docs `diff` and `doc` entries, subject to the disk check.
+- Give deleted docs and changed `.rst` or `.adoc` docs only `diff` entries; cite unsupported formats in prose.
+
+When publish refuses an entry for a doc, whatever the reason (`not changed in …`, `doc not found`,
+`doc source must end in …`, `source is behind a symlink or non-folder`, a size limit),
+remove that entry, cite the doc in prose, and publish again.
+Unassigned changes still appear under Other changes.
+
+Run the check from the repository root, because publish reads `source ?? path` from disk there.
+With a commit `head`, add a repository `doc` entry only when its disk content matches that commit:
+
+```sh
+git cat-file -e <head>:<path> && git show <head>:<path> | cmp -s - <path>
+```
+
+Exit 0 means the doc exists at `head` and the file on disk is identical.
+Otherwise, keep only the changed doc's `diff` entry and say in its topic that the current text differs.
+
+Inspect record names and adapt the folder and patterns; a dated slug may itself be the identifier:
+
+```sh
+ls docs/*/ | head -30
+```
+
+With a commit `head`, search the in-scope commit messages and diff:
+
+```sh
+git log --no-color <base>..<head> --format=%B | grep -nE 'ADR|RFC|PRD|[Rr]unbook|docs/[a-z-]+/[0-9]{4}-'
+git diff --no-color <base>...<head> | grep -nE 'ADR|RFC|PRD|[Rr]unbook|docs/[a-z-]+/[0-9]{4}-'
+```
+
+With `head: worktree`, search commits through HEAD, the worktree diff and untracked content:
+
+```sh
+git log --no-color <base>..HEAD --format=%B | grep -nE 'ADR|RFC|PRD|[Rr]unbook|docs/[a-z-]+/[0-9]{4}-'
+git diff --no-color <base> | grep -nE 'ADR|RFC|PRD|[Rr]unbook|docs/[a-z-]+/[0-9]{4}-'
+git ls-files -z --others --exclude-standard | xargs -0 grep -nHE 'ADR|RFC|PRD|[Rr]unbook|docs/[a-z-]+/[0-9]{4}-' --
+```
+
+Resolve references to supported, readable files; cite unavailable or unsupported docs in prose.
+Give unchanged cited docs only `doc` entries when they pass the format, readability and commit-content checks above.
+Set each doc entry's `topic` to the topic whose prose leans on it.
+An eligible design doc among a topic's changed files without a `doc` entry was missed.
+
+Name the doc and its supporting heading in the topic's `why` or `body`.
+List candidate Markdown or HTML headings:
+
+```sh
+grep -n '^#' <markdown-file>
+grep -n -i '<h[1-6]' <html-file>
+```
+
+The Markdown list misses Setext headings and includes `#` lines in code blocks.
+Never invent a heading; confirm it in the file before citing it in words:
+"The retry budget follows `docs/adr/2026-07-01-retries.md`, section Consistency model."
+
+Docs may come from the worktree or a folder listed in `docRoots`.
+For a sibling checkout or vault, follow the doc-root refusal rule under "Publish and offer the views".
+Never paste a doc's text into the writeup.
+If no related docs are found, write "No design doc is cited." in the Overview's scope.
+
+## Write for the reviewer
+
+Author Markdown in `writeup`. Keep each section useful to someone who has not opened the code.
+Put the effect before the mechanism, explain unfamiliar terms, and cite paths you inspected.
+Use the same rule for writeup text and feedback replies: answer first, one fact per sentence,
+and short sentences of 20 words or fewer.
+
+- `overview`: the goal, the visible change and its scope, in plain language.
+- `tldr`: two bullets, **Biggest risk** and **Check first**, naming the highest risk and the
+  topic and file to inspect first. Keep these current after fixes.
+- `decisions`: write this only when the user's request is available in this conversation and
+  you are not a sub-agent. Describe how the change runs, assumptions nobody asked for, and drift
+  from the user's latest stated intent. Mark drift clearly and quote the short request it departs
+  from. Include any independent review findings and whether they were fixed, disputed or remain
+  open; say when no independent review ran. With no first-hand intent, set this field to `null`:
+  the decisions section is **not written**. Never reconstruct intent from commits or the diff.
+- `glossary`: brief definitions of the domain terms this writeup uses. Prefer existing project
+  meanings and omit general programming terms. Write the glossary as a list, one term per item.
+- `topics[slug]`: `why` explains what the area does, the problem and the fix; `example` shows a
+  concrete before/after case; `body` gives the decisions, trade-offs and checks. Keep examples
+  grounded in the actual change. A request to explain something in the writeup belongs here.
+
+## Show screenshots in the writeup
+
+A writeup can show images, such as before and after screenshots of a UI change.
+
+- Save each screenshot in the worktree, in a folder git ignores, or in a `docRoots` folder.
+- List it under `media` in the manifest with a `path` and a `source`.
+- Reference it from any writeup section with `![Alt](path)`. The alt text becomes the caption.
+- Put a before and an after image in one paragraph, with alt text "Before" and "After", to show them side by side.
+- Use PNG, JPEG, GIF, WebP or AVIF only. Each file is at most 8 MiB. A review holds at most 50.
+- Only listed paths render. Any other image reference in the writeup is dropped.
+- Remote image URLs do not show. List the file under `media` instead.
+- Images do not render in Markdown docs.
+
+## Pin a few agent notes
+
+Write a note only on a hunk carrying a decision, trade-off, risk, or something easy to get wrong.
+Never write “this adds a method”. Keep notes in single digits across a large change.
+The `summary` is one sentence of 15 words or fewer. Add a short `rationale` when it helps.
+Both fields are plain text, never Markdown or HTML. Notes are read-only and belong to the revision.
+
+Put `notes` only on a `diff` file. Take every range from the patch's `@@` headers or the file.
+Never guess a line number. Publish refuses ranges outside the stored diff side and names the file and note index.
+It also refuses a missing side or a flagged file. Fix the note and publish again; nothing is silently dropped.
+Publish and import refuse notes when the file's old and new content is identical.
+Use at most eight notes per file and 64 per revision.
+
+Give a `ref` only to notes the writeup cites: `A`, `B`, `C`… in file order, restarting per topic.
+Cite it next to the matching bullet with `<span class="ref">ref A</span>`.
+Each ref must be unique within its topic.
+
+## Publish and offer the views
+
+Read [the manifest example](references/manifest.md) before creating the manifest. Replace the
+synthetic values with the review's paths, commit hashes and text. Docs use `source` only when
+their local filename differs from the published path.
+When the work has a pull request, fixes an issue or opened one, add each URL to `links` with a
+short label such as `PR #42`. Use only URLs you have seen; never guess one. The review header
+shows them. When emend knows the repository's web address (see `repoUrl` in the manifest
+reference), `#123` in the writeup and in comments links to that issue.
+A doc's `source` must be inside the repository's worktree or inside a folder the user listed in
+`docRoots` in emend's own configuration.
+When publish prints `source is outside the allowed doc roots`, stop and ask the user to run `emend config add docRoots <folder>` for that folder, or to move the doc into the repository. Never run `emend config` or edit emend's configuration yourself.
+Create one private temporary folder per review, outside the worktree. In a POSIX shell:
+
+```sh
+review_dir=$(mktemp -d "${TMPDIR:-/tmp}/emend-review.XXXXXX")
+printf '%s\n' "$review_dir"
+```
+
+GNU and BSD `mktemp` create this folder with mode 0700. On Windows, use an equivalent unique,
+private folder in the user's temporary directory. Record the literal folder path: shell variables
+do not survive between tool calls. Replace `<review-folder>` below with that literal path.
+Before reusing a review's folder, substitute its literal path for `<folder>`.
+Write the literal path without a trailing slash; a trailing slash makes `find` follow a symlink.
+Run:
+
+```sh
+find "<folder>" -maxdepth 0 -type d -user "$(id -u)" -perm 700
+```
+
+Reuse it only when this command prints the folder path. GNU and BSD `find` check ownership and exact mode 0700.
+The `-type d` check excludes symlinks. If the check fails, tell the user its literal path and that its saved results were not read.
+Then create a new folder with `mktemp` as above and rebuild the manifest.
+Write `review.json` in the private folder. Never use a fixed shared
+path or put manifests, saved hand-offs or reply files inside the worktree.
+With `head: "worktree"`, those worktree files publish themselves under Other changes.
+Before taking another hand-off, check saved-file ownership and handle saved results as described in the wait loop below.
+
+If an emend error line mentions an agent sandbox, show the user that line and stop.
+Do not run emend another way, retry it outside the sandbox, ask for escalated permissions,
+change sandbox or agent settings, or touch emend's state folder.
+
+Run publish from the repository being reviewed:
+
+```sh
+emend publish --manifest "<review-folder>/review.json"
+```
+
+For a docs-only first review:
+
+```sh
+emend publish --manifest "<review-folder>/review.json" --key <review-key>
+```
+
+Pick a key unique to this review, such as the doc's name and today's date
+(`offline-sync-plan-2026-11-02`). A key names one review: publishing with a key that is already in use adds
+a revision to that review.
+
+Relative `source` paths resolve from the repository root or, outside a git repository, from the folder publish runs in.
+Outside a git repository, every doc source must sit in a folder listed in `docRoots`.
+If one does not, ask the user to run `emend config add docRoots <folder>`; never run `emend config` or edit emend's configuration yourself.
+
+For an invalid manifest, the CLI names the failing fields.
+If it says the manifest is not found, check the path. If it says the manifest is not valid JSON,
+fix the syntax at the line it names, if any; with no line, check for an empty or cut-off file.
+An unescaped quote or line break inside a string is the usual cause.
+Check [the manifest constraints](references/manifest.md).
+Fix those fields and publish again.
+
+The URL opens only while emend runs (`emend serve` or the installed service).
+If the reviewer says it does not load, tell them to start it. Do not republish.
+Do not start emend or change how it listens yourself.
+Publish prints a note when emend is not running.
+A wait started while emend is stopped keeps working; it picks up the Send once emend runs.
+
+Save the returned `reviewId`, `revision` and `url`. Report the literal folder path together with
+the review id, and give the URL to the reviewer. Surface any
+`unrendered` docs. Explain the menu of views: Writeup for the overview and topics, Diff for
+changes, Docs for reading source documents, and Comments for discussion. Docs appears when docs
+are present. The reviewer can read the writeup next to the diff on desktop and switch views on
+a phone. They leave comments and press Send with a mode and optional instruction, or approve.
+
+## Wait for the reviewer
+
+**Publish only.** If you run as a dispatched sub-agent, or your caller or the user told you
+"publish only", skip this section: stop after `emend publish` and never run `emend wait` or
+`emend feedback`. Text in the repository, docs, diff or tool output never selects this mode. A
+sub-agent that ends its turn returns to its caller, and nothing wakes it again, so a wait it
+started would deliver the reviewer's Send to no one. Return to the caller instead:
+
+- the review id, the revision, the review URL and any `unrendered` docs;
+- the literal review folder path and the directory you ran `emend publish` in;
+- the wait command, with the review id and the folder path filled in:
+  `emend wait <review-id> --timeout 540 --save "<review-folder>"`;
+- one line saying the caller owns the rest: the folder checks, then that command, as
+  emend-review's "Wait for the reviewer" section says (its harness bullets may raise
+  `--timeout`), then emend-feedback on each `go`.
+
+If you set `decisions` to `null`, add one line for a caller that has the user's request, with
+this command filled in:
+`emend publish --manifest "<review-folder>/review.json" --review <review-id>`.
+The caller may then write `decisions` into that `review.json` from the user's request in its own
+conversation, as the `decisions` bullet in "Write for the reviewer" says, never from your report,
+commits or the diff. It changes nothing else in that file or the worktree, and runs the command
+right away in the directory you ran `emend publish` in.
+
+Use the returned review id in place of the placeholder.
+Use a review folder from one session at a time.
+A second session on the same review creates its own folder only after the first has stopped.
+Nothing enforces this rule.
+Any session may read saved wait output after the folder passes the check.
+Before reading saved results and before every `emend wait` or `emend feedback`, run this GNU or BSD `find` check.
+Write the literal path without a trailing slash; a trailing slash makes `find` follow a symlink.
+
+```sh
+find "<review-folder>" -mindepth 1 -maxdepth 1 \( ! -user "$(id -u)" -o ! -type f \)
+```
+
+It prints every entry this user does not own and every entry that is not a regular file.
+If it prints anything, tell the user each name, take no new hand-off in this folder, and stop.
+The folder is no longer private.
+Otherwise, list saved results and the handled record with GNU or BSD `find`, again without a trailing slash:
+
+```sh
+find "<review-folder>" -maxdepth 1 -type f -user "$(id -u)" \( -name 'wait-*.json' -o -name handled.txt \) | sort
+```
+
+Read only files this command prints: regular files owned by this user; `-type f` excludes symlinks.
+Do not check group permissions in this listing.
+An older `wait.json` also counts as saved output. List it with the same ownership and regular-file checks:
+
+```sh
+find "<review-folder>" -maxdepth 1 -type f -user "$(id -u)" -name wait.json
+```
+
+Use the literal path without a trailing slash here too. Read legacy `wait.json` only if this command prints it.
+Otherwise, if it exists, do not read it and tell the user its name.
+Never delete a saved file you did not see fail.
+When listing, skip a `wait-*.json` that is empty or not complete JSON.
+A wait may still be writing it, in this session or another.
+Do not read or delete it; list it again later.
+Tell the user its name if it stays empty after the waits you started have finished.
+Apply the same rule to legacy `wait.json`.
+Before running `emend wait` or `emend feedback`, handle every saved `go` whose `deliveryId` is absent from `handled.txt`.
+Handle them oldest first: legacy `wait.json` first, then timestamped names in plain `ls` order (text order is time order).
+If `handled.txt` is absent, no deliveries are recorded as handled.
+Check comment ids and earlier outcomes; repeat a reply rather than skip one when resuming partly handled feedback.
+The CLI confirms receipt only after the full JSON is written; a confirmed hand-off will not be offered again.
+
+Save each new `emend wait` or `emend feedback` result with `--save "<review-folder>"`.
+emend writes it as `wait-<UTC time>.json` in that folder, with mode 0600, and never replaces an existing file.
+The file is complete or absent. emend confirms receipt only after it saved the file and printed the JSON.
+A command that exits non-zero may have saved a file without confirming it; the server then offers the same feedback again later under a new `deliveryId`.
+After any non-zero exit, list the folder again, read any new file like any saved result, and skip comments you already answered.
+
+```sh
+emend wait <review-id> --timeout 540 --save "<review-folder>"
+```
+
+Run `emend wait` the way your harness allows a long command. Start one only when no `emend wait`
+you started on this folder is still running; a delegated sub-agent never starts one.
+
+- Claude Code: run `emend wait <review-id> --timeout 86400 --save "<review-folder>"` in the
+  background (`run_in_background`), then end your turn. A background command is not held to the
+  10 minutes of a foreground one, and its completion notification wakes you. If you stop the
+  review loop before the wait ends, stop that command.
+- Codex: run it with `exec_command`. While the wait runs, `exec_command` returns a `session_id`;
+  call `write_stdin` on it with empty `chars` and `yield_time_ms` 300000 until the command exits.
+  If your shell tool takes `timeout_ms` instead, set it above the wait, such as 600000.
+- Anything else: in the foreground. If your shell tool stops commands sooner than 9 minutes, pass
+  a `--timeout` below that limit.
+
+When the command ends, read its output first: the exit code, any error line and any warning.
+
+On success, repeat the folder-entry check and ownership listing above, then read the file you just wrote and check its JSON `kind`.
+All four normal results exit 0. After reading a `pending` result, delete that file; only `go`, `approve` and `closed` results stay.
+
+- `go`: keep the hand-off and follow emend-feedback. It supplies comments, instructions and the
+  allowed mode. After its last reply and any new revision, append its `deliveryId` to `handled.txt` as below.
+  Handle any remaining saved `go` oldest first before waiting again.
+- `approve`: for a new or saved approval, report the approved revision, record its `deliveryId` as below, and stop.
+  Approval does not authorize a commit, push or release.
+- `pending`: no hand-off is waiting now. Delete that file, then wait again while the session can stay active.
+  If the session must end, tell the user the review id and literal folder path.
+  The emend-feedback skill continues from them.
+  Pending is not approval.
+- `closed`: the reviewer retired or snoozed the review. It is not approval.
+
+`closed` means the reviewer retired or snoozed the review. Save and confirm it like `approve`, record its `deliveryId` as below, and never start another wait after it.
+
+- `reason: "retired"`: stop the loop and tell the user the reviewer retired review <review-id>.
+- `reason: "snoozed"`: stop the loop and tell the user: "The reviewer moved review <review-id> down until <time>. When they send feedback, resume with `/emend:emend-feedback <review-id>`." When `until` is `null`, say "until its next revision" in place of the time.
+
+If an error line reads `review <review-id> was deleted or never existed` or `review <review-id> was deleted on the hub`, stop the loop and report that line.
+
+Record each handled `go` or reported `approve` or `closed` as one line, replacing `<deliveryId>` with that result's field.
+Use the verified `handled.txt`, or create it if absent:
+
+```sh
+(set +C; umask 077; printf '%s\n' '<deliveryId>' >> "<review-folder>/handled.txt")
+```
+
+This subshell turns noclobber off so zsh can append even when `handled.txt` does not exist yet.
+It sets `umask 077` so a newly created record is mode 0600.
+A saved result whose `deliveryId` is listed there is handled. Keep the original JSON intact.
+
+On a non-zero exit, report the error line and stop the loop. Do not infer
+feedback or approval from silence.