Problem Definition: <short title>

• Slug: <ASSESS_SLUG>
• Created: <ISO 8601 date>
• Inputs used: intake.md? | research.md? | user input only

Problem Statement

<One or two sentences, in the problem space.>

Affected Users & Stakeholders

• Users: —
• Stakeholders: — <interest / decision power>

Goals

Non-Goals

Success Metrics

• (baseline: <current value / unknown>)

Cost of Inaction

Open Questions

• [NEEDS CLARIFICATION: …]

模板头部有三个元数据字段值得注意：

- `Slug` 使工件可回溯到评估目录，与其余四个工件保持一致句柄；
- `Created` 采用 ISO 8601 日期，保证时间可机器解析；
- `Inputs used` 显式记录本定义实际使用了哪些上游输入（`intake.md?` / `research.md?` / 仅用户输入），这让"定义是否建立在证据上"一目了然，也为 `decide` 阶段评分时的溯源提供依据。

`Success Metrics` 中每个信号都要求附带 `(baseline: <current value / unknown>)`——这直接服务于第 6 步的基线思维：没有基线度量的目标在 `decide` 的"Value vs. cost of inaction"评分中难以自证。

执行完毕后，`define` 向用户回报三样东西：slug（独占一行）、`problem.md` 的路径、未决问题的计数，以及下一步指令 `__SPECKIT_COMMAND_ASSESS_SHAPE__ slug=<ASSESS_SLUG>`。

## 下游消费：problem.md 如何驱动 shape 与 decide

理解 `define` 的价值，最好的方式看它的两个直接消费者。

**shape 阶段的消费**（见 [speckit.assess.shape.md](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/extensions/assess/commands/speckit.assess.shape.md?utm_source=gitcode_repo_files)）：`problem.md` 是**强制前置**（"若不存在，停止并指导用户先运行 define——在没有已定义问题的情况下塑形，会诱导真空中的方案设计"）。shape 必须读取 `problem.md`（以及存在的 `research.md`/`intake.md`），确保所生成的 2–3 个概念级选项"address the stated goals, respect the non-goals, and are grounded in evidence"——即选项对准定义的目标、尊重非目标、有证据支撑。这正是 `define` 刻意产出 Goals/Non-Goals 分离结构的原因：Non-Goals 会被 shape 直接继承为推荐选项的 Out of Scope。

**decide 阶段的消费**（见 [speckit.assess.decide.md](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/extensions/assess/commands/speckit.assess.decide.md?utm_source=gitcode_repo_files)）：`decide` 用六个显式标准给想法打分（每项评级 `strong | adequate | weak | unknown` 并附一行来自工件的论据），其中两项直接以 `problem.md` 为数据源：

| 标准 | 数据来源 |
|------|----------|
| Problem validity（问题是否真实且值得解决） | `problem.md` + `research.md` |
| Value vs. cost of inaction（解决它是否胜过不行动） | `problem.md` |

换言之，`define` 第 1 步的 Problem Statement 决定了"Problem validity"一栏，第 6 步的 Cost of Inaction 决定了"Value vs. inaction"一栏。若 `problem.md` 中充斥未标记的杜撰内容或含糊的定性目标，`decide` 的评分只能给出 `weak`/`unknown`，而 `go` 结论硬性要求 problem validity `adequate`+ 且证据强度 `adequate`+（绝不接受 `weak`/`unknown`）——问题定义的质量因此直接卡住了 go 的门槛。

### `__SPECKIT_COMMAND_*__` 占位符的解析机制

命令文档中出现的 `__SPECKIT_COMMAND_ASSESS_SHAPE__`、`__SPECKIT_COMMAND_ASSESS_DECIDE__` 等并非字面量，而是 spec-kit 的命令引用占位符。从源码看，[extensions/__init__.py](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/src/specify_cli/extensions/__init__.py?utm_source=gitcode_repo_files#L1599) 在安装扩展命令时通过正则 `r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__"` 将其替换为实际的调用形式；[integrations/base.py](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/src/specify_cli/integrations/base.py?utm_source=gitcode_repo_files#L629-L643) 中 `replace_command_placeholders` 方法在针对不同 AI agent（按各自的 invoke 分隔符）注册命令时执行同样的替换，例如解析为 `/speckit.assess.shape` 或该 agent 对应的命令语法。这种设计的意义在于：命令文档是 agent 无关的模板，同一个 `define` 命令可以注册到 Claude Code、Copilot、Gemini 等数十种集成下，而跨阶段引用（"下一步运行 shape"）在每种 agent 下都渲染为正确的调用串。[specify_cli 包入口](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/src/specify_cli/__init__.py?utm_source=gitcode_repo_files#L153) 的文档字符串也说明了这一占位符解析机制。

## Guardrails：define 的五条硬约束

命令文档末尾的 Guardrails 是对前述所有规则的收束，也是评估"命令执行是否合规"的检查清单：

- **绝不修改源文件**——只读，写操作仅限 `.specify/assessments/<slug>/` 内部；
- **绝不滑入方案空间**——不谈特性、API、数据模型或任务；
- **绝不杜撰无 intake/research 支撑的用户、度量或目标**——必须标记 `[NEEDS CLARIFICATION: …]`；
- **绝不在未确认的情况下覆写已存在的 `problem.md`**；
- **若问题根本无法表述**，明确说出来，并建议重跑 `__SPECKIT_COMMAND_ASSESS_INTAKE__` 或 `__SPECKIT_COMMAND_ASSESS_RESEARCH__`，而不是硬凑一份陈述。

最后一条尤其体现漏斗思维：`define` 允许"定义不出来"作为合法输出，并指明回退路径（重跑上游阶段），而非强行产出工件——这与 README 中"杀死一个想法（或让评估退回澄清）是成功结果而非失败"的整体基调一致。

## 安装与扩展注册

`assess` 是随 spec-kit 捆绑的分发扩展，注册信息见 [extension.yml](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/extensions/assess/extension.yml?utm_source=gitcode_repo_files)：扩展 id 为 `assess`、版本 1.0.0、`requires.speckit_version: ">=0.9.0"`，`provides.commands` 声明了 intake/research/define/shape/decide 五个命令文件。安装方式：

```bash
specify extension add assess

可再随时禁用/启用：

specify extension disable assess
specify extension enable assess