docs: add errors-use-error-notice frontend review rule

[CrysisDeu]

Problem / Motivation

The dashboard has one shared error surface, ErrorNotice, that renders an error and offers to hand it to the agent with the full structured context (route, failed endpoint, HTTP status, backend code). Nothing requires anyone to use it. Roughly 100 sites still render an error as a hand-written <div className="text-danger">{err}</div>, and new ones keep landing, because no review rule names the component or the askAgent decision.

Why it matters

This is an AI agent app: an error the user cannot fix themselves is usually one the agent can, so every hand-written red div is a dead end that throws away the context the agent would need. It also re-implements the visual (icon, role="alert", tokens, dismiss) slightly differently each time. The hand-off is also destructive (it navigates away and unmounts the tree, destroying unsaved local state), so the askAgent choice has to be made deliberately per surface — and today a reviewer cannot tell "protected a draft" from "forgot the prop".

What changed (motivation → approach → change)

Goal: make "render errors through ErrorNotice, decide askAgent explicitly" a review-enforced rule rather than tribal knowledge.

Approach: a blocking: true rule in website/AUTOSDE.yaml, which is what the GPT and Opus review lanes load from the base ref, plus a one-bullet pointer in website/AGENTS.md's "Rules that must not wait for a pointer" list so agents see it before writing code. No CI script — the error-vs-validation split and the "does this subtree hold a draft" question are semantic, so this belongs to the AI lanes, not a grep gate.

The rule (errors-use-error-notice):

• Every user-facing error (a rejected request, a caught exception, a useQuery/useMutation error, a backend { error, code } body, a job's last_error, a boundary fallback) renders through ErrorNotice; classification is by where the value comes from, not how it is rendered. Validation hints, empty states and warnings are out of scope.
• The author must turn askAgent on where nothing unsaved can be lost, and must leave it off next to an unsaved draft with a {/* No hand-off: … */} comment naming the draft (the form already used in RemoteCrewPanel.tsx). onHandoff lets a dialog close itself but does not make the navigation safe.
• The reviewer blocks on the hand-written surface and on the missing decision (an added/touched ErrorNotice with neither askAgent nor a No hand-off comment) — never on the direction of the decision, since whether a subtree holds unsaved state is not visible in a hunk and a wrong demand would cause exactly the data loss the prop's default prevents.
• Applies to what a diff adds or touches. Existing sites are grandfathered until edited; this is deliberately stricter than max-two-buttons-per-row's growth-only grandfather because the migration is one line and growth-only would leave the backlog a dead end forever.
• Does not flag ErrorBoundary/MessageErrorBoundary fallbacks (they mount AskAgentButton directly), chat-transcript ErrorCard rows (the agent is already in that conversation), or useNotify(..., { type: 'error' }) toasts — but a toast as the only report of a failure that leaves the user in a failed state is a violation, because the app-sdk seam carries only message + type and cannot host the hand-off.

Local adversarial review (GPT and Opus lanes mirrored locally, then one verifier): 0 blocking, 5 advisory findings, all fixed in this commit — the reviewer bright line moved to "missing decision", the onHandoff clause no longer counts as enabled over a draft, the toast exception was corrected against the real useNotify signature, the stricter grandfather is stated with its reason, and error classification is anchored on the value's source.

Tests

N/A — the diff is a review rule (YAML) and a doc bullet (markdown); no runtime code path. The YAML was parsed (custom-rules still loads, 14 rules, the new one blocking: true on src/**/*.tsx), and the diff-scoped gates (check_brand_name.py, docs-lint.sh, scrub-lint.sh, check_focus_cue.py, check_harness_parity.py, check_changelog_history.py) exit 0.

Manual verification

Every factual claim the rule makes about the codebase was checked against the source: ErrorNotice.askAgent defaults to false; RemoteCrewPanel.tsx carries the No hand-off comment form; App.tsx mounts AskAgentButton with onHandoff; chat role: 'error' rows render through ErrorCard; useNotify takes (message, { type }) only.

Related Issues

no linked issue: the rule was requested directly, not tracked in an issue.

Checklist

• At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
• Existing tests pass and new tests added for new functionality
• Self-review completed; code follows project style guidelines
• Documentation updated (if applicable)
• No secrets, credentials, or internal references in the diff

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 2d5d586f55c4dcc61300daa77ea65a7668bf6c39 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2d5d586

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2d5d586f55c4dcc61300daa77ea65a7668bf6c39: <one-sentence reason>

[github-actions]

UX Review (Fable 5) — ✅ PASS

UX-level review of 2d5d586f55c4dcc61300daa77ea65a7668bf6c39 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Docs-and-review-rule-only change — no rendered UI, strings, or flows are touched; nothing a user experiences differs.

[UX-REVIEWED] 2d5d586

[github-actions]

Design Review (Fable 5) — ✅ PASS

Design-level review of 2d5d586f55c4dcc61300daa77ea65a7668bf6c39 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Codifies an already-proven pattern; every referenced artifact (component, prop default, comment convention, exemplar sites) exists and matches the rule's claims.

Suggestions

• The toast carve-out's violation condition ("a toast as the ONLY report") needs whole-page visibility a hunk doesn't give — the same limitation the rule itself names for unsaved state. Scope it the same way ("raise in a thread, don't block") so the blocking rule stays decidable from the diff.

[DESIGN-REVIEWED] 2d5d586

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed 2d5d586f55c4dcc61300daa77ea65a7668bf6c39 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 2d5d586

Verdict parsed from the review's SHA-scoped output markers for commit 2d5d586f55c4dcc61300daa77ea65a7668bf6c39.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 2d5d586f55c4dcc61300daa77ea65a7668bf6c39: <one-sentence reason>

[CrysisDeu]

Status note — the remaining red is infrastructure, not this diff.

Dependency Audit / Audit Production Dependencies has failed three times on head db6251900 with the same message: npm audit timed out after 120s for website/package-lock.json. This PR changes only website/AUTOSDE.yaml and website/AGENTS.md (no lockfile, no dependency). The same failure is currently hitting other open PRs (#8341, #8340, #8335 at the time of writing), so it is npm registry advisory latency on the runners. Everything else is green: GPT 5.6 and Opus 4.8 both stamped this head with no findings, UX and Design PASS, First Principles green.

I will re-run the audit job once the registry recovers (another PR's audit going green is the signal) rather than retrying every few minutes.

[bolichen97]

Approving — docs + AI-reviewer config only, no runtime impact.

Scope check: website/AGENTS.md prose plus one appended entry in AUTOSDE.yaml custom-rules. 99 additions, 0 deletions. No workflow, CODEOWNERS, or branch-protection change, and no existing rule blocking flag, file-patterns, or text is modified — this only adds strictness for the AutoSDE reviewer, it relaxes nothing.

Verified the rule matches the code it governs: src/components/ErrorNotice.tsx exposes variant and askAgent (defaulting false, with the data-loss rationale the rule quotes).

Follow-up nit (not blocking): the onHandoff bullet reads as an ErrorNotice prop, but ErrorNotice has no onHandoff — it is an AskAgentButton prop. Worth one clarifying clause in a later pass.

Verdict: MERGE_WITH_FOLLOWUP.