validation-contract

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Validation Contract

验证契约

Use When

适用场景

Authoring a new specialist skill and deciding which validation evidence it should produce.
Normalising an older specialist skill against the current house style.
Preparing a feature or release for ship and assembling the Release Evidence Bundle.
Reviewing a PR that claims a feature is production-ready.

编写新的专业Skill并确定其应生成的验证证据。
按照当前规范标准化旧的专业Skill。
准备功能或版本发布并组装Release Evidence Bundle。
审查声称功能已具备生产就绪条件的PR。

Do Not Use When

不适用场景

The work is purely local, experimental, or explicitly throwaway with no path to production.
The skill being authored is a baseline, process, or pure index skill. Those do not declare evidence.
The task is unrelated to validation planning or shipping readiness.

工作内容仅为本地、实验性或明确可丢弃，无上线生产的路径。
编写的Skill是基线Skill、流程Skill或纯索引Skill。这些Skill无需声明证据。
任务与验证规划或发布就绪无关。

Required Inputs

必要输入

The specialist skill or feature being validated, including its intended scope and risk tier.
Access to the repository's existing validation skills (
```
advanced-testing-strategy
```
,
```
vibe-security-skill
```
,
```
observability-monitoring
```
, etc.) as the source of category-specific "how to validate" content.
Awareness of the 14 canonical artifact templates in
```
skill-composition-standards/references/
```
so evidence rows can cite existing formats.

待验证的专业Skill或功能，包括其预期范围和风险等级。
访问仓库中现有验证Skill（如
```
advanced-testing-strategy
```
、
```
vibe-security-skill
```
、
```
observability-monitoring
```
等），作为特定类别“如何验证”内容的来源。
了解
```
skill-composition-standards/references/
```
中的14个标准工件模板，以便证据行可以引用现有格式。

Workflow

工作流程

Identify whether the skill or feature in scope is specialist (declares evidence) or baseline/process (does not).
For specialist skills: map each artifact the skill produces to one of the seven evidence categories.
For releases: produce a Release Evidence Bundle that links concrete artifacts under each of the seven categories, using
```
N/A — <reason>
```
only where an entire category legitimately does not apply.
Cross-check risk tier guidance before permitting any
```
N/A
```
in high-risk releases.

确定范围内的Skill或功能是专业Skill（需声明证据）还是基线/流程Skill（无需声明）。
对于专业Skill：将其生成的每个工件映射到七个证据类别之一。
对于版本发布：生成Release Evidence Bundle，在每个类别下关联具体工件；仅当整个类别确实不适用时，才使用
```
N/A — <原因>
```
标注。
在允许高风险版本中出现任何
```
N/A
```
标注前，交叉检查风险等级指南。

Quality Standards

质量标准

Every specialist skill that produces validation evidence declares at least one evidence category with a concrete artifact reference.
Evidence declarations cite existing artifact templates where possible instead of inventing new formats.
Release Evidence Bundles never carry empty cells. Every cell links evidence or carries an
```
N/A — <reason>
```
line.

每个生成验证证据的专业Skill至少声明一个带有具体工件引用的证据类别。
证据声明应尽可能引用现有工件模板，而非创建新格式。
Release Evidence Bundle不得存在空单元格。每个单元格要么关联证据，要么包含
```
N/A — <原因>
```
行。

Anti-Patterns

反模式

Declaring every category on every skill "just in case". This kills the signal.
Writing prose validation notes instead of linking concrete artifacts in a Release Evidence Bundle.
Permitting unjustified
```
N/A
```
on Correctness, Security, Data safety, Operability, or Release evidence in high-risk releases.
Treating the Release Evidence Bundle as a retrospective summary written after ship. It is produced before ship.

为每个Skill声明所有类别“以防万一”。这会削弱信号有效性。
在Release Evidence Bundle中编写散文式验证说明，而非关联具体工件。
在高风险版本中，允许Correctness、Security、Data safety、Operability或Release evidence类别出现无正当理由的
```
N/A
```
标注。
将Release Evidence Bundle视为发布后编写的回顾性总结。它应在发布前生成。

Outputs

输出

A specialist skill with a validated
```
## Evidence Produced
```
section declaring one or more of the seven categories.
A Release Evidence Bundle in the project's
```
docs/
```
tree linking evidence for every applicable category at ship time.
Clear
```
N/A — <reason>
```
annotations for non-applicable categories, with risk-tier-aware justification.

带有已验证的
```
## Evidence Produced
```
章节的专业Skill，该章节声明一个或多个七个类别中的项。
项目
```
docs/
```
目录中的Release Evidence Bundle，在发布时关联每个适用类别的证据。
对不适用类别清晰标注
```
N/A — <原因>
```
，并提供符合风险等级的理由。

References

参考资料

references/evidence-categories.md: per-category definition, indicative contributing skills, and common artifact shapes.
references/declaration-form.md: the
```
## Evidence Produced
```
table form, rules, and worked examples.
references/release-evidence-bundle-template.md: the canonical fillable Release Evidence Bundle.
references/integration-rollout.md: audit trail of edits made to other skills during this skill's rollout.

