ai-sdlc-conventional-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ai-sdlc-conventional-commit: Conventional Commit Message

ai-sdlc-conventional-commit: 规范提交消息

Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. Before producing the final artifact, confirm required inputs, target audience, missing facts, output format, and constraints when they are unclear. Do not invent missing information. Ask concise clarification questions when required inputs are absent.

内部AI SDLC技能，默认不面向客户。以下每条规则都必须严格遵守，不得跳过任何一条。在生成最终成果前，若所需输入、目标受众、缺失信息、输出格式或约束条件不明确，请先确认这些内容。不得编造缺失信息。当必要输入缺失时，请提出简洁的澄清问题。

0. Skill Card

0. 技能卡片

Skill name:
```
ai-sdlc-conventional-commit
```
Primary audience: Dev
Supporting audience: PM, BA, QA
Audience tags: Dev, PM, BA, QA
SDLC stage: Commit message drafting
Purpose: Draft, validate, or repair an AI SDLC commit message that uses Conventional Commit syntax and includes SDD, business, implementation, testing, and validation traceability when the change is medium or large.
Output: Conventional Commit subject/body with traceability and validation summary

技能名称：
```
ai-sdlc-conventional-commit
```
核心受众：开发人员（Dev）
支持受众：产品经理（PM）、业务分析师（BA）、测试人员（QA）
受众标签：Dev, PM, BA, QA
SDLC阶段：提交消息起草
用途：起草、验证或修复符合Conventional Commit语法的AI SDLC提交消息，当变更为中型或大型时，需包含SDD、业务、实现、测试和可追溯性验证信息。
输出：包含可追溯性和验证摘要的规范提交主题/正文

0.1 Required Inputs

0.1 必要输入

Change type, scope, and implementation summary.
Spec, validation, and test evidence when applicable.
Breaking-change or migration details if any.

变更类型、范围和实现摘要。
适用时的规范、验证和测试证据。
若存在破坏性变更或迁移细节，请提供相关信息。

0.2 Clarification Rules

0.2 澄清规则

Ask concise questions before finalizing when role, artifact, requirements, scope, audience, or constraints are unclear.
If optional information is missing, mark it as
```
TBD
```
,
```
Not provided
```
, or
```
Assumption
```
instead of inventing it.
Separate confirmed facts from assumptions and open questions.
Do not proceed to downstream synthesis when a required upstream artifact or decision is missing.

当角色、成果、需求、范围、受众或约束条件不明确时，在最终确定前提出简洁的问题。
若可选信息缺失，标记为
```
TBD
```
（待确定）、
```
Not provided
```
（未提供）或
```
Assumption
```
（假设），不得编造内容。
将已确认的事实与假设、待解决问题分开。
当必要的上游成果或决策缺失时，不得进行下游合成工作。

0.2.1 Flow Mode Flags

0.2.1 流程模式标志

Support two explicit execution flags:
```
--quick-flow
```
and
```
--full-flow
```
.
If both flags are supplied,
```
--full-flow
```
takes precedence because it is the stricter mode.
```
--quick-flow
```
: move fast, make high-quality progress with available context, avoid clarification questions unless continuing would create material product, security, compliance, data-loss, or irreversible implementation risk.
In
```
--quick-flow
```
, use documented assumptions, recommended defaults, existing repository patterns, and the nearest available artifact evidence; record important assumptions and decisions in
```
decision-log.md
```
.
In
```
--quick-flow
```
, run only focused checks that are directly relevant, cheap, and likely to catch regressions for the requested work; report any skipped broader checks as residual risk.
```
--full-flow
```
: ask concise clarification questions when inputs, scope, ownership, acceptance criteria, or decisions are unclear; do not silently assume material requirements.
In
```
--full-flow
```
, verify upstream and downstream artifacts, decision-log entries, traceability links, acceptance criteria, and validation evidence before finalizing.
In
```
--full-flow
```
, run or recommend the skill-appropriate gates, reviews, scripts, and validation commands needed for end-to-end confidence; document any blocked verification explicitly.
When neither flag is supplied, follow the skill default rules and choose the least risky behavior for the request size and domain.

