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

package/content/skills/design-exploration/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: design-exploration
+description: How a visual design exploration runs - the step size, what to put in front of the user at each stop, and when you may commit. Read BEFORE any visual design work on a sketch, a prototype, a theme, a palette, or the look of a component. The user is the designer; you find and frame, and you never pick the fix alone.
+kind: skill
+scope: both
+vars: [storybookUrl]
+---
+
+# Design exploration
+
+A design exploration is a dialog. **The user is the designer. You find and frame. The user
+chooses.** A finding is not a licence to pick the fix.
+
+The unit of work is a **call**: one open question, with every answer drawn side by side at
+the same geometry. A variant wins or loses only against the other variants of its call.
+
+## The rules
+
+1. **One open call at a time.** Take one question. Draw its variants. Stop.
+2. **Put the variants in the call, then name your pick.** Two to four variants, drawn for
+   real, side by side, labelled, with what each one costs. Your pick is a proposal.
+3. **Commit only when the user says commit.**
+4. **A clear rejection starts the next call.** Settle and record the rejected call, then draw
+   the next focused question automatically, within the user's original scope. Stop only when the
+   user asks to pause or end the exploration, or when their feedback leaves no grounded next
+   question.
+5. **Keep the answer short.** 120 words at most.
+
+Confirm the step size once, at the start. Do not ask again at every stop. A task is not
+finished while the user is still talking about it.
+
+## What one stop looks like
+
+- The question, in one sentence.
+- The call slug to look at.
+- The variants, labelled A, B, C, one line each.
+- Your pick, one line on why.
+- Nothing else. No next step, no second finding.
+
+**Do not send a screenshot.** The user keeps the page open. Screenshot only for your own
+check that a variant renders.
+
+If a second defect appears, add it to the open list and give it one line. Do not draw it.
+
+## Where the variants are drawn
+
+The exploration's plan file names the tool. Two shapes exist.
+
+**A repository with a `.ethlete/design` folder** draws a call per page, each variant in its own
+iframe. The tool is `et design`, from `@ethlete/cli`, so the repository itself needs no design
+tooling. A call argues in the repository it is about:
+
+```
+.ethlete/design/
+  config.json     the port, the default call, and one entry per project
+  calls/<project>/<group>/<slug>/
+    call.ts       the eyebrow, the headline, the intro, frameWidth, the variants and the round prose
+    fixture.ts    the data every variant shares
+    variant-a.ts  one default-exported drawing per variant
+    variant-b.ts
+```
+
+The first segment of a slug is the **project**. `config.json` gives each project its own
+`styles` and its own `head`, so one project's type scale and fonts never reach another's
+drawings. A project the config names not draws bare.
+
+Start the page with `et design [checkout]`, which serves the port `config.json` names. The
+checkout defaults to the working directory, and `DE_PORT` overrules the config, so two
+checkouts can be drawn at once. A repository that builds the tool rather than installing it
+wraps this in a script - in the ethlete SDK, `yarn design:check`. There, the user reads the
+calls in Ethlete Studio, started with `yarn studio`, and Studio serves the page itself. Do not
+start `yarn design` next to it.
+
+Ethlete Studio carries its own copy of the tool, so it draws a checkout that installs nothing.
+The machine still needs Node, and the render stage still needs `playwright` where the copy in
+use can reach it.
+
+`call.ts` calls `defineCall` from `@design-explore`. Each variant carries a `key`, a `name`,
+a `claim`, a `cost`, an optional `verdict` of `chosen` or `rejected`, and a `load` that
+imports its own module. The host greys a rejected variant and shows it on hover.
+
+In a call that runs past about a dozen variants, every variant names the pass that drew it with
+`round: 'r3'`. **That tag is the only thing that makes a round exist.** The host reads the
+variants, draws one band per round in the order the variants introduce them, and lists those
+same bands in the sidebar, so a new variant can never leave the menu stale. A round whose
+variants all carry a verdict is **settled**: the page folds it down to its winner plus one row
+per rejected variant, and a link opens it again.
+
+A call whose rounds have all ruled is **resolved**. Its winners usually form a chain, each one
+the last plus a change, so the page stops drawing them: it leads with a **Result** band holding
+the final winner, and prints the chain as a row of keys above it. Every round below folds to
+rows. A key in the chain opens the round that drew it.
+
+`rounds` is prose only. Each entry gives a `key`, a `title` and a `note` saying what came out
+of that pass, which is how the intro stays short and each pass reads as a reply to the one
+before. An untagged round still draws and still gets a menu row - it says the bare key until
+somebody writes the entry. A `rounds` entry that no variant names is stale prose, and the host
+and the check both report it. Write the note in the same pass that sets the verdicts, never
+before the user rules.
+
+A call with one variant and no `claim` is a **view**: one reference picture, drawn full
+width with no verdict tag. Use it for a picture that answers no question.
+
+Two views, and a way to compare:
+
+- **rounds** is the default. Round headings, the result band, and the folding above.
+- **all N** is a contact sheet: every variant in the call at about a third size, in one grid, so
+  a call of two dozen fits on a screen or two. Use it to find the variants worth a close look.
+- Clicking a variant's name anywhere - a heading, a folded row, a thumbnail - puts it in the
+  **compare overlay** at the top of the page. Two drawings that differ by a few pixels can only
+  be told apart in one place, so the overlay stacks every pick in one box at full size and the
+  reader switches between them: click the box or press space to blink, and with two picks the
+  arrow keys wipe a seam across. Nothing is scaled and nothing moves. The picks live in the URL
+  under `pick`, so a comparison is a link you can send.
+
+Three constraints the tool puts on a variant file:
+
+- **Never import a package barrel.** The libraries resolve to source, so one barrel makes
+  the browser request every module in the library, and the requests fail with
+  `ERR_INSUFFICIENT_RESOURCES`. Import the one file you need.
+- **The fixture is shared, and a variant may not change it.** Variants drawn at three
+  geometries cannot be compared.
+- **One file per variant**, so several agents can draw at once, and a broken variant breaks
+  its own frame only.
+
+**A repository with a sketch Storybook** draws every variant in the **same** story, side by
+side, under the real geometry the thing ships in. The default Storybook is
+{%storybookUrl%}; an app with its own sketch Storybook names its port in the plan file.
+
+Either way:
+
+- Sketches take inputs only and stay out of the application's build.
+- Prototype, never refactor. Do not touch the shipped component until the treatment is
+  settled.
+- Keep the rejected variants drawn, marked as rejected.
+
+## Check before you look
+
+A broken build draws an overlay, so a screenshot of it looks like a design. **One check
+covers that, and it is the whole gate.** Name the files you changed, never a whole project,
+which is far slower and can fight the user's own editor.
+
+With `et design`, run the checker from the checkout it draws:
+
+```bash
+et design check --lint <changed files> --tsconfig
+```
+
+`--tsconfig` with no path types every call of the checkout. `--checkout <path>` names another
+one.
+
+With a Storybook, copy {%resource:check-story.mjs%} to the **repository root** first:
+
+```bash
+node check-story.mjs --lint <changed files> --tsconfig apps/<app>/.storybook/tsconfig.json
+```
+
+Both take about four seconds and need no dev server. Then stop and hand the slug to the
+user. Do not also open the page in a browser: it costs a browser launch, and both tools
+transpile without type checking, so the render reports `ok` on a file that does not
+compile. Open it only when the check passes and the drawing still does not appear:
+
+```bash
+et design check --call <slug>             # every variant of the call
+et design check --call <slug> --variant b # one of them
+node check-story.mjs --tsconfig <path> --story <story-id>
+```
+
+## Delegating a call
+
+A call has one job per variant, so it fans out. Every brief names `model: opus`.
+
+1. **One agent per variant.** Give it the call folder, the variant key, the fixture it must
+   not change, and the one claim its drawing has to support. Tell it to write its own
+   variant file and nothing else, so two agents never touch one file.
+2. **One check-and-fix agent, after the drawing agents return.** Give it the changed files
+   and the call slug. It runs the check above, fixes what it reports, and repeats until the
+   check says `ok`. It may not change what a variant draws, only what stops it rendering.
+3. **One write-up agent, once the user settles the call.** Give it the verdict in the
+   user's own words and the plan file. It records what won, what lost and why, it sets each
+   variant's `verdict` in `call.ts`, and it writes that round's `note`. It runs while you open
+   the next call.
+
+## Screenshots
+
+**Off by default.** The user has the page open and sends you a picture when something looks
+wrong. Take one only when the code cannot tell you whether two variants really differ, and
+never to put in front of the user. Copy {%resource:shoot-template.mjs%} to the repository
+root.
+
+```bash
+node shoot.mjs <story-id> 1100 760 out.png
+```
+
+- `waitUntil: 'networkidle'` never settles on an iframe that holds a live dev server
+  connection. Use `'domcontentloaded'`.
+- `:hover`, `:focus-visible` and `:active` need a CDP session and `CSS.forcePseudoState`.
+  Several hold open at once, so one image shows them all. The template does this.
+
+## Writing it down
+
+Every settled call goes in the exploration's plan file: what won, what lost, and why. Keep
+an **Open** list for the calls not yet made. A rejected variant written down stops the next
+session from drawing it again. After a clear rejection, use that record to frame and draw the
+next call; do not wait for the user to type “continue”.