references/evidence-categories.md：每个类别的定义、指示性贡献Skill和常见工件类型。
references/declaration-form.md：
```
## Evidence Produced
```
表格格式、规则及示例。
references/release-evidence-bundle-template.md：标准可填写的Release Evidence Bundle模板。
references/integration-rollout.md：此Skill推出期间对其他Skill所做编辑的审计跟踪。

The three repository-wide contracts

仓库级的三个契约

The repository is held together by three contracts, each codified in a baseline skill:

House-style contract — every skill follows the same shape. Source:
```
skill-composition-standards
```
, Standard 1.
Inputs/Outputs contract — every skill declares the artifacts it consumes and produces. Source:
```
skill-composition-standards
```
, Standard 2.
Evidence contract — every specialist skill declares which of seven fixed validation categories its artifacts contribute to, and every release produces a Release Evidence Bundle. Source: this skill.

The three contracts stack. A skill that meets Standard 1 but skips Standard 2 or 3 is not repository-grade.

仓库由三个契约维系，每个契约都在基线Skill中编码：

风格规范契约 —— 每个Skill遵循相同的结构。来源：
```
skill-composition-standards
```
，标准1。
输入/输出契约 —— 每个Skill声明其消耗和生成的工件。来源：
```
skill-composition-standards
```
，标准2。
证据契约 —— 每个专业Skill声明其工件对七个固定验证类别中的哪些有贡献，每个版本发布都需生成Release Evidence Bundle。来源：本Skill。

这三个契约是层级关系。符合标准1但未遵循标准2或3的Skill不属于仓库级Skill。

The seven evidence categories

七个证据类别

#	Category	What the evidence proves
1	Correctness	Behaviour matches spec; tests cover risk surface; contracts hold.
2	Security	Threat model exists; scans clean; secrets handled; auth/authorisation verified.
3	Data safety	Schema integrity; migration safety; backup, retention, and PII handling.
4	Performance	Budgets met; load profile understood; query plans acceptable.
5	Operability	SLOs defined; runbook exists; observability wired; rollback plan ready.
6	UX quality	Accessibility pass; design audit; content/UX-writing review; AI slop check.
7	Release evidence	Change record; migration plan; rollout/rollback log; post-deploy verification.

The taxonomy is closed. Adding an eighth category requires editing this skill, not silently extending it elsewhere. Full definitions and indicative contributing skills live in references/evidence-categories.md.

#	类别	证据需证明的内容
1	Correctness	行为符合规格；测试覆盖风险面；契约有效。
2	Security	存在威胁模型；扫描无问题；密钥处理合规；认证/授权已验证。
3	Data safety	架构完整性；迁移安全；备份、保留及PII处理合规。
4	Performance	符合预算；了解负载情况；查询计划可接受。
5	Operability	已定义SLO；存在运行手册；已接入可观测性；回滚计划就绪。
6	UX quality	通过无障碍测试；设计审核通过；内容/UX写作已评审；AI冗余检查通过。
7	Release evidence	变更记录；迁移计划；发布/回滚日志；部署后验证完成。

分类是封闭的。添加第八个类别需要编辑本Skill，而非在其他地方私自扩展。完整定义和指示性贡献Skill请参见references/evidence-categories.md。

Declaration mechanic

声明机制

Specialist skills add a

## Evidence Produced

section to their

SKILL.md

, between

## Outputs

and

## References

markdown

undefined

专业Skill需在其

SKILL.md

的

## Outputs

和

## References

之间添加

## Evidence Produced

章节：

markdown

undefined

Evidence Produced

Category	Artifact	Format	Example
Security	Threat model	Markdown doc per `skill-composition-standards/references/threat-model-template.md`	`docs/security/threat-model-checkout.md`
Operability	Runbook	Markdown doc per `skill-composition-standards/references/runbook-template.md`	`docs/runbooks/payment-failures.md`

undefined

Category	Artifact	Format	Example
Security	Threat model	Markdown doc per `skill-composition-standards/references/threat-model-template.md`	`docs/security/threat-model-checkout.md`
Operability	Runbook	Markdown doc per `skill-composition-standards/references/runbook-template.md`	`docs/runbooks/payment-failures.md`

undefined

Rules

规则

A specialist skill that produces validation evidence MUST declare at least one row.
Each row's
```
Category
```
value MUST be one of the seven canonical names (case-sensitive).
Each row's
```
Format
```
field MUST reference an existing template or define its own format inline in the same
```
SKILL.md
```
.
A specialist skill MAY contribute to multiple categories.
Baseline skills, process skills, and pure index/orchestration skills MUST NOT declare.

Worked examples live in references/declaration-form.md.

