design-invariants

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Invariants Skill

Design Invariants 技能

Audits a design proposal or diff against Exarchos-specific architectural invariants. Project-scoped — these invariants govern Exarchos itself, not consumers of the Exarchos plugin.

The skill is the operational complement to issue #1118 (codify principles) and #1109 (cross-cutting constraints). Reference content is also a candidate to back the v2.11.0 #1275 (MCP Resources) surface and the #1260 machine-readable invariants generator — every invariant carries a stable ID and structured shape.

对照Exarchos专属的架构不变量审核设计提案或代码差异。本技能为项目专属范围——这些不变量管控Exarchos本身，而非Exarchos插件的使用者。

本技能是Issue #1118（规范化原则）和Issue #1109（跨领域约束）的操作层面补充。参考内容也可作为v2.11.0版本中#1275（MCP资源）界面和#1260机器可读不变量生成器的支撑——每个不变量都带有稳定ID和结构化格式。

When to use

使用场景

During
```
/exarchos:ideate
```
or
```
/exarchos:plan
```
, before committing a design.
During
```
/exarchos:review
```
, alongside
```
/axiom:audit
```
.
When reviewing a PR that touches the event store, MCP surface, runtime YAML, or composite tool registry.

在
```
/exarchos:ideate
```
或
```
/exarchos:plan
```
阶段，提交设计方案前使用。
在
```
/exarchos:review
```
阶段，与
```
/axiom:audit
```
搭配使用。
当评审涉及事件存储、MCP界面、运行时YAML或复合工具注册表的PR时使用。

When NOT to use

禁用场景

For generic backend quality — use
```
/axiom:*
```
skills (see complementarity matrix below).
For TDD / spec compliance — use
```
/exarchos:review
```
or the
```
spec-review
```
skill.
For prose / AI-writing tells — use
```
/axiom:humanize
```
.

通用后端质量审核——使用
```
/axiom:*
```
系列技能（见下方互补矩阵）。
TDD/规范合规性检查——使用
```
/exarchos:review
```
或
```
spec-review
```
技能。
文案/AI写作风格优化——使用
```
/axiom:humanize
```
。

How to invoke

调用方式

State the artifact under review (design path, diff range, or PR URL).
Walk INV-1..INV-5 in order, recording HIGH/MEDIUM/LOW findings per invariant.
For INV-5, walk all four sub-disciplines (5a input ergonomics, 5b output contract, 5c Aspire verbs, 5d action discriminator).
Cross-link any axiom finding that overlaps (e.g., a topology issue under INV-1 may also be DIM-1).
Output the same finding format as axiom (severity + dimension + file:line + description + required_fix).

说明待评审的工件（设计路径、代码差异范围或PR链接）。
按顺序检查INV-1至INV-5，记录每个不变量对应的高/中/低风险发现。
针对INV-5，需覆盖全部四个子领域（5a 输入人机工程学、5b 输出契约、5c Aspire动词、5d 动作鉴别器）。
交叉链接所有重叠的axiom发现（例如，INV-1下的拓扑问题可能同时属于DIM-1）。
输出与axiom一致的发现格式（风险等级 + 维度 + 文件:行号 + 描述 + 修复要求）。

Invariant references

不变量参考

INV-1 → references/INV-1-event-sourcing.md
INV-2 → references/INV-2-facade-equivalence.md
INV-3 → references/INV-3-basileus-forward.md
INV-4 → references/INV-4-platform-agnosticity.md
INV-5a → references/INV-5a-input-ergonomics.md
INV-5b → references/INV-5b-output-contract.md
INV-5c → references/INV-5c-aspire-verbs.md
INV-5d → references/INV-5d-action-discriminator.md
Deterministic checks → references/deterministic-checks.md

INV-1 → references/INV-1-event-sourcing.md
INV-2 → references/INV-2-facade-equivalence.md
INV-3 → references/INV-3-basileus-forward.md
INV-4 → references/INV-4-platform-agnosticity.md
INV-5a → references/INV-5a-input-ergonomics.md
INV-5b → references/INV-5b-output-contract.md
INV-5c → references/INV-5c-aspire-verbs.md
INV-5d → references/INV-5d-action-discriminator.md
确定性检查 → references/deterministic-checks.md

Finding format

发现格式

Match axiom's vocabulary (HIGH / MEDIUM / LOW) so reviewers don't context-switch:

json

{
  "verdict": "pass | conditional | fail",
  "findings": [
    {
      "invariant": "INV-1",
      "severity": "HIGH",
      "file": "servers/exarchos-mcp/src/projections/foo.ts",
      "line": 42,
      "description": "Reducer mutates state in place inside the apply switch",
      "required_fix": "Return a new state object via spread; deep-freeze input via assertReducerImmutable in tests",
      "axiom_overlap": "DIM-1"
    }
  ]
}

匹配axiom的术语体系（HIGH / MEDIUM / LOW），避免评审者切换上下文：