package/content/skills/design-exploration/check-story.mjs

@@ -0,0 +1,139 @@
+/**
+ * Find out why a story does not render, in the cheapest order.
+ *
+ * A compile error renders as an overlay on top of the story, so a screenshot of it looks
+ * like a design. Run this first, and never screenshot before it says `ok`.
+ *
+ * Copy to the repository root - Node resolves `playwright` from the working directory.
+ *
+ *   node check-story.mjs --lint <file>… --tsconfig <path>        # ~4s, no browser
+ *   node check-story.mjs --tsconfig <path> --story <story-id>    # + the render
+ *   SB_URL=http://localhost:4401 node check-story.mjs --story <story-id>
+ *
+ * Three stages, because they cost three different amounts:
+ *
+ * 1. `eslint` on the files you changed, about a second. Name the files - never a whole
+ *    project, which is far slower and can fight the user's own editor.
+ * 2. `tsc --noEmit` reads the source. It needs no dev server, waits for no rebuild, and
+ *    catches every syntax and type error in about three seconds. Almost everything you
+ *    break is caught here.
+ * 3. The browser catches what the source cannot: an Angular template error, a runtime
+ *    throw, a missing story id. It costs a browser launch, and it can only see a build the
+ *    dev server has already finished, so a fresh edit needs a few seconds first.
+ *
+ * A type error does not stop this repo's Storybook - it transpiles without checking - so
+ * stage 2 alone will report `ok` on a file that does not compile. That is why stage 1 exists.
+ */
+import { execFileSync } from 'node:child_process';
+
+const BASE = process.env.SB_URL ?? 'http://localhost:4400';
+
+/**
+ * The type checker to run. `tsc` resolves the one the repository installed. Set
+ * `TSC=@typescript/native-preview` for the Go port, which is about a third faster - but it
+ * rejects a `baseUrl` in the config, so a repository that still uses one cannot run it.
+ */
+const TSC = process.env.TSC ?? null;
+
+const flags = { '--lint': [], '--tsconfig': [], '--story': [] };
+let current = null;
+
+for (const arg of process.argv.slice(2)) {
+  if (arg in flags) current = arg;
+  else if (current) flags[current].push(arg);
+}
+
+const lintFiles = flags['--lint'];
+const [tsconfig] = flags['--tsconfig'];
+const [id] = flags['--story'];
+
+if (lintFiles.length === 0 && !tsconfig && !id) {
+  console.error('usage: node check-story.mjs [--lint <file>…] [--tsconfig <path>] [--story <id>]');
+  process.exit(2);
+}
+
+/** A bundler stack runs to hundreds of frames and says nothing. Keep the message. */
+const trim = (text) =>
+  [...new Set(text.split('\n').filter((line) => !/^\s+at /.test(line) && line.trim() !== ''))].slice(0, 12).join('\n');
+
+if (lintFiles.length > 0) {
+  try {
+    execFileSync('npx', ['eslint', ...lintFiles], { encoding: 'utf8', stdio: 'pipe' });
+  } catch (error) {
+    console.error(`LINT\n${trim(`${error.stdout ?? ''}${error.stderr ?? ''}`)}`);
+    process.exit(1);
+  }
+}
+
+if (tsconfig) {
+  try {
+    const cmd = TSC ? ['-y', TSC] : ['tsc'];
+    execFileSync('npx', [...cmd, '--noEmit', '-p', tsconfig], { encoding: 'utf8', stdio: 'pipe' });
+  } catch (error) {
+    console.error(`TYPE ERROR\n${trim(`${error.stdout ?? ''}${error.stderr ?? ''}`)}`);
+    process.exit(1);
+  }
+}
+
+if (!id) {
+  console.log('ok');
+  process.exit(0);
+}
+
+const { chromium } = await import('playwright');
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1400, height: 900 } });
+
+/** Angular throws at render time; the overlay never shows those, so read the console too. */
+const consoleErrors = [];
+page.on('console', (m) => m.type() === 'error' && consoleErrors.push(m.text()));
+page.on('pageerror', (e) => consoleErrors.push(e.message));
+
+await page.goto(`${BASE}/iframe.html?id=${id}&viewMode=story`, { waitUntil: 'domcontentloaded' });
+
+const rendered = await page
+  .locator('#storybook-root > *')
+  .first()
+  .waitFor({ timeout: 15000 })
+  .then(
+    () => true,
+    () => false,
+  );
+
+/** The webpack overlay is an iframe, so its text is only reachable through a frame locator. */
+const webpackOverlayText =
+  (await page.locator('#webpack-dev-server-client-overlay').count()) > 0
+    ? await page
+        .frameLocator('#webpack-dev-server-client-overlay')
+        .locator('body')
+        .innerText()
+        .catch(() => '(overlay present, text unreadable)')
+    : '';
+/** The Vite overlay keeps its text in a shadow root. */
+const viteOverlayText = await page.evaluate(() => {
+  const overlay = document.querySelector('vite-error-overlay');
+  if (!overlay) return '';
+  return overlay.shadowRoot?.textContent?.trim() || '(overlay present, text unreadable)';
+});
+const overlayText = webpackOverlayText || viteOverlayText;
+
+await browser.close();
+
+if (overlayText) {
+  console.error(`COMPILE ERROR on ${id}\n${trim(overlayText)}`);
+  process.exit(1);
+}
+
+if (!rendered) {
+  console.error(`EMPTY on ${id} - #storybook-root never got a child.`);
+  if (consoleErrors.length > 0) console.error(trim(consoleErrors.join('\n')));
+  process.exit(1);
+}
+
+if (consoleErrors.length > 0) {
+  console.error(`RENDERED WITH ERRORS on ${id}\n${trim(consoleErrors.join('\n'))}`);
+  process.exit(1);
+}
+
+console.log(`ok ${id}`);

