capture-work-items

技能（Skill）：捕获工作项

目的 (Purpose)

从自由格式的输入中捕获需求、错误或问题，并将其转化为结构化、持久性的产品。提供快速结构化记录，无需“分析需求”执行的深度验证。将输出路径与项目文档结构（例如项目文档模板）保持一致，并包括治理状态跟踪。

---

核心目标（Core Objective）

首要目标：将用户提供的需求、错误或问题描述转换为具有所有必填字段的结构化工作项，并将其保留到项目约定路径中。

成功标准（必须满足所有要求）：

1. ✅ 已识别的类型：分类为需求、错误或问题的工作项
2. ✅ 必填字段完成：该类型的所有必填字段均已填写（无推断；缺失时询问用户）
3. ✅ 状态设置：前面的初始状态：已捕获
4. ✅ strategic_goal_id 已标：每个工作项必填 strategic_goal_id，映射到项目 strategic-goals 中的某一目标（依据 ADR 20260417-unified-value-driven-prioritization-model 决策 3.4）
5. ✅ priority 标为 unset：新建工作项 frontmatter 必含 priority: unset，等待 prioritize-backlog 批量评分
6. ✅ 检测到的路径：根据项目文档结构选择的输出路径（请参阅路径检测）
7. ✅ 工件持久化：工作项写入所选路径
8. ✅ 用户确认：用户明确确认或委托写入
9. ✅ 批量捕获后建议优先级评分：批量捕获结束时，统计未评分 backlog 总数并建议（不自动执行）运行 prioritize-backlog

验收测试：某人或下游系统是否可以阅读产品并理解完整的工作项目并在不提出澄清问题的情况下采取行动？

---

范围边界（范围边界）

本技能负责：

• 自由格式输入 → 结构化工作项
• 单次或批量捕获（批量：按项目或批次确认）
• 输出到项目约定路径下的本地 Markdown
• 状态生命周期：仅限初始“已捕获”（下游更新“分类”、“进行中”、“完成”、“阻止”、“取消”）

本技能不负责：

• 深入需求澄清或验证 → 使用“分析需求”
• 设计或建筑 → 使用“设计解决方案”
• 直接 API 调用 Zentao/GitHub 以创建问题（扩展点；v1 不需要）

转交点：当产品被持久化并且用户确认后，如果项目需要更深入的验证，则移交给“分析需求”，或者移交给流程管理/里程碑进行规划。

---

使用场景（用例）

• 快速待办条目：用户说“记录此错误”或“添加此要求” - 结构并持续，无需全面分析。
• 会议/电子邮件捕获：从会议记录或电子邮件中提取工作项目并保存为结构化产品。
• 分类输入：捕获项目以供以后在里程碑或任务分解中进行分类和优先级排序。
• 积压证据：填补评估文档中确定的积压差距（例如“积压：弱 - 没有明确的待办文档”）。

---

行为（行为）

交互（互动）政策

• 默认：项目规范或规格/产品合同的路径；从输入中键入
• 选择选项：一次一个缺失字段的问题；在适用时提供选择
• 确认：与默认路径不同时的目标路径；用户在写入前确认

1. 按 §8.2 发现顺序解析项目规范 → 确定 backlog-item 的 path_pattern（默认：docs/process-management/project-board/backlog/YYYY-MM-DD-{slug}.md 或 fallback docs/backlog/YYYY-MM-DD-{slug}.md；项目可覆盖为聚合式）
2. 按 §8.3 占位符语法替换；未解析占位符按 §8.6 追问用户
3. 若调用方 frontmatter 输入含 upstream_ref（应指向上游 roadmap 条目或 requirement）：在产出制品的 frontmatter emit parent: <upstream_ref>
4. 记录 resolved_path + frontmatter 增量供后续写入使用

注：默认情况保留 §3 路径检测逻辑（docs/process-management/ 存在否决定 canonical vs fallback），但若项目在 ARTIFACT_NORMS.md 声明了显式 path_pattern，以项目声明为准。

路径检测

使用解析规范（或合同默认值）选择输出路径：

状况	输出路径
docs/process-management/ 存在	docs/process-management/project-board/待办/YYYY-MM-DD-<slug>.md
否则	docs/待办/YYYY-MM-DD-<slug>.md

如果子目录不存在，则创建它们。今天使用“YYYY-MM-DD”； <slug> 是标题中的 kebab-case。

第 0 阶段：分类 — 识别类型

开始时宣布：“我正在使用捕获工作项技能来记录此工作项。”

将输入分类为：

• 要求：新需求、功能请求或增强
• bug：缺陷、不正确的行为、未能满足规范
• 问题：任务、改进或问题（通用工作项）

第 1 阶段：提取 — 识别字段

从输入中提取可用字段。按类型划分的必填字段：

类型	必填字段
要求	标题、问题/需求、验收标准、strategic_goal_id
错误	标题、描述、重现步骤、预期与实际、严重性、strategic_goal_id
问题	标题、描述、类型（任务|改进|问题）、strategic_goal_id

strategic_goal_id 说明：

