root-cause-remediation
Mandatory for every Nomi corrective change: user-reported bugs, regressions, CI-only failures, flaky tests, performance or security defects, review/audit findings, and compatibility failures in any production path. Classify one_off versus recurring before implementation. Recurring and high-risk repairs require a schema-v3 contract, shared enforcement boundary, structural prevention, dependency lifecycle decision, and changed regression evidence.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 651
- Forks
- 143
01 前言 Front Matter
- name
- root-cause-remediation
- description
- Mandatory for every Nomi corrective change: user-reported bugs, regressions, CI-only failures, flaky tests, performance or security defects, review/audit findings, and compatibility failures in any production path. Classify one_off versus recurring before implementation. Recurring and high-risk repairs require a schema-v3 contract, shared enforcement boundary, structural prevention, dependency lifecycle decision, and changed regression evidence.
02 资源文件 2
- 参考文档evals/evals.json2.2 KB
- 参考文档references/contract-v3.template.json4.0 KB
03 SKILL.md 正文
Root Cause Remediation
Mission
Act as an investigator and system owner, not a patch author. Restore the missing invariant at the earliest shared boundary so the reported failure and every equivalent entry fail safely or succeed consistently. A green example is not success if another vendor, version, caller, platform, or stored value can reproduce the same class.
This skill is the detailed operating source for P2/R21. CLAUDE.md and generated AGENTS.md only carry the trigger; scripts/root-cause-contracts.mjs is the merge-time enforcement authority.
Success Bar
A remediation is complete only when evidence connects all of these:
- the exact user-visible symptom and deterministic reproduction;
- the direct mechanism that failed;
- the class-wide missing invariant;
- every equivalent entry point found by repository search;
- one or more shared boundaries that enforce the invariant without exceptions;
- changed tests for both the reported case and the class boundary;
- removal or explicit non-applicability of obsolete paths;
- an explicit dependency upgrade/retention decision with exit criteria when a third-party runtime is involved;
- verification on the platform or build boundary that originally exposed the defect.
Required Workflow
- Reproduce the symptom with the smallest deterministic fixture. Preserve the failing output before editing production code.
- Trace the complete path from user input through parsing, state/persistence, shared services, and the final request/write/decode boundary.
- Separate
symptom,direct_cause, andclass_root. The class root is the missing invariant that explains why equivalent inputs or callers can fail, not the line that happened to throw. - Classify recurrence before implementation:
one_offrequires repository-wide evidence that no other user, input, entry, machine, or future run can reach the mechanism and no reusable invariant can prevent it; observed once is not evidence. Otherwise classifyrecurring. 4a. Before first proposing a solution, and again when changing it, check this object’s past decisions and deletion records (docs/design/,git log --grep, and known facts supplied by the coordinator); verify the original wording and whether it still applies. State the user outcome to preserve, then compare fixing in the current direction, taking a different approach (changing modes or adopting an existing solution), and deleting it. Choose from the facts; writeunknownwhere evidence is missing. For a small matter with an already clear fix, one sentence is enough. - Count the doors before choosing where to fix. Run
node scripts/door-map.mjs <mutator symbol or file>to enumerate every write and read entry point of the state whose invariant broke, and paste the output into the contract'sdoors. A door map you typed by hand is the same thing as the sentence "I checked"; the script is the check. The tool counts direct call sites only, so follow one more hop when a door is reached through a wrapper. If the fix changes what a shared read face returns (filtering, hiding, reshaping), enumerate every reader of it — includingtests/uxwalkthroughs and scripts that call it throughwindow.nomiDesktop— and check each reader's expectation before shipping; 改了读面返回什么,就把它的全部读者(含走查)逐个核一遍 (2026-10-22: hiding blank drafts in the project list broke golden path and real-user-journeys, which find a just-created project throughlistAsync). - Search the repository by data shape, contract, producer, and consumer. Record at least two independently checked same-class entry points; do not search only for the reported provider, version, model, or fixture name. 这一步是修缺陷用的;任务是删掉某个东西时,范围按归属定(它属于谁的目录、声明、夹具、测试),全仓搜索只用来最后核对剩下什么,不用来决定删什么。
- Identify the earliest shared boundary that can own the invariant. If callers do not converge, first consolidate ownership or define multiple explicit shared boundaries.
- For third-party behavior, inspect current official documentation, source, installed versions, and platform/package drift. Choose
upgrade-now,retain-with-exit, ornot-applicable; retention requires a target and testable exit criteria. - Read
references/contract-v3.template.json, then create or update a schema-v3docs/fixes/*.root-cause.jsonbefore a recurring or high-risk production fix. Preserve the template's exact field names, object shapes, and enums; every changed high-risk production file must be covered byscope_paths. - Add the failing reported-case test and at least one class-level test. Run only this red slice before implementation. 门岗反例夹具只截取本次相关片段;不要把整份旧规则 / 旧文件复制进夹具。先证明夹具会红,按字节还原后再证明回绿。
- For recurring repairs, enforce the invariant at the shared boundary and list changed structural code in
prevention.artifacts. Delete obsolete behavior in the same change; tests, documentation, and fallback paths are not structural prevention. - Run the changed class tests and
pnpm run check:root-cause-contracts. After the logical batch is stable, run the risk-selected repository validation once.
Decision Rules
- Prefer schema/type/parser/normalization/persistence boundaries over caller-side conditionals.
- A platform or dependency version may explain the symptom, but it is not automatically the class root. Bind the application-level contract explicitly, then decide whether the dependency also needs an upgrade.
- Upgrade now when a supported target-aware package can replace the old runtime without weakening packaging, security, or cross-architecture guarantees.
- Retain with exit only when an application invariant safely spans current versions and the upgrade has concrete prerequisites, owner paths, and verification criteria.
- If migration cannot distinguish legacy user-authored behavior from generated behavior, fail visibly or require explicit regeneration; do not guess and silently rewrite.
- If the same class truly has one technical caller, enumerate different input populations or downstream consumers. A one-example scan does not establish generality.
Forbidden Patch Shapes
- A vendor/model/version/platform branch when a shared role, type, schema, byte, lifecycle, or persistence boundary can own the rule.
- Swallowing an error, broadening a regex, increasing a timeout/retry count, or weakening validation without proving the underlying invariant.
- Changing only the failing fixture or mocking away the production boundary.
- Adding a new path while leaving the old path callable as a fallback.
- Calling a dependency old but neither upgrading it nor recording a target-aware exit plan.
- Listing vague entry points, nonexistent paths, unchanged tests, or prose that cannot be tied back to code.
Contract v3 Review
Before implementation, confirm the contract contains:
generality_proofexplaining why the solution spans the class;shared_boundarieswith real path, symbol, and responsibility;doors: every write and read entry point of the affected state, generated byscripts/door-map.mjs, each{kind, path, symbol}— the door's identity is file + symbol, never a line number (line numbers drift on unrelated edits and produced a whole family of no-op "keep the line numbers current" commits);door_reduction:{before, after}whereafterequalsdoors.length; when two or more doors survive unchanged,why_notmust say why each entry has to exist;same_class_entry_pointswith path, entry, disposition, and evidence;recurrencewithone_off/recurring, reason, and concrete repository scan evidence;- recurring
preventionwith a supported mechanism, shared enforcement path, invariant, fail behavior, no exception policy, strategy, and changed structural artifacts; class_regression_teststhat are also changedregression_tests;legacy_pathsasremovedor justifiednot-applicable;dependency_lifecycleasnot-applicable,upgrade-now, orretain-with-exit.
The exact machine contract is references/contract-v3.template.json. In particular, use same_class_entry_points[].entry_point, disposition enforced or not-affected, the exact recurrence and prevention keys, and an object-shaped legacy_paths; do not paraphrase schema keys in a contract outline. prevention.kind is one of centralized-boundary, schema-validation, type-system, runtime-assertion, static-gate, migration, or dependency-upgrade. Each external source is {kind: official-doc|source-code, url, checked_at: YYYY-MM-DD, purpose}; otherwise use a truthful internal_only_reason. Run the checker immediately after drafting so field-shape errors are resolved before production work.
Schema v1 and v2 contracts are immutable history. Any modification must migrate that contract to v3; new legacy contracts fail CI.
Final Review
Do not call the issue solved until every answer has code or test evidence:
- Can the same class still enter through another caller, provider, version, platform, or old stored value? Answer from the door map, not from memory.
- Does every equivalent entry converge on a declared enforcement boundary?
- Does the boundary fail closed without a compatibility exception or fallback?
- Did the reported case fail before the fix and pass after it? For a user-reported problem this means replaying the user's own flow under the same real conditions (what counts as real depends on the problem, for example a real model for generation, real old-version data for an upgrade): complete, with every difference from the user's run named, the same symptom seen before the fix and the same steps passing after it. Derive what to cover from the user's flow and the door map, not from a fixed list (
docs/engineering-rules.mdR13). Record it in the PR's## 真实场景复现; a fake-provider walk alone does not count, and missing resources are written as未验证:原因. - Does a separate class-level test prove the invariant rather than the example?
- Are dependency and migration decisions explicit, bounded, and testable?
Unknowns belong in residual_risks; they are not permission to claim completion.
Reference
references/contract-v3.template.json- exact schema-v3 authoring template; always read it before drafting a contract.
04 同仓库更多 Skills
my-skill
What this skill does
video-gen
AI video generation via Seedance, Kling, Gemini Omni, MiniMax H3, and MiniMax H3 Max. Use when the user wants to generate a video clip — text-to-video, image-to-video, first/last-frame transitions, reference-guided generation — or wants to modify / edit / extend an existing generated clip.
writer-style-schrader
保罗·施拉德(Paul Schrader,《出租车司机》编剧、《美国舞男》《第一归正会》导演)的叙事风格——超验电影式的极简、克制与蓄压,写孤独主角在平庸日常里被侵蚀、由偶遇而非选择推向转折,意义在"一切照旧"中悄然位移。适用于都市孤独、边缘人物、慢节奏内心戏、生活流的现实题材。Nomi 创作区想要这种冷峻克制、不解释情绪、靠并置而非因果说话的剧本质感时套用。
writer-structure
结构师(John Truby 方法论)——故事有机结构设计 / 对手网络构建 / 场景编织 / 节奏控制 / 钩子编排。Nomi 创作区搭故事骨架时参考。
writer-songfangjin
宋方金编剧方法论(中国编剧《手机》《给青年编剧的信》)——人物先于情节 / 生活质感 / 关系即戏剧 / 对白零废话。Nomi 创作区写剧本时参考,尤其中式现实题材。
writer-screenwriter
专业编剧(Lawrence Kasdan《星战》《肖申克》× Tony Gilroy《谍影重重》方法论)——故事结构/场景写作/对白/质量审查,含格式变体(长片/剧集/短片/超短)与严肃叙事风格。Nomi 创作区写剧本时参考。