package/content/skills/design-exploration/shoot-template.mjs

@@ -0,0 +1,61 @@
+/**
+ * Screenshot one Storybook story, with optional forced pseudo-states.
+ *
+ * Copy to the repository root - Node resolves `playwright` from the working directory.
+ *
+ *   node shoot.mjs <story-id> [width] [height] [out.png]
+ *
+ * To hold :hover / :focus-visible / :active open at the same time, fill FORCED below with
+ * one entry per element. A CSS selector is matched inside the story's document.
+ */
+import { chromium } from 'playwright';
+
+const BASE = process.env.SB_URL ?? 'http://localhost:4400';
+
+/** @type {{ selector: string, states: ('hover'|'focus'|'focus-visible'|'active')[] }[]} */
+const FORCED = [
+  // { selector: '[data-state="hover"] .the-band', states: ['hover'] },
+];
+
+const [id, width = '1100', height = '760', out = 'shot.png'] = process.argv.slice(2);
+
+if (!id) {
+  console.error('usage: node shoot.mjs <story-id> [width] [height] [out.png]');
+  process.exit(1);
+}
+
+const browser = await chromium.launch();
+const page = await browser.newPage({
+  viewport: { width: Number(width), height: Number(height) },
+  deviceScaleFactor: 2,
+});
+
+await page.goto(`${BASE}/iframe.html?id=${id}&viewMode=story`, { waitUntil: 'domcontentloaded' });
+await page.waitForSelector('#storybook-root > *', { timeout: 15000 });
+
+const overlays = await page.locator('#webpack-dev-server-client-overlay, vite-error-overlay').count();
+if (overlays > 0) {
+  console.error('compile error overlay is present - the image would lie');
+  await browser.close();
+  process.exit(1);
+}
+
+if (FORCED.length > 0) {
+  const cdp = await page.context().newCDPSession(page);
+  await cdp.send('DOM.enable');
+  await cdp.send('CSS.enable');
+  const { root } = await cdp.send('DOM.getDocument', { depth: -1 });
+
+  for (const { selector, states } of FORCED) {
+    const { nodeIds } = await cdp.send('DOM.querySelectorAll', { nodeId: root.nodeId, selector });
+    for (const nodeId of nodeIds) {
+      await cdp.send('CSS.forcePseudoState', { nodeId, forcedPseudoClasses: states });
+    }
+  }
+}
+
+await page.waitForTimeout(400);
+await page.screenshot({ path: out });
+await browser.close();
+
+console.log(out);

package/content/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily: only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording _that_ a decision was made and _why_, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/content/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md): receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/content/skills/domain-modeling/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
+kind: skill
+scope: both
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the _active_ discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely _reading_ `CONTEXT.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily: only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account': do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up: capture them as they happen. Use the format in {%resource:CONTEXT-FORMAT.md%}.
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in {%resource:ADR-FORMAT.md%}.
+
+---
+
+Vendored from [mattpocock/skills](https://github.com/mattpocock/skills) at `3cca18b`, MIT (Copyright (c) 2026 Matt Pocock).