支持两种明确的执行标志：
```
--quick-flow
```
和
```
--full-flow
```
。
若同时提供两个标志，
```
--full-flow
```
优先，因为它是更严格的模式。
```
--quick-flow
```
：快速推进，利用现有上下文开展高质量工作，除非继续执行会带来产品、安全、合规、数据丢失或不可逆的实现风险，否则避免提出澄清问题。
在
```
--quick-flow
```
模式下，使用已记录的假设、推荐的默认值、现有仓库模式和最接近的可用成果证据；将重要假设和决策记录在
```
decision-log.md
```
中。
在
```
--quick-flow
```
模式下，仅运行与请求工作直接相关、成本低且可能发现回归问题的针对性检查；将任何跳过的更广泛检查作为剩余风险进行报告。
```
--full-flow
```
：当输入、范围、所有权、验收标准或决策不明确时，提出简洁的澄清问题；不得默认重要的需求。
在
```
--full-flow
```
模式下，在最终确定前验证上游和下游成果、决策日志条目、可追溯性链接、验收标准和验证证据。
在
```
--full-flow
```
模式下，运行或推荐适合技能的关卡、审核、脚本和验证命令，以确保端到端的可信度；明确记录任何受阻的验证工作。
当未提供任何标志时，遵循技能默认规则，并根据请求的规模和领域选择风险最低的行为。

0.3 Output Rules

0.3 输出规则

Keep output structured with headings and bullets.
Make findings, gaps, risks, and blockers explicit.
Tie recommendations to evidence from the provided artifact, repository,
```
specs-refiniment/<feature-name>/<file.md>
```
workspace, or user context.
Include role ownership when the output creates follow-up work for BA, QA, Dev, PM, or Delivery.
Return progress, completion, validation, and handoff summaries directly in the Codex response.

Before the final response, emit the

ai-sdlc-handoff/v1

contract with

result

blockers

next_required

, and

next_optional

; every action includes

reason

command

, and

expected_artifact

Do not create
```
summary.txt
```
,
```
*-summary.txt
```
, or another standalone summary file unless the user explicitly requests one.
Keep durable writes limited to the canonical lifecycle artifacts, decision log, human-readable index, and
```
_ai_sdlc
```
machine files.
Let shared helpers migrate legacy paths on the next write; never overwrite or manually merge divergent legacy and canonical files.

输出需使用标题和项目符号保持结构化。
明确指出发现的问题、差距、风险和障碍。
建议需与提供的成果、仓库、
```
specs-refiniment/<feature-name>/<file.md>
```
工作区或用户上下文的证据相关联。
当输出为BA、QA、Dev、PM或交付团队创建后续工作时，需包含角色所有权信息。
在Codex响应中直接返回进度、完成情况、验证和交接摘要。

在最终响应前，输出

ai-sdlc-handoff/v1

协议，包含

result

、

blockers

、

next_required

和

next_optional

；每个操作需包含

reason

、

command

和

expected_artifact

。

除非用户明确要求，否则不得创建
```
summary.txt
```
、
```
*-summary.txt
```
或其他独立的摘要文件。
持久化写入仅限于标准生命周期成果、决策日志、人类可读索引和
```
_ai_sdlc
```
机器文件。
让共享助手在下次写入时迁移旧路径；不得覆盖或手动合并不一致的旧文件和标准文件。

0.4 Artifact Routing

0.4 成果路由

Maintain a feature decision log whenever this skill records, resolves, changes, or depends on a product, delivery, QA, security, validation, branching, implementation, or rollout decision.
For PM, BA, QA, Delivery, discovery, planning, refinement, and readiness work, write decisions to
```
specs-refiniment/<feature-name>/decision-log.md
```
.
For developer implementation SDD work, write decisions to
```
specs/<feature-name>/decision-log.md
```
.
Each decision-log entry must include date, decision, context or evidence, options considered when relevant, owner, status, and links to affected artifacts, tasks, tests, or validation evidence.

