Skip to content

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.md
index 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.md
index 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 them
against 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 should
demonstrate the bug first (a failing test, a reproduction, or another
diff --git a/.github/instructions/templates.instructions.md b/.github/instructions/templates.instructions.md
index 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/Contributing
that would land below B; post findings as a scorecard (advisory — comment, don't
hard-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