生成验证证据的专业Skill 必须至少声明一行。
每行的
```
Category
```
值必须是七个标准名称之一（区分大小写）。
每行的
```
Format
```
字段必须引用现有模板，或在同一
```
SKILL.md
```
中内联定义自己的格式。
专业Skill 可以贡献多个类别。
基线Skill、流程Skill及纯索引/编排Skill 不得进行声明。

示例请参见references/declaration-form.md。

Specialist vs exempt skills

专业Skill与豁免Skill

A skill is "specialist" for the purposes of this contract when it:

Produces concrete project artifacts (code patterns, schemas, configs, documents).
Is loaded for a specific domain or platform problem rather than as a baseline frame.

Skills exempt from declaring (non-exhaustive):

world-class-engineering

skill-composition-standards

validation-contract

itself.

system-architecture-design

engineering-management-system

git-collaboration-workflow

```
feature-planning
```
,
```
spec-architect
```
.
All
```
superpowers:*
```
skills.

When a skill straddles the line, the default is declare. False positives are cheaper than silent omissions.

就本契约而言，Skill被视为“专业Skill”的条件是：

生成具体的项目工件（代码模式、架构、配置、文档）。
针对特定领域或平台问题加载，而非作为基线框架。

豁免声明的Skill（非 exhaustive）：

world-class-engineering

、

skill-composition-standards

、

validation-contract

本身。

system-architecture-design

、

engineering-management-system

、

git-collaboration-workflow

。

```
feature-planning
```
、
```
spec-architect
```
。
所有
```
superpowers:*
```
类Skill。

当Skill处于模糊地带时，默认规则是必须声明。误判为专业Skill的成本低于遗漏声明的成本。

The Release Evidence Bundle

Release Evidence Bundle

When a feature or release is ready to ship, the reviewer produces a single fillable document — the Release Evidence Bundle — that links to the concrete artifacts satisfying each of the seven categories.

Template: references/release-evidence-bundle-template.md.
N/A
semantics: permitted only with a reason on the same line. An empty cell is not acceptable.
Risk tier guidance:
- Low risk — internal tools, docs, non-user-facing scripts. Typical bundle has 3-4 categories live.
- Medium risk — user-facing feature, single-tenant. All 7 categories addressed; some may be
```
N/A
```
  with reason.
- High risk — multi-tenant data, payments, auth, external APIs, AI features. All 7 categories live; no
```
N/A
```
  permitted on Correctness, Security, Data safety, Operability, or Release evidence.

当功能或版本准备发布时，评审者需生成一份可填写的单一文档——Release Evidence Bundle，关联满足七个类别的具体工件。

模板： references/release-evidence-bundle-template.md。
N/A
语义：仅允许在同一行附带原因的情况下使用。空单元格是不可接受的。
风险等级指南：
- 低风险 —— 内部工具、文档、非面向用户的脚本。典型的Bundle包含3-4个有效类别。
- 中风险 —— 面向用户的功能、单租户。所有7个类别均需处理；部分类别可标注
```
N/A
```
  并附带原因。
- 高风险 —— 多租户数据、支付、认证、外部API、AI功能。所有7个类别均需有效；Correctness、Security、Data safety、Operability或Release evidence类别不允许标注
```
N/A
```
  。

Strictness

严格性

The contract uses MUST, MAY, MUST NOT in the RFC 2119 sense.
Mechanical enforcement is out of scope for this skill. It lands separately as a CI contract-gate hook that will:
- parse
```
## Evidence Produced
```
  tables and warn on missing or invalid categories.
- parse Release Evidence Bundles and warn on empty cells or unjustified
```
N/A
```
  .
Authoring with binding language now means the CI hook is a parser and CI integration only, not a policy debate.

本契约使用的MUST、MAY、MUST NOT符合RFC 2119的定义。
本Skill不涉及机械强制执行。这将作为CI契约门钩子单独实现，功能包括：
- 解析
```
## Evidence Produced
```
  表格，对缺失或无效类别发出警告。
- 解析Release Evidence Bundle，对空单元格或无正当理由的
```
N/A
```
  标注发出警告。
使用约束性语言编写本契约意味着，CI钩子仅作为解析器和CI集成工具，而非政策讨论的载体。

Integration with existing skills

与现有Skill的集成

The rollout in references/integration-rollout.md lists every edit made to other skills when this skill was introduced. Future edits that touch this contract should update that file.

references/integration-rollout.md中的推出记录列出了本Skill引入时对其他Skill所做的所有编辑。未来涉及本契约的编辑应更新该文件。

Companion Skills

配套Skill

skill-composition-standards

— Standards 1 and 2. Load this before

validation-contract

```
world-class-engineering
```
— repository production-readiness bar. This contract makes the evidence of meeting that bar a first-class artifact.
Category-specific skills — the source of truth for how to validate within each category (see references/evidence-categories.md).

skill-composition-standards

—— 标准1和2。应在

validation-contract

之前加载。

```
world-class-engineering
```
—— 仓库生产就绪标准。本契约将满足该标准的证据作为一等工件。
特定类别Skill —— 每个类别内“如何验证”的事实来源（参见references/evidence-categories.md）。