An open source design system that's fully customizable and agent ready
TypeScript
docs: add triage-first step (categorize, assess risk incl. breaking changes, pick review path) to reviewers (#3806)
Cindy Zhang3eef81ecaa2e
diff --git a/.github/instructions/docsite.instructions.md b/.github/instructions/docsite.instructions.mdindex b3d573fb65..9614b8c8c0 100644--- a/.github/instructions/docsite.instructions.md+++ b/.github/instructions/docsite.instructions.md@@ -9,6 +9,21 @@ Its defining constraint is **how it handles data** — review against[`apps/docsite/README.md`](../../apps/docsite/README.md), specifically the"How It Works" and "The Rule" sections.+## Step 0 — Triage first++Fast triage before depth. The docsite ships app code (not published packages),+so consumer-breaking API changes aren't the concern — **blast radius** is:++- **Shared component / util** (e.g. a `components/blog/BlogCard`, a shared layout)+ → higher stakes: a change ripples across pages. Check every call site, and+ that a new prop is **optional** (additive) so existing usages don't break.+- **Single page / one-off** → lower stakes, contained.++Then pick depth: **fast path** for a contained single-page or copy tweak (verify+the data rule + accuracy, approve); **standard path** for a shared-component or+layout/structural change (full data-rule + idiomatic + mobile review below).+State it briefly, e.g. `Triage: shared BlogCard, additive optional prop → standard`.+## The data rule (primary review focus)**All data comes from the build-time pipeline. Never hardcode package names,diff --git a/.github/instructions/packages.instructions.md b/.github/instructions/packages.instructions.mdindex 3fbff9bc98..44e3796090 100644--- a/.github/instructions/packages.instructions.md+++ b/.github/instructions/packages.instructions.md@@ -7,9 +7,59 @@ applyTo: "packages/**"These paths ship as published `@astryxdesign/*` packages, so review themagainst Astryx's API guidance and component review protocol.+## Step 0 — Triage first: categorize, assess risk, pick a path++Before reviewing in depth, do a fast triage. It decides *how hard* to look and+in what order, so effort lands where the risk is — and so the risk checks+(especially breaking changes) happen **up front**, not as an afterthought.++**1. Categorize the PR** (by what it changes, not just the title prefix):++| Category | Signals |+|---|---|+| **test / docs / chore** | only `*.test.tsx`, `*.doc.mjs`, stories, CI, build config — no shipped runtime/API change |+| **bug fix** | behavior change to existing code, no new public surface |+| **new API surface** | new component, new prop/variant, new exported hook/type, changed signature |+| **refactor / internal** | behavior-preserving restructure, shared-util migration |++**2. Assess risk — the two questions that gate everything:**++- **Is it a breaking change?** Scan for: a removed/renamed public export, prop,+ or variant; a **new required** field on a public type/context/props; a changed+ default; a changed function signature; or changed DOM/class/ARIA output+ consumers may depend on. (The tell for an *accidental* breaking change:+ unrelated tests/examples/call sites had to be edited — see the silent-breaking+ rule in Judgment.) A real breaking change must be **intentional and signalled+ with a `[breaking]` changeset category** (pre-1.0 stays a `patch` bump — never+ ask for `minor`/`major`; the category is the signal), and for a+ removed/renamed/changed public API, a **codemod** under `astryx upgrade`.+ Flag a breaking change with no `[breaking]` changeset (and no codemod where one+ is warranted) as blocking.+- **What's the blast radius?** A core primitive many components build on, or a+ shared type/context, is higher-stakes than a leaf component or a docsite tweak.++**3. Pick the review path** (depth follows category × risk):++- **Fast path** — test/docs/chore, or a small behavior-only bug fix with a+ regression test, no breaking change, low blast radius. Verify accuracy (does+ the referenced API exist / does the fix match the described bug), confirm the+ test/changeset, and approve. Don't manufacture findings on a clean small PR.+- **Standard path** — a normal bug fix or a contained prop/behavior change. Run+ the full Mechanical checklist + convergence + Judgment below.+- **Deep path** — new API surface, a breaking change, a plugin/hook that extends+ a host, or a high-blast-radius core change. Do the full review **and** route+ the API-design decision to a human (see "When to flag for engineering / human+ judgment"); note it should be spec'd + vibe-tested. Do not verdict the API+ yourself.++State the category, the risk (breaking? blast radius?), and the chosen path at+the top of the review, e.g. `Triage: bug fix · non-breaking · low blast radius →+fast path`. This makes the depth of review legible and ensures the+breaking-change question is answered on every PR.+## Calibrate to the PR type-Weight the review by what the PR is trying to do:+Once triaged, weight the review by what the PR is trying to do:- **Bug fixes** — require **evidence in the description**. A fix shoulddemonstrate the bug first (a failing test, a reproduction, or anotherdiff --git a/.github/instructions/templates.instructions.md b/.github/instructions/templates.instructions.mdindex da4330f6d6..da06103c04 100644--- a/.github/instructions/templates.instructions.md+++ b/.github/instructions/templates.instructions.md@@ -22,6 +22,19 @@ in [Contributing Templates](https://github.com/facebook/astryx/wiki/Contributingthat would land below B; post findings as a scorecard (advisory — comment, don'thard-block).+## Step 0 — Triage first++Quick triage before grading. Two questions:++- **New template vs. edit to an existing one?** A *new* template that lands+ already-visible (its `.doc.mjs` isn't `hidden: true`) skipped hidden-staging —+ flag it (see Lifecycle note) and hold it to the full B+ bar. An edit to an+ existing template is scoped to what changed.+- **Content-only vs. structural?** A copy/mock-data tweak is a fast grade+ (purity + metadata); a layout/root/`AppShell` change needs the full Layout &+ Structure pass. State it briefly, e.g. `Triage: edit to existing template,+ layout change → full structure pass`.+## Score the 7 categories (100 pts)1. **Astryx component purity (30)** — count JSX tags; every raw lowercase HTML