@ethlete/agent-rules 0.1.0-next.2 → 0.1.0-next.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.3
+
+### Patch Changes
+
+- [`ca0bf2f`](https://github.com/ethlete-io/ethdk/commit/ca0bf2f09cd5bd925da52bdb17c93bb62bda8735) Thanks [@TomTomB](https://github.com/TomTomB)! - The `comments` rule is now an allowlist: four kinds of comment are allowed and everything else gets deleted.
+
 ## 0.1.0-next.2
 
 ### Minor Changes

package/content/rules/comments.md

@@ -1,31 +1,61 @@
 ---
 name: comments
-description: Write comments for the next reader of the file, not for the reviewer of your change.
+description: Comments are an allowlist of four cases. Everything else gets deleted before the change is done.
 kind: rule
 scope: both
 ---
 
-## Comments: write for the next reader of this file, not for the reviewer of your change
+## Comments: almost none, and never for the reviewer of your change
 
-A comment earns its place by telling someone **using or editing this code** something the
-code cannot. Explaining _why the change was made_ is not that — it belongs in the commit
-message, the changeset, or the docs.
+**Write no comment unless it fits one of the four cases below.** This is an allowlist, not a
+set of tips. Anything outside it gets **deleted** before you call the change done — not
+softened, not shortened. Code that needs prose to be understood needs a better name, a
+smaller function, or a type; fix that instead of narrating it.
 
-Do **not** leave behind:
+### The only comments allowed
 
-- **Rationale for a mechanical choice.** `Record<Size, X>` with literal keys, a `@__PURE__`
-  annotation, a factory instead of a literal, a helper moved to another file — the type,
-  the annotation and the import already say what happens.
-- **Migration narration.** "moved here from X", "used to be a tuple", "so Y no longer pulls Z".
-  Git knows. A reader six months from now does not care.
-- **The same explanation repeated per call site.** If a pattern needs explaining, explain it
-  once where the pattern is defined (the helper's JSDoc, the lint rule's message, the guide)
-  and let every use site stay silent.
-- **Restating the code.** `// increment the counter` above `counter++`.
+1. **An ordering or timing constraint** a reasonable edit would break. Say what breaks.
+2. **An invariant the types cannot express**, that a caller or a future edit could violate.
+3. **A workaround**, naming its concrete cause (browser bug, upstream issue, framework
+   limitation) and linking it where a link exists, so the next reader can tell when it may go.
+4. **Public API JSDoc** — what it does and how to call it, on something a lib actually
+   exports. One or two sentences. Not internals, not history, not why it is shaped that way.
 
-Do keep: non-obvious behaviour and ordering constraints, a real invariant a future edit could
-break, a workaround with the reason it exists, and public API JSDoc (what it does and how to
-use it — not why it is shaped that way).
+Nothing else qualifies. Not "this is subtle", not "worth noting", not a heading over a group
+of members, not a summary of the function underneath it.
 
-When you catch yourself writing "because", check whether the sentence is aimed at the reviewer
-of your diff. If it is, cut it.
+### The test each one still has to pass
+
+Delete it unless **both** are true:
+
+- a competent reader who never sees your diff would be **surprised** without it, and
+- a future edit could **break something** that this sentence is the only warning about.
+
+Unsure counts as no. A missing comment costs a minute of reading; a stale one misleads for
+years.
+
+### Always delete
+
+- **Restating the code** — `// increment the counter` over `counter++`; a JSDoc on `size` that
+  says nothing beyond "the size of the button".
+- **Section headers and dividers** — `// --- Inputs ---`, `// Helpers`, `// Public API`.
+- **Rationale for a mechanical choice** — `Record<Size, X>` with literal keys, a `@__PURE__`
+  annotation, a factory instead of a literal, a helper moved into its own file. The type, the
+  annotation and the import already say what happens.
+- **Migration narration** — "moved here from X", "used to be a tuple", "so Y no longer pulls
+  Z", "renamed for clarity". Git knows; the next reader does not care.
+- **The same explanation at every call site.** Explain a pattern once where it is defined (the
+  helper's JSDoc, the lint rule's message, the guide) and let every use site stay silent.
+- **Commented-out code.**
+- **`TODO`/`FIXME` without an issue link.** Fix it now or leave nothing.
+- **Hedging and meta** — "note that", "for clarity", "just in case", "this is cleaner", "we
+  could also…".
+
+### Before you call the change done
+
+Re-read every comment in your diff and cut the ones that are not one of the four. Then fix or
+delete any existing comment your change made wrong — one describing behaviour that no longer
+exists is worse than none.
+
+Two signals you have already over-commented: you wrote the word "because", or the diff adds
+more than a handful of comments. Both mean go back and cut.

package/content/skills/sdk-local-build/SKILL.md

@@ -21,8 +21,10 @@ published yet, or when you are iterating on it.
   {%skill:sdk-source%} covers resolving it and what to check before trusting it.
 - The checkout has its dependencies installed (`yarn install` in the checkout root - the
   SDK repo is a Yarn 4 workspace).
-- Note which branch it is on. Building `main` when your app runs `-next` prereleases
-  swaps in a completely different API surface.
+- Check which branch it is on before building - unless the user said otherwise, that
+  should be `next`, up to date with `origin/next`. Building `main` when your app runs
+  `-next` prereleases swaps in a completely different API surface, and building a stale
+  `next` rebuilds a bug that is already fixed upstream. Ask before changing its branch.
 
 ## 2. Build the libraries you changed
 

package/content/skills/sdk-source/SKILL.md

@@ -38,15 +38,40 @@ holds the full `.d.ts` surface of exactly the version this repo runs - and to
 {%docsBaseUrl%}. Then tell the user a local checkout would help, and offer the snippet
 above (the file is gitignored, so adding it changes nothing for anyone else).
 
-## 2. Check the checkout matches what is installed
+## 2. Check the branch before you read anything
 
-A checkout sits on whatever branch the developer left it on, so it can be months of
-work ahead of the installed package - or behind it. Compare before you trust it:
+A checkout sits on whatever branch the developer left it on, so the first command you
+run against it is the one that tells you what you are looking at:
 
 ```bash
-grep '"@ethlete/' package.json                          # what this repo runs
+git -C <sdkSourcePath> fetch --quiet          # read-only, safe
+git -C <sdkSourcePath> status -sb             # branch, ahead/behind, dirty files
+```
+
+**Unless the user says otherwise, the expected state is `next`, up to date with
+`origin/next`.** That is the branch the SDK develops on, and the one the `-next`
+prereleases are cut from. Anything else and you are reading a different SDK than the
+one you are about to describe.
+
+When it is not in that state, **say so and ask** - never switch, pull, stash or reset
+it yourself. It is someone's working tree, and the read-only rule below applies:
+
+- **On another branch** - name it and ask whether to read it as-is or whether they want
+  `next`. A feature branch may be exactly what you were sent to look at.
+- **Behind `origin/next`** - report how far. The code you would quote may already be
+  fixed upstream, so read the missing commits before calling anything a bug:
+  `git -C <sdkSourcePath> log --oneline HEAD..origin/next`.
+- **Dirty** - it may contain someone's work in progress. Say so rather than quoting it
+  as SDK behaviour.
+
+## 3. Check the checkout matches what is installed
+
+Even on a clean `next`, the checkout can be months of work ahead of the installed
+package - or behind it:
+
+```bash
+grep '"@ethlete/' package.json                                 # what this repo runs
 grep -m1 '"version"' <sdkSourcePath>/libs/<lib>/package.json   # what the checkout is at
-git -C <sdkSourcePath> status -sb                       # branch, and whether it is dirty
 ```
 
 Rules when they differ:
@@ -55,10 +80,8 @@ Rules when they differ:
   `.d.ts` in `node_modules` is the truth about the API you are calling.
 - Source that is ahead describes an **unreleased** API. Never write consumer code
   against it, and never assume it is available - say what release it needs.
-- A dirty checkout may contain someone's work in progress. Say so rather than quoting
-  it as SDK behaviour.
 
-## 3. Where things live
+## 4. Where things live
 
 Paths are relative to the checkout root:
 
@@ -79,7 +102,7 @@ Inside a component domain: `<name>.component.ts` with its `.css` next to it,
 `index.ts` as the barrel. The lib's public surface is `libs/<lib>/src/index.ts` -
 anything not re-exported from there is internal, whatever it looks like.
 
-## 4. Search it, don't read it whole
+## 5. Search it, don't read it whole
 
 ```bash
 rg -n "etButton" <sdkSourcePath>/libs/components/src --glob '!*.spec.ts'   # a selector
@@ -91,12 +114,14 @@ Specs are the cheapest description of intended behaviour - `<name>.component.spe
 next to a component usually answers "is this supposed to happen?" faster than the
 implementation does.
 
-## 5. The checkout is read-only from here
+## 6. The checkout is read-only from here
 
 It is a different repository with its own branch, lint, docs and changeset workflow.
-Never edit it while working on a task in this repo, and never copy its internals into
-consumer code - a private helper is not a supported API and disappears without a major
-version (the same goes for anything under a `subtle` namespace).
+Never edit it while working on a task in this repo - that covers its git state too, so
+no `checkout`, `pull`, `stash` or `reset` without the user asking for it (`fetch` is
+fine). Never copy its internals into consumer code either - a private helper is not a
+supported API and disappears without a major version (the same goes for anything under
+a `subtle` namespace).
 
 When the fix belongs in the SDK, say so and describe it precisely: file, symbol, and
 the behaviour it should have. If the user wants that fix verified against this app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/agent-rules",
-  "version": "0.1.0-next.2",
+  "version": "0.1.0-next.3",
   "license": "MIT",
   "type": "commonjs",
   "main": "./src/index.js",