Use this exact decision-log structure:

markdown

# Decision Log

| ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

Use
```
specs/
```
only for developer implementation SDD packages and repo-governance artifacts.
Do not place PM, BA, QA, Delivery, discovery, planning, refinement, or readiness outputs in
```
specs/
```
; those belong at
```
specs-refiniment/<feature-name>/<file.md>
```
.
When consuming
```
specs-refiniment/<feature-name>/<file.md>
```
, treat it as upstream refinement context and create or update
```
specs/
```
only when implementation work is explicitly in scope.

每当本技能记录、解决、更改或依赖产品、交付、QA、安全、验证、分支、实现或发布决策时，需维护功能决策日志。
对于PM、BA、QA、交付、探索、规划、细化和准备工作，将决策写入
```
specs-refiniment/<feature-name>/decision-log.md
```
。
对于开发人员实现SDD的工作，将决策写入
```
specs/<feature-name>/decision-log.md
```
。
每个决策日志条目必须包含日期、决策、上下文或证据、相关可选方案（若适用）、负责人、状态以及受影响成果、任务、测试或验证证据的链接。

使用以下精确的决策日志结构：

markdown

# 决策日志

| ID | 日期 | 状态 | 负责人 | 决策 | 上下文/证据 | 考虑的可选方案 | 受影响成果 | 验证/追溯链接 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | 角色或姓名 | 简洁的决策内容 | 源事实、成果链接或证据 | 方案A；方案B；推荐默认值 | 受影响的文档、任务、代码、测试或发布说明 | 需求ID、测试ID、验证命令、PR、提交或工单 |

```
specs/
```
仅用于开发人员实现SDD的包和仓库治理成果。
不得将PM、BA、QA、交付、探索、规划、细化或准备工作的输出放在
```
specs/
```
中；这些内容应放在
```
specs-refiniment/<feature-name>/<file.md>
```
。
当使用
```
specs-refiniment/<feature-name>/<file.md>
```
时，将其视为上游细化上下文，仅当实现工作明确在范围内时才创建或更新
```
specs/
```
中的内容。

0.5 Feature State Machine

0.5 功能状态机

Maintain feature lifecycle state in TOON at

specs-refiniment/<feature-name>/_ai_sdlc/state.toon

for refinement work and

specs/<feature-name>/_ai_sdlc/state.toon

for implementation work.

Before executing this skill for a feature, check the state machine with

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

When this skill starts durable work, mark it in progress with
```
begin
```
; when the skill's required artifact or review is complete, mark it done with
```
complete
```
and include
```
--artifacts <path>
```
plus
```
--decision-ref DEC-###
```
when a decision was involved.
In
```
--full-flow
```
, do not proceed when predecessor stages are incomplete, another lifecycle skill is active, or the state file reports a blocker.
In
```
--quick-flow
```
, a predecessor skip is allowed only when continuing is low risk and the command includes
```
--assumption "..."
```
or
```
--decision-ref DEC-###
```
; record the same assumption or decision in
```
decision-log.md
```
.

Use

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

to emit compact LLM-readable state before choosing the next skill.

The state machine is feature-scoped: do not reuse a
```
state.toon
```
across unrelated feature folders.

在TOON中维护功能生命周期状态：细化工作对应

specs-refiniment/<feature-name>/_ai_sdlc/state.toon

，实现工作对应

specs/<feature-name>/_ai_sdlc/state.toon

。

在为某个功能执行本技能前，使用

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

检查状态机。

当本技能开始持久化工作时，用
```
begin
```
标记为进行中；当技能所需的成果或审核完成时，用
```
complete
```
标记为已完成，若涉及决策，需添加
```
--artifacts <path>
```
和
```
--decision-ref DEC-###
```
。
在
```
--full-flow
```
模式下，当前置阶段未完成、另一个生命周期技能处于活跃状态或状态文件报告存在障碍时，不得继续执行。
在
```
--quick-flow
```
模式下，仅当继续执行风险较低且命令包含
```
--assumption "..."
```
或
```
--decision-ref DEC-###
```
时，才允许跳过前置阶段；需在
```
decision-log.md
```
中记录相同的假设或决策。