json

{
  "verdict": "pass | conditional | fail",
  "findings": [
    {
      "invariant": "INV-1",
      "severity": "HIGH",
      "file": "servers/exarchos-mcp/src/projections/foo.ts",
      "line": 42,
      "description": "Reducer mutates state in place inside the apply switch",
      "required_fix": "Return a new state object via spread; deep-freeze input via assertReducerImmutable in tests",
      "axiom_overlap": "DIM-1"
    }
  ]
}

Pairing with axiom — complementarity matrix

与axiom的搭配——互补矩阵

The seam: axiom asks "is this code well-engineered?"; this skill asks "does this design respect Exarchos's load-bearing invariants?" A design can be axiom-clean and still violate event-sourcing integrity (a perfectly well-typed handler that mutates state in place instead of emitting events).

Finding	Axiom dimension	Design invariant
Lazy fallback that creates degraded EventStore	DIM-1 Topology	INV-1 (silent loss of event integrity)
Hardcoded `Skill({...})` in skills-src	—	INV-4
`console.log` -only catch in projection apply	DIM-2 Observability	INV-1 (fold throws → must trigger reducer-throw degradation path)
New CLI verb without MCP equivalent	—	INV-2
Adapter-local mutable cache for projection state	DIM-1 Topology	INV-1 + INV-2 (TaskStore-as-side-database anti-pattern)
`runtimes/claude.yaml` field read at runtime	—	INV-3
Tool description without "do NOT use for" guidance	—	INV-5a
Successful `ToolResult` without `next_actions`	—	INV-5b
Long-running op using NDJSON post-v2.11.0	—	INV-5b (should use Tasks SEP-1686)
New top-level tool that should be an action on `exarchos_workflow`	—	INV-5d
Schema field removed but still read	DIM-3 Contracts	INV-1 if it's an event field

Concerns axiom owns and this skill defers to:

Concern	Owner
Generic SOLID, coupling, dependency direction (DIM-6)	`axiom:critique`
Generic error handling, silent fallbacks (DIM-2, DIM-7)	`axiom:harden`
Generic schema-runtime drift, type-assertion safety (DIM-3)	`axiom:scan` , `axiom:critique`
Generic test fidelity, mock overuse (DIM-4)	`axiom:verify`
Generic dead code, vestigial patterns (DIM-5)	`axiom:distill`
AI-prose tells (DIM-8)	`axiom:humanize`

核心差异：axiom关注「代码是否工程化良好？」；本技能关注「设计是否符合Exarchos的核心架构不变量？」。一个设计可能在axiom审核中达标，但仍违反事件溯源完整性（例如，一个类型完全合规的处理器却在原地修改状态而非触发事件）。

发现内容	Axiom维度	设计不变量
创建降级EventStore的懒加载回退机制	DIM-1 Topology	INV-1（事件完整性静默丢失）
skills-src中硬编码的 `Skill({...})`	—	INV-4
投影apply中仅用 `console.log` 捕获异常	DIM-2 Observability	INV-1（必须触发reducer抛出降级路径，而非折叠异常）
无对应MCP实现的新CLI动词	—	INV-2
投影状态的适配器本地可变缓存	DIM-1 Topology	INV-1 + INV-2（TaskStore作为侧数据库的反模式）
运行时读取 `runtimes/claude.yaml` 字段	—	INV-3
无「禁止使用场景」说明的工具描述	—	INV-5a
无 `next_actions` 的成功 `ToolResult`	—	INV-5b
v2.11.0版本后使用NDJSON的长时操作	—	INV-5b（应使用Tasks SEP-1686）
应作为 `exarchos_workflow` 动作的新顶层工具	—	INV-5d
已移除但仍被读取的Schema字段	DIM-3 Contracts	若为事件字段则属于INV-1

axiom负责处理、本技能无需介入的关注点：

关注点	负责技能
通用SOLID原则、耦合性、依赖方向（DIM-6）	`axiom:critique`
通用错误处理、静默回退（DIM-2, DIM-7）	`axiom:harden`
通用Schema-运行时漂移、类型断言安全性（DIM-3）	`axiom:scan` , `axiom:critique`
通用测试保真度、过度使用Mock（DIM-4）	`axiom:verify`
通用死代码、遗留模式（DIM-5）	`axiom:distill`
AI生成文案特征（DIM-8）	`axiom:humanize`

Source

来源

Discovery report:

docs/research/2026-05-07-design-invariants-skill.md

. Amend this skill when the principles doc per #1118 lands at

docs/architecture/principles.md

— the skill becomes the operational projection of that doc rather than re-stating principles.

发现报告：

docs/research/2026-05-07-design-invariants-skill.md

。当#1118对应的原则文档落地到

docs/architecture/principles.md

时，需更新本技能——本技能将成为该文档的操作层面映射，而非重复陈述原则内容。