failure-resilience

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

failure-resilience

failure-resilience

Demo data and a fast laptop hide the states real users meet on day one: slow networks, empty accounts, failed requests, expired sessions. AI-built UIs usually implement only the happy path.
演示数据和一台运行速度很快的笔记本电脑会掩盖真实用户第一天就会遇到的情况:网络缓慢、账户为空、请求失败、会话过期。AI 构建的 UI 通常只实现 happy path。

Activate when

何时启用

  • The UI fetches data, submits actions, uses auth, uploads files, or renders lists/results that can be empty.
  • Reviewing before launch or after users report blank screens or "stuck" pages.
  • Not for fully static sites with no interactive data (say so).
  • UI 获取数据、提交操作、使用 auth、上传文件,或渲染可能为空的列表或结果。
  • 上线前审查,或用户报告白屏或页面“卡住”之后。
  • 不适用于完全没有交互式数据的静态站点(需明确说明这一点)。

Working alone

独立工作

This skill is self-contained. Its companions (declared in its metadata) are skills whose method it may need to do its own promised work. Use of a companion can be conditional: declaring one does not mean running it. When a companion's lane applies, use the skill if it is installed; if not, follow its short entry in references/companion-methods.md and say in your report which lanes ran inline at reduced depth. Never skip an applicable lane silently. Skills mentioned here only for escalation, referral, documentation, or optional deeper follow-up are not dependencies: report the hand-off and finish honestly.
Companions:
design-system-reconnaissance
.
此 skill 是自包含的。它的 companions(在 metadata 中声明)是指其方法可能需要借助来完成自身所承诺工作的其他 skill。使用 companion 可以是有条件的:声明 companion 并不表示一定会运行它。当某个 companion 的 lane 适用时,如果该 skill 已安装,请使用它;如果未安装,则遵循 references/companion-methods.md 中的简短条目操作,并在报告中说明哪些 lane 以降低深度 inline 执行。绝不能静默跳过任何适用的 lane。此处仅用于升级(escalation)、转交(referral)、文档记录(documentation)或可选的深入后续工作(follow-up)而提及的 skill 并非依赖:应报告交接(hand-off)情况并如实完成。
Companions:
design-system-reconnaissance
。

Inspect

检查