在选择下一个技能前，使用

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

输出紧凑的LLM可读状态。

状态机以功能为范围：不得在不相关的功能文件夹之间复用
```
state.toon
```
。

0.6 Artifact Metadata And Metatags

0.6 成果元数据和元标签

Every Markdown artifact generated or updated by this skill must start with an
```
artifact_metadata
```
YAML frontmatter block before the first visible heading.

Use schema

ai-sdlc-artifact-metadata/v1

and keep these fields current:

feature

artifact

path

workspace

skill

flow_mode

state_file

decision_log

status

owner

created_at

updated_at

trace_ids

related_artifacts

validation

, and

metatags

```
metatags
```
must include at minimum
```
ai-sdlc
```
, the workspace (
```
refinement
```
or
```
implementation
```
), this skill name, the artifact type or filename stem, and a lifecycle/status tag such as
```
draft
```
,
```
review
```
,
```
approved
```
, or
```
validated
```
.
When
```
--quick-flow
```
is active, set
```
flow_mode: quick
```
, keep assumptions visible in the body, and add tags for major defaults or unresolved risk only when they help retrieval.
When
```
--full-flow
```
is active, set
```
flow_mode: full
```
, keep blockers and validation evidence reflected in
```
status
```
,
```
validation
```
,
```
trace_ids
```
, and
```
related_artifacts
```
.
Update metadata whenever the artifact path, status, owner, trace links, validation evidence, related artifacts, or decision references change.
Metadata is an index for routing, retrieval, and traceability; it does not replace the artifact body,
```
decision-log.md
```
, or
```
state.toon
```
.

本技能生成或更新的每个Markdown成果，必须在第一个可见标题前包含
```
artifact_metadata
```
YAML前置块。

使用

ai-sdlc-artifact-metadata/v1

schema，并保持以下字段最新：

feature

、

artifact

、

path

、

workspace

、

skill

、

flow_mode

、

state_file

、

decision_log

、

status

、

owner

、

created_at

、

updated_at

、

trace_ids

、

related_artifacts

、

validation

和

metatags

。

```
metatags
```
必须至少包含
```
ai-sdlc
```
、工作区（
```
refinement
```
或
```
implementation
```
）、本技能名称、成果类型或文件名主干，以及生命周期/状态标签（如
```
draft
```
、
```
review
```
、
```
approved
```
或
```
validated
```
）。
当
```
--quick-flow
```
激活时，设置
```
flow_mode: quick
```
，在正文中保留假设，仅当有助于检索时才添加主要默认值或未解决风险的标签。
当
```
--full-flow
```
激活时，设置
```
flow_mode: full
```
，在
```
status
```
、
```
validation
```
、
```
trace_ids
```
和
```
related_artifacts
```
中反映障碍和验证证据。
当成果路径、状态、负责人、追溯链接、验证证据、相关成果或决策引用发生变化时，更新元数据。
元数据是用于路由、检索和可追溯性的索引；它不能替代成果正文、
```
decision-log.md
```
或
```
state.toon
```
。

0.7 Specs Index

0.7 规范索引

Before searching across feature folders, inspect the compact LLM index first:
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
for refinement work or
```
specs/_ai_sdlc/specs-index.toon
```
for implementation work.
Use the human-readable index at
```
specs-refiniment/specs-index.md
```
or
```
specs/specs-index.md
```
when reporting feature coverage, artifact inventory, or handoff status to people.

After this skill creates or materially updates an artifact, refresh the matching workspace index with

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