• 读取 docs/project-overview/strategic-goals.md，呈现可选目标列表给用户
• 用户选择该工作项主要服务于哪个战略目标
• 若 strategic-goals.md 不存在 → halt，建议先运行 design-strategic-goals
• Bug / 技术债类工作项通常映射到"工程 / 治理健康"目标（依据 ADR 1 决策 3.5）

第 2 阶段：提示 — 填写缺少的必填字段

对于任何缺少的必填字段，请询问用户一次一个问题。不要推断或猜测。

第 3 阶段：坚持 — 编写工件

1. 运行“解决项目规范”，然后运行“路径检测”（见上文）
2. 如果目标路径与默认路径不同，请与用户确认
3. 使用适当的模板使用 YAML front-matter 编写 Markdown（请参阅输出模板）
4. 在 front-matter 中设置 status: capture

第 4 阶段：确认

与用户确认产品已编写且完整。除非用户明确请求，否则不要提交版本控制。

第 5 阶段：建议批量评分（不自动执行）

捕获结束时（单项或批量），执行以下 suggest 动作：

1. 扫描 backlog 目录，统计 priority: unset 的条目总数
2. 若 ≥ 阈值（默认 ≥ 3）或本次批量捕获 ≥ 2 项，则输出建议：

   "Backlog 当前有 N 个未定优先级的条目。建议在下次 planning 前运行 prioritize-backlog 批量评分。此技能不会自动调用 —— 由用户决定时机（批量评分在有对照组时质量更高）。"

3. 不自动执行 prioritize-backlog（理由见 ADR 2 决策 3.7.1：两技能节律不同，强行链式破坏评分质量）

---

输入与输出 (Input & Output)

输入（输入）

• 用户的需求、错误或问题的原始描述
• 可选：项目上下文（用于路径检测的现有“docs/”结构）

输出（输出）

带有 YAML front-matter 的结构化工作项 Markdown 文件。模板如下。

需求模板

---
artifact_type: backlog-item
created_by: capture-work-items
lifecycle: living
type: requirement
date: YYYY-MM-DD
status: captured
priority: unset
strategic_goal_id: [goal-N]
source: [user|meeting|email]
trace_id: optional
---

# [Title]

## Problem / Need
[Who has what problem; no solution language]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Notes
[Optional]

错误模板

---
artifact_type: backlog-item
created_by: capture-work-items
lifecycle: living
type: bug
date: YYYY-MM-DD
status: captured
priority: unset
strategic_goal_id: [goal-N]
severity: [critical|major|minor]
---

# [Title]

## Description
[What goes wrong]

## Steps to Reproduce
1. ...
2. ...

## Expected vs Actual
- **Expected**: ...
- **Actual**: ...

## Environment
[Optional]

问题模板

---
artifact_type: backlog-item
created_by: capture-work-items
lifecycle: living
type: issue
subtype: [task|improvement|question]
date: YYYY-MM-DD
status: captured
priority: unset
strategic_goal_id: [goal-N]
---

# [Title]

## Description
[Content]

状态生命周期

该技能仅设置“状态：捕获”。下游流程（里程碑、升级迭代任务、运行检查点）可能会更新为：“分类”、“进行中”、“完成”、“阻止”、“取消”。

---

限制（限制）

ハードバウンダリー（Hard Boundaries）

• 必須フィールドをスキップしない：必須フィールドを推測できない場合は、ユーザーに確認してください。空欄のままにしないでください。
• strategic_goal_id をスキップしない：strategic-goals.md が存在しない場合は halt し、先に design-strategic-goals を実行するよう提案してください。空欄のままにしたり、推測したりしてはいけません。
• prioritize-backlog を自動実行しない：キャプチャの終了時には提案だけを行い、いつまとめてスコアリングするかはユーザーに決めてもらってください（実施のリズムは異なり、個別のスコアリングでは実態を反映できません）。
• No diagnostic flow：診断ステート（RA0–RA5）を実行しないでください。入力内容が非常に曖昧な場合は、まずキャプチャを提案し、意図を確認してから詳しく明確化してください。
• 書き込み前にパスを確認する：既存のファイルを上書きしないようにしてください。出力先のパスが明確でない場合は確認してください。
• パスはプロジェクト構造に従う：パス検出ルールを使用してください。単一のパスをハードコードしないでください。

スキルの境界（Skill Boundaries）（重複を避ける）

次のことは行わないでください（他のスキルが対応できます）：

• 要件の詳細な検証：診断ステート、問題の明確化、スコープの境界設定 →「要件の分析」を使用
• 設計とアーキテクチャ：解決策、代替案、トレードオフ →「解決策の設計」を使用
• タスクの分解：エピック／タスクの分解、受け入れ基準の詳細化 → プロセス管理または実装計画を使用

停止して引き継ぐタイミング：

• ユーザーが「もっと分析が必要です」と言った場合 →「要件の分析」に引き継ぐ
• ユーザーが「これを設計してください」と言った場合 →「解決策の設計」に引き継ぐ
• 成果物が保持され、確認された場合 → 引き継ぎ完了