1. Enumerate the data-dependent views and actions from routes and components: lists, dashboards, detail pages, search, forms, uploads, payments, auth transitions.
2. For each, the five states:
StateWhat good looks like
LoadingImmediate, proportionate feedback (skeleton/spinner) with layout that does not jump; slow (>~3s) loading tells the user something; never a spinner that can outlive a failed request
EmptyExplains what would be here and offers the next action ("No invoices yet. Create your first."); not a blank area or a raw
[]
or
undefined
SuccessConfirms what happened; next step; state updated
ErrorHuman-readable message, what happened, what to do; retry; input preserved; no raw stack/JSON/HTTP codes; no red-screen crash
RecoveryRetry works; expired session prompts sign-in and returns the user; offline/timeout handled; double-click does not double-act
3. Force the failures (local/staging only). The runtime helper can fail, slow, and cut the network (paths relative to this skill's folder):
bash
node scripts/observe-runtime.mjs --url <site> --fail "**/api/items=500"            # server error
node scripts/observe-runtime.mjs --url <site> --fail "**/api/items=abort"          # network failure
node scripts/observe-runtime.mjs --url <site> --fail "**/api/items=401" --steps s.json   # expired session
node scripts/observe-runtime.mjs --url <site> --delay "**/api/items=6000" --screenshots ./shots --steps s.json
Steps can
click
,
reload
,
screenshot
, and
{"do":"offline","on":true}
to lose the network mid-flow. Screenshots let you see the loading, empty, and error states;
REQUEST_FAILURES
and
CONSOLE_ERRORS
show what the page logged. Also try an empty list (serve
[]
) by pointing at a staging backend or a stub. Watch for: spinner forever; blank white screen; console errors with no UI; success toast after a failed request; data disappearing; infinite retry loops.
4. Code patterns:
try/catch
that only
console.log
s;
.catch(() => {})
; loading flags never reset in
finally
; missing error boundaries (React) or
error.tsx
/
+error.svelte
; optional chaining hiding
undefined
renders;
Suspense
without fallback; unhandled promise rejections; lists rendering
.map
on possibly-undefined data.
5. Auth and session transitions: expired token mid-action; logged-out user hits a private URL (redirect vs error); post-login return path.
6. Error copy honesty: no fake success, no "Something went wrong" with no route forward when a retry or support link is available.
**1. 从路由和组件中枚举依赖数据的视图与操作:**列表、仪表板、详情页、搜索、表单、上传、支付、auth 状态转换。
2. 对每一个视图和操作检查五种状态:
状态良好表现
Loading(加载)立即、适度的反馈(skeleton/spinner),且布局不发生跳动;加载较慢(>~3s)时告知用户发生了什么;绝不让 spinner 在请求失败后仍无限持续
Empty(空)说明这里本应显示什么,并提供下一步操作(“还没有发票。创建第一张。”);不能只是空白区域或原始的
[]
或
undefined
Success(成功)确认发生了什么;给出下一步;更新状态
Error(错误)显示人类可读的消息,说明发生了什么以及用户该做什么;允许重试;保留输入;不显示原始 stack/JSON/HTTP code;不出现整屏红色崩溃页面
Recovery(恢复)重试有效;会话过期时提示登录并在登录后让用户返回;处理离线或超时;防止双击导致重复操作
3. 强制触发故障(仅限 local/staging)。运行时 helper 可以制造失败、延迟并切断网络(路径相对于此 skill 所在文件夹):
bash
node scripts/observe-runtime.mjs --url <site> --fail "**/api/items=500"            # server error
node scripts/observe-runtime.mjs --url <site> --fail "**/api/items=abort"          # network failure
node scripts/observe-runtime.mjs --url <site> --fail "**/api/items=401" --steps s.json   # expired session
node scripts/observe-runtime.mjs --url <site> --delay "**/api/items=6000" --screenshots ./shots --steps s.json
步骤可以执行
click
、
reload
、
screenshot
,以及
{"do":"offline","on":true}
,从而在流程中途断开网络。截图可以让你看到加载、空和错误状态;
REQUEST_FAILURES
和
CONSOLE_ERRORS
会显示页面记录的内容。还可以让 staging 后端或 stub 返回
[]
,以尝试空列表。注意观察:spinner 永远不结束;空白白屏;只有 console error 而没有 UI;请求失败后却显示成功 toast;数据消失;无限重试循环。
**4. 代码模式:**仅执行
console.log
的
try/catch
;
.catch(() => {})
;loading flag 从未在
finally
中重置;缺少 error boundary(React)或
error.tsx
/
+error.svelte
;optional chaining 隐藏了
undefined
渲染;
Suspense
没有 fallback;未处理的 Promise rejection;列表在可能为 undefined 的数据上调用
.map
。
**5. Auth 与 session 转换:**操作过程中 token 过期;已退出用户访问私有 URL(重定向还是报错);登录后的返回路径。
**6. 错误文案必须诚实:**不能伪造成功,也不能只显示“出了点问题”,在明明可以重试或提供支持链接时却不给出继续处理的路径。

Evidence that counts

有效证据

Label each claim OBSERVED, SOURCE-INDICATED, DECLARED, INFERRED, UNKNOWN, or REVIEW REQUIRED. UNKNOWN is never a pass and never a failure.
  • A state forced at runtime and seen: OBSERVED. A state handler in code: SOURCE-INDICATED.
  • If a backend cannot be failed safely, mark those paths UNVERIFIED with what would be needed.
为每项结论标注 OBSERVED、SOURCE-INDICATED、DECLARED、INFERRED、UNKNOWN 或 REVIEW REQUIRED。UNKNOWN 既不算通过,也不算失败。
  • 在运行时强制触发并实际看到的状态:OBSERVED。代码中存在相应状态处理:SOURCE-INDICATED。
  • 如果无法安全地让后端发生故障,则将这些路径标为 UNVERIFIED,并说明需要什么条件才能验证。

May change

可以更改的内容

Design first. Before creating or changing anything visible, inspect the project's existing design system (
design-system-reconnaissance
) and build from its tokens and components, by the component ladder: reuse, compose, extend, and only then create a matching component. Never impose a ReadyVibe look on the user's site.
Add or fix loading, empty, error, and success states in the existing design system; add
finally
resets; add error boundaries and route-level error pages; preserve form input on failure; add retry affordances; add timeouts where the pattern exists. Do not add global fake success, hide errors, or over-engineer retry/backoff frameworks.
**先做设计。**在创建或更改任何可见内容之前,先检查项目现有的设计系统(
design-system-reconnaissance
),并基于其 token 和组件进行构建,按 component 层级依次执行:复用、组合、扩展,最后才创建风格匹配的组件。绝不能把 ReadyVibe 的视觉风格强加到用户的站点上。
在现有设计系统中添加或修复 loading、empty、error 和 success 状态;添加
finally
重置;添加 error boundary 和路由级错误页面;失败时保留表单输入;添加重试入口;在已有相应模式的地方添加 timeout。不要添加全局性的虚假成功、隐藏错误,或过度设计 retry/backoff 框架。

Must not claim

不得声称

"Resilient", "handles all failures", or "production-ready error handling". State which failure classes you forced.
不得声称“具备韧性(Resilient)”“处理所有故障(handles all failures)”或“生产就绪的错误处理(production-ready error handling)”。应说明你强制触发了哪些故障类别。

Verify

验证

Repeat each forced failure after changes: the UI shows a clear message, offers recovery, recovers when the failure ends, and nothing logs uncaught errors. Confirm the happy path still works.
更改后重复触发每一种强制故障:UI 应显示清晰消息、提供恢复方式,并在故障结束后恢复正常,同时不应记录任何 uncaught error。确认 happy path 仍然正常工作。

Escalate

升级处理

Payment or auth flows whose failure states you cannot test safely; data-loss risks (unsaved work on error); offline-first expectations (a product decision).
无法安全测试的 payment 或 auth 流程;data loss 风险(出错时未保存的工作);offline-first 预期(属于 product decision)。

No change is valid when

无需更改的情况

Views already handle the five states, or the site has no data-dependent UI. Do not add skeletons to a static page.
当视图已经处理这五种状态,或站点没有依赖数据的 UI 时,无需更改同样有效。不要给静态页面添加 skeleton。