In
```
--quick-flow
```
, rely on
```
specs-index.toon
```
to choose the smallest relevant artifact set before opening files.
In
```
--full-flow
```
, verify the updated artifact appears in both
```
specs-index.toon
```
and
```
specs-index.md
```
before final handoff.
The specs index summarizes artifact metadata and state; it does not replace reading the selected source artifacts when details, approvals, or validation evidence matter.

在跨功能文件夹搜索前，先查看紧凑的LLM索引：细化工作对应
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
，实现工作对应
```
specs/_ai_sdlc/specs-index.toon
```
。
当向人员报告功能覆盖范围、成果清单或交接状态时，使用
```
specs-refiniment/specs-index.md
```
或
```
specs/specs-index.md
```
的人类可读索引。

本技能创建或实质性更新成果后，使用

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

刷新匹配的工作区索引。

在
```
--quick-flow
```
模式下，依赖
```
specs-index.toon
```
选择最小的相关成果集，然后再打开文件。
在
```
--full-flow
```
模式下，在最终交接前验证更新后的成果是否同时出现在
```
specs-index.toon
```
和
```
specs-index.md
```
中。
规范索引汇总成果元数据和状态；当细节、审批或验证证据很重要时，它不能替代阅读选定的源成果。

References

参考资料

Use
```
scripts/validate_commit_msg.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.

当工作流需要确定性验证、规划或格式化时，使用
```
scripts/validate_commit_msg.py
```
；若支持，传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。

Script Usage

脚本用法

Validate commit messages before presenting or using them.

Quick flow:

python3 skills/ai-sdlc-conventional-commit/scripts/validate_commit_msg.py --quick-flow --message "<type(scope): subject>"

Full flow:

python3 skills/ai-sdlc-conventional-commit/scripts/validate_commit_msg.py --full-flow path/to/commit-message.txt

Use
```
--require-traceability
```
when medium or large work must include
```
Spec:
```
and
```
Validation:
```
metadata even outside full flow.

在展示或使用提交消息前先进行验证。

快速模式：

python3 skills/ai-sdlc-conventional-commit/scripts/validate_commit_msg.py --quick-flow --message "<type(scope): subject>"

完整模式：

python3 skills/ai-sdlc-conventional-commit/scripts/validate_commit_msg.py --full-flow path/to/commit-message.txt

当中型或大型工作必须包含
```
Spec:
```
和
```
Validation:
```
元数据时，即使在完整模式之外，也使用
```
--require-traceability
```
。

Purpose

用途

Draft, validate, or repair an AI SDLC commit message that uses Conventional Commit syntax and includes SDD, business, implementation, testing, and validation traceability when the change is medium or large.

起草、验证或修复符合Conventional Commit语法的AI SDLC提交消息，当变更为中型或大型时，需包含SDD、业务、实现、测试和可追溯性验证信息。

Inputs

输入

Collect the intended change type:
```
feat
```
,
```
fix
```
,
```
docs
```
,
```
test
```
,
```
refactor
```
,
```
chore
```
,
```
ci
```
,
```
build
```
,
```
perf
```
, or
```
revert
```
.
Collect the optional scope when it adds useful precision, for example
```
api
```
,
```
bitgo
```
,
```
sdd
```
,
```
skills
```
, or
```
docs
```
.
Collect the active spec folder for medium or large work, for example
```
specs/177-skill-instruction-upgrade
```
.
Collect the implementation summary, reviewer-visible test path, and exact validation commands with outcomes.
Collect breaking-change details when behavior, schema, API contract, migration requirements, or compatibility changes are not backward compatible.

收集预期的变更类型：
```
feat
```
、
```
fix
```
、
```
docs
```
、
```
test
```
、
```
refactor
```
、
```
chore
```
、
```
ci
```
、
```
build
```
、
```
perf
```
或
```
revert
```
。
当范围能增加有用的精度时，收集可选范围，例如
```
api
```
、
```
bitgo
```
、
```
sdd
```
、
```
skills
```
或
```
docs
```
。
收集中型或大型工作的活跃规范文件夹，例如
```
specs/177-skill-instruction-upgrade
```
。
收集实现摘要、审核人员可见的测试路径以及带有结果的精确验证命令。
当行为、 schema、API协议、迁移要求或兼容性变更不向后兼容时，收集破坏性变更细节。

Steps

步骤

Write the subject as

type(scope): imperative summary

type: imperative summary

Keep the subject under 72 characters unless a longer subject prevents ambiguity.
Use a lowercase type and lowercase kebab-case scope.

Use an imperative summary, for example

fix bitgo wallet routing

, not

fixed bitgo wallet routing

Add
```
Spec: specs/NNN-feature-name
```
for medium or large work.

Add

Business context

Implementation details

Mermaid diagram

How to test

, and

Validation

sections for medium or large work.

Add
```
BREAKING CHANGE:
```
when the change requires a migration, client update, data backfill, or operator action.

Validate the message before committing:

bash

python3 skills/ai-sdlc-conventional-commit/scripts/validate_commit_msg.py path/to/message.txt --require-traceability

Fix every validator error before using the message.

主题格式为

type(scope): 祈使语气摘要

或

type: 祈使语气摘要

。

主题长度控制在72字符以内，除非更长的主题能避免歧义。
使用小写的类型和小写的短横线命名法（kebab-case）范围。

使用祈使语气的摘要，例如

fix bitgo wallet routing

，而非

fixed bitgo wallet routing

。

对于中型或大型工作，添加
```
Spec: specs/NNN-feature-name
```
。
对于中型或大型工作，添加
```
Business context
```
（业务上下文）、
```
Implementation details
```
（实现细节）、
```
Mermaid diagram
```
（Mermaid图）、
```
How to test
```
（测试方法）和
```
Validation
```
（验证）部分。
当变更需要迁移、客户端更新、数据回填或操作人员操作时，添加
```
BREAKING CHANGE:
```
。

提交前验证消息：

bash

python3 skills/ai-sdlc-conventional-commit/scripts/validate_commit_msg.py path/to/message.txt --require-traceability

在使用消息前修复所有验证器错误。

Output Spec

输出规范

Return a complete commit message, not a paragraph about the message:

text

type(scope): imperative summary


Spec: specs/NNN-feature-name

Business context:
One or two sentences explaining why the change matters to product, operations, risk, clients, QA, or delivery governance.

Implementation details:
- Concrete code, contract, doc, workflow, provider, schema, or validation changes.
- Important compatibility, rollout, or failure-mode decisions.

Mermaid diagram:
```mermaid
flowchart LR
    Actor["Actor or trigger"] --> Change["Changed AI SDLC path"]
    Change --> Outcome["Business-visible outcome"]