---

セルフチェック（Self-Check）

中核となる成功基準（すべて満たす必要があります）

• タイプを特定済み：作業項目が要件、バグ、または問題である
• 必須フィールドを入力済み：すべての必須フィールドが入力されている（推測なし）
• strategic_goal_id を指定済み：strategic-goals 内の具体的な目標にマッピングされている
• priority が unset：frontmatter に priority: unset が含まれている
• ステータスを設定済み：前述の内容に「ステータス：キャプチャ済み」とある
• パスを検出済み：出力パスがパス検出ルールに従っている
• 成果物を保持済み：ファイルが選択したパスに書き込まれている
• ユーザーが確認済み：ユーザーが書き込みを確認または委任している
• 一括スコアリングを提案済み：一括処理の場合、ユーザーに prioritize-backlog の実行を提案している（ただし自動実行はしていない）

プロセス品質チェック

• 質問は一度に1つ：不足している複数のフィールドについて質問して、ユーザーを困惑させていない
• 要件に解決策の表現が含まれていない：問題／要件では実装方法ではなく、問題を説明している
• パスの作成：必要に応じて待办/サブディレクトリを作成している
• ファイル名の規則：YYYY-MM-DD-{slug}.md を使用している

受け入れテスト

ある人または下流システムが、プロダクトを読み、作業項目の全容を理解し、確認質問をせずに対応できますか？

いいえの場合：必須フィールドが不完全です。プロンプトの段階に戻ってください。

はいの場合：キャプチャ完了です。必要に応じて引き継いでください。

---

例（例）

例 1：バグのキャプチャ

ユーザー：「パスワードフィールドに特殊文字を使うと、ログインページに 500 が表示されます。」

エージェントの宣言：「作業項目を記録するため、作業項目のキャプチャスキルを使用します。」

分類：バグとして分類。

抽出：タイトルと説明はあります。再現手順、期待される結果と実際の結果、重大度が不足しています。

質問（一度に1つ）：

エージェント：「これを再現するための具体的な手順は何ですか？」

ユーザー：「1. /login に移動する 2. 任意のユーザー名を入力する 3. @ または # を含むパスワードを入力する 4. 「ログイン」をクリックする」

エージェント：「期待した結果と実際に起きたことは、どのように異なりますか？」

ユーザー：「期待：正常にログインするか、認証エラーが表示される。実際：500 内部サーバーエラー。」

エージェント：「重大度は、クリティカル、メジャー、マイナーのどれにしますか？」

ユーザー：「メジャー。」

保持：パスを検出しました - docs/process-management/ が存在します。「docs/process-management/project-board/待办/2026-03-06-login-500-special-chars.md」に書き込みます。

確認：「書き込みました。内容を調整しますか、それとも分類に引き継ぎますか？」

例 2：要件のキャプチャ — 曖昧な入力

ユーザー：「もっと良いエラーメッセージが必要です。」

エージェントの宣言：「作業項目を記録するため、作業項目のキャプチャスキルを使用します。」

分類：要件として分類（問題の可能性もありますが、エージェントはデフォルトの「必要」に基づいて要件を選択）。

抽出：タイトルは推測できます（「もっと良いエラーメッセージ」）。問題／要件と受け入れ基準が不足しています。

質問：

エージェント：「誰がこの問題に遭遇していますか？現在のエラーメッセージの何が具体的に問題ですか？」

ユーザー：「当社の API ユーザーには、対処に役立つ情報のない一般的な「問題が発生しました」というメッセージが表示されます。」

エージェント：「「完了」とはどのような状態ですか？具体的な受け入れ基準を少なくとも1つ教えてください。」

ユーザー：「エラーレスポンスには、コード（例：ERR_001）と、発生した問題を説明する短くて人間が読めるメッセージを含める必要があります。」

保持：パスを検出しました - docs/process-management/ は存在しません。「docs/待办/2026-03-06-better-error-messages.md」に書き込みます。

引き継ぎの提案：「この件は、要件の分析による詳細な検証が役立つ可能性があります。キャプチャのみを続けますか、それとも包括的な分析に引き継ぎますか？」

ユーザー：「ひとまずキャプチャだけでお願いします。」

確認：「書き込みました。準備ができたらトリアージに引き継いでください。」

例 3：問題のキャプチャ — エッジケース（1つのメッセージに複数の項目が含まれる場合）

ユーザー：「2つあります。1）README のインストールセクションを更新する。2）CONTRIBUTING.md を追加する。」

エージェントの宣言：「作業項目のキャプチャスキルを使用します。個別の作業項目が2つあります。1つずつキャプチャします。」

項目 1 — タイプ：問題（タスク）。タイトル：「README のインストールセクションを更新する」。説明：コンテキストから取得。2026-03-06-update-readme-install.md として保持。

項目 2 — タイプ：問題（タスク）。タイトル：「CONTRIBUTING.md を追加する」。説明：コンテキストから取得。2026-03-06-add-contributing.md として保持。

確認：「2つの項目をキャプチャしました。必要に応じて確認し、調整してください。」