```

How to test:
1. Reviewer-visible happy path or documentation path.
2. Important permission, failure, boundary, regression, or governance path.

Validation:
- command -> outcome

Quality gate:

Pass when the subject is Conventional Commit compliant, traceability is present when required, validation commands are exact, and every required body section contains concrete project-specific content.
Fail when the message uses placeholders, omits required traceability, hides failed validation, or describes implementation in vague terms such as "updated stuff" or "improved docs".

返回完整的提交消息，而非关于消息的段落：

text

type(scope): 祈使语气摘要


Spec: specs/NNN-feature-name

Business context:
用一两句话解释变更对产品、运营、风险、客户、QA或交付治理的重要性。

Implementation details:
- 具体的代码、协议、文档、工作流、提供商、schema或验证变更。
- 重要的兼容性、发布或故障模式决策。

Mermaid diagram:
```mermaid
flowchart LR
    Actor["参与者或触发器"] --> Change["变更后的AI SDLC路径"]
    Change --> Outcome["业务可见的结果"]
```

How to test:
1. 审核人员可见的正常路径或文档路径。
2. 重要的权限、故障、边界、回归或治理路径。

Validation:
- 命令 -> 结果

质量关卡：

通过：主题符合Conventional Commit规范，必要时包含可追溯性，验证命令精确，每个必填正文部分包含具体的项目相关内容。
失败：消息使用占位符，省略必要的可追溯性，隐藏失败的验证，或用模糊术语描述实现（如"updated stuff"或"improved docs"）。

Examples

示例

Valid medium-change message:

text

docs(skill): upgrade repo-local skill instructions


Spec: specs/177-skill-instruction-upgrade

Business context:
This makes AI skill usage deterministic for future AI SDLC work and reduces reviewer effort caused by vague skill outputs.

Implementation details:
- Rewrote every repo-local skill with Purpose, Inputs, Steps, Output spec, Examples, Edge cases, and Scope boundary.
- Added a skill index that maps each workflow phase to the correct skill.

Mermaid diagram:
```mermaid
flowchart LR
    Request["Skill audit"] --> Rewrite["Normalized SKILL.md files"]
    Rewrite --> Output["Consistent AI assistant behavior"]
```

How to test:
1. Read a cold skill and confirm it contains a complete execution contract.
2. Run skill and spec validators for the updated files.

Validation:
- PYTHONPYCACHEPREFIX=/tmp/ai-sdlc-harness-pycache python3 -m py_compile skills/ai-sdlc-validation/scripts/validation_plan.py -> passed
- git diff --check -> passed

Invalid counter-example:

text

updates

Made skills better.

Reject this because the subject is not Conventional Commit syntax, traceability is absent, and validation evidence is missing.

有效的中型变更消息：

text

docs(skill): upgrade repo-local skill instructions


Spec: specs/177-skill-instruction-upgrade

Business context:
This makes AI skill usage deterministic for future AI SDLC work and reduces reviewer effort caused by vague skill outputs.

Implementation details:
- Rewrote every repo-local skill with Purpose, Inputs, Steps, Output spec, Examples, Edge cases, and Scope boundary.
- Added a skill index that maps each workflow phase to the correct skill.

Mermaid diagram:
```mermaid
flowchart LR
    Request["Skill audit"] --> Rewrite["Normalized SKILL.md files"]
    Rewrite --> Output["Consistent AI assistant behavior"]
```

How to test:
1. Read a cold skill and confirm it contains a complete execution contract.
2. Run skill and spec validators for the updated files.

Validation:
- PYTHONPYCACHEPREFIX=/tmp/ai-sdlc-harness-pycache python3 -m py_compile skills/ai-sdlc-validation/scripts/validation_plan.py -> passed
- git diff --check -> passed

无效的反例：

text

updates

Made skills better.

拒绝此消息，因为主题不符合Conventional Commit语法，缺少可追溯性，且没有验证证据。

Edge Cases

边缘情况

Include
```
BREAKING CHANGE:
```
even for documentation-only commits when the documented workflow intentionally retires a previously required control.
Use
```
revert: ...
```
only when the commit actually reverts a previous commit; include the reverted hash in the body.
Stop and fix the message when the validator fails; do not commit with an invalid message.
State failed or skipped validation honestly in the
```
Validation
```
section with the residual risk.

当文档化的工作流有意停用先前要求的控制措施时，即使是仅涉及文档的提交，也需包含
```
BREAKING CHANGE:
```
。
仅当提交实际还原了先前的提交时，才使用
```
revert: ...
```
；在正文中包含被还原的哈希值。
当验证器失败时，停止并修复消息；不得使用无效消息提交。
在
```
Validation
```
部分如实说明失败或跳过的验证以及剩余风险。

Scope Boundary

范围边界

Do not stage files or create commits; use
```
$ai-sdlc-commit-prep
```
for staging and commit execution.
Do not invent validation results; use
```
$ai-sdlc-validation
```
to choose and run checks.
Do not use this skill to summarize a diff unless the output is a commit message.

不得暂存文件或创建提交；使用
```
$ai-sdlc-commit-prep
```
进行暂存和提交执行。
不得编造验证结果；使用
```
$ai-sdlc-validation
```
选择并运行检查。
不得使用本技能汇总差异，除非输出是提交消息。