workflow: add intake investigation gate
This commit is contained in:
parent
e752a7206a
commit
1143ae1c5a
|
|
@ -6,9 +6,11 @@ requires: []
|
|||
---
|
||||
# Ticket Intake Workflow
|
||||
|
||||
Yoi の multi-agent 運用で、ユーザーの依頼をいきなり実装委譲せず、まず **合意済み Ticket** に変換するための Workflow。
|
||||
Yoi の multi-agent 運用で、ユーザーの依頼をいきなり実装委譲せず、まず **合意済み Ticket** または「まだ Ticket 化しない」判断に変換するための Workflow。
|
||||
|
||||
Intake の目的は、ユーザーの意図・要件・制約・受け入れ条件・未決定点を明確にし、Orchestrator が次の routing を判断できる Ticket を作ることである。Intake は scheduler ではなく、coder / reviewer Pod を起動しない。
|
||||
この workspace workflow は bundled `resources/workflows/ticket-intake-workflow.md` を dogfooding 用に詳述した override である。Objective / split policy / local Ticket 運用の説明を追加するが、bundled workflow の調査ゲート、Ticket 作成前の user agreement、Intake の非 scheduler 境界を弱めてはならない。
|
||||
|
||||
Intake の目的は、ユーザーの意図・要件・制約・受け入れ条件・未決定点を明確にし、Orchestrator が次の routing を判断できる Ticket を作ることである。Intake は scheduler ではなく、coder / reviewer / read-only investigation helper Pod を起動しない。
|
||||
|
||||
## 位置づけ
|
||||
|
||||
|
|
@ -36,18 +38,19 @@ Intake は以下を行う。
|
|||
|
||||
- ユーザー依頼の主語と目的を確認する。
|
||||
- 既存 Ticket を確認し、duplicate / related work を探す。
|
||||
- 必要に応じて関連 docs / code / workflow / history を読む。
|
||||
- 曖昧な依頼、現在挙動への claim、authority boundary、workflow/source-of-truth 変更では、Ticket 化前の最小調査ゲートとして関連 docs / code / workflow / history を読む。
|
||||
- 不足している要件を質問する。
|
||||
- 作成または refinement する Ticket が、実装・レビュー・検証・完了判断を単独で行える concrete work item であるか確認する。
|
||||
- 広い依頼を分割する場合は、進捗コンテナとしての umbrella Ticket ではなく、concrete Ticket / Objective context / split decision record に責務を分ける。
|
||||
- Objective-to-Ticket links を提案する場合は canonical opaque Ticket ID だけを使い、dependency / blocking / ordering relation として扱わない。
|
||||
- Ticket の title / body/request snapshot / acceptance criteria / priority / readiness / risk flags を、現在の要件として意味がある範囲で提案する。
|
||||
- canonical ID は Ticket 作成/storage が opaque な path-derived value として割り当てるため、Intake はユーザー向け metadata として提案しない。
|
||||
- ユーザー主張、Intake が確認した事実、未確認仮説、未決定点を分けて整理する。
|
||||
- background / requirements / acceptance criteria / escalation conditions を整理する。
|
||||
- binding decisions / invariants と implementation latitude を分けて書く。
|
||||
- 具体的な除外や触れてはいけない境界が binding decision である場合は、generic な除外リストではなく invariant / escalation condition として明記する。
|
||||
- readiness / open questions / risk flags を明示する。
|
||||
- ユーザー合意後に Ticket を作成する。
|
||||
- ユーザー合意後にだけ official Ticket を作成する。
|
||||
- 既存 Ticket の refinement を求められた場合は、TicketComment で経緯を残す。
|
||||
|
||||
## Intake がしないこと
|
||||
|
|
@ -89,7 +92,7 @@ Ticket tools が利用できない環境では、勝手に file write で代替
|
|||
- 既に決まっていること。
|
||||
- まだ未決定のこと。
|
||||
|
||||
この段階では Ticket を作らない。
|
||||
この段階では Ticket を作らない。ユーザー発話は request snapshot / claim として扱い、確認済み requirements と混同しない。
|
||||
|
||||
### 2. 既存 Ticket を確認する
|
||||
|
||||
|
|
@ -104,6 +107,33 @@ Ticket tools が利用できない環境では、勝手に file write で代替
|
|||
|
||||
既存 Ticket の更新で足りる場合、新規 Ticket を作らず、ユーザーに更新案を提示する。
|
||||
|
||||
### 2.1. Ticket 化前の最小調査ゲート
|
||||
|
||||
`TicketCreate` または material な `TicketComment` の前に、以下の gate を通す。
|
||||
|
||||
必ず行うこと:
|
||||
|
||||
- duplicate / related / blocking-looking Ticket を確認する。
|
||||
- 既存 Ticket を更新するなら、その Ticket の item/thread/artifacts を読む。
|
||||
- ユーザー claim と、Intake が読んで確認した fact を分ける。
|
||||
|
||||
次のいずれかに当たる場合は、Ticket 作成前に関連 docs / code / workflow / prompt / config / history を読む。
|
||||
|
||||
- 依頼が曖昧、または複数の concrete work item を含む。
|
||||
- 「現在の挙動」「既存仕様」「壊れている」「既にある」など、事実確認を要する claim がある。
|
||||
- scope / permission / history / prompt context / persistence / public API など authority boundary に触れる。
|
||||
- prompt / workflow resource、Ticket schema、source-of-truth 境界の変更に触れる。
|
||||
- 既存実装の map がないと requirements / acceptance criteria を誤って固定しそうである。
|
||||
|
||||
Gate output は draft に以下を分けて残す。
|
||||
|
||||
- User claims / request snapshot: ユーザーが述べたこと。
|
||||
- Confirmed facts / sources: Intake が読んで確認したことと source。
|
||||
- Unverified hypotheses: ありそうだが未確認の推測。
|
||||
- Undecided points / open questions: ユーザーまたは Orchestrator の判断が必要なこと。
|
||||
|
||||
調査が大きい、current-code map がない、または仕様同期が足りない場合は、official Ticket を作らず draft で止める。readiness は `spike_needed` / `requirements_sync_needed` / `blocked` のいずれかを付け、次に必要な調査や質問を報告する。確認できない claim を requirements / acceptance criteria として保存しない。
|
||||
|
||||
### 2.5. Broad request の split policy
|
||||
|
||||
1つの依頼が複数の implementable work item を含む場合、Intake は以下を提案する。
|
||||
|
|
@ -121,6 +151,7 @@ Ticket tools が利用できない環境では、勝手に file write で代替
|
|||
|
||||
最低限、以下を確認する。
|
||||
|
||||
- ユーザー claim のうち、どれが確認済み fact で、どれが未確認仮説か。
|
||||
- observable な完了条件は何か。
|
||||
- 作業の種類・影響範囲は prose として body に書けばよいが、current Ticket core metadata として扱わない。
|
||||
- 受け入れ条件は何か。
|
||||
|
|
@ -130,7 +161,7 @@ Ticket tools が利用できない環境では、勝手に file write で代替
|
|||
- validation は何で確認できるか。
|
||||
- 人間判断が必要な論点は何か。
|
||||
|
||||
不足がある場合は、Ticket 作成前に質問する。質問は多すぎず、Ticket 作成に必要な最小限に絞る。
|
||||
不足がある場合は、Ticket 作成前に質問する。質問は多すぎず、Ticket 作成に必要な最小限に絞る。調査が先に必要な場合は `spike_needed`、仕様同期が先に必要な場合は `requirements_sync_needed` として draft に留める。
|
||||
|
||||
### 4. readiness を分類する
|
||||
|
||||
|
|
@ -145,9 +176,11 @@ implementation_ready:
|
|||
|
||||
requirements_sync_needed:
|
||||
- 目的は見えているが、仕様・用語・UX・責務境界・受け入れ条件が未同期。
|
||||
- ユーザー claim を requirements として固定するには合意や確認が足りない。
|
||||
|
||||
spike_needed:
|
||||
- 技術調査、依存関係、性能、license、diagnostics、現在コード map が先に必要。
|
||||
- どの files/workflows/Tickets を読むべきかは見えているが、Intake の最小調査では実装可能な要件まで確定できない。
|
||||
|
||||
blocked:
|
||||
- 人間判断、外部イベント、別 Ticket の完了が必要。
|
||||
|
|
@ -188,11 +221,16 @@ Title:
|
|||
|
||||
Priority:
|
||||
Readiness:
|
||||
Action required:
|
||||
Attention required:
|
||||
Next Ticket operation: draft_only | create_after_user_agreement | update_existing_after_user_agreement | no_ticket
|
||||
Risk flags:
|
||||
|
||||
Body / request snapshot:
|
||||
User claims / request snapshot:
|
||||
|
||||
Confirmed facts / sources:
|
||||
|
||||
Unverified hypotheses:
|
||||
|
||||
Undecided points / open questions:
|
||||
|
||||
Background:
|
||||
|
||||
|
|
@ -208,12 +246,12 @@ Escalation conditions:
|
|||
|
||||
Validation:
|
||||
|
||||
Related tickets/docs:
|
||||
Related tickets/docs/files:
|
||||
```
|
||||
|
||||
canonical ID は作成時に storage が opaque/path-derived value として割り当てるため、draft では提案しない。
|
||||
|
||||
この時点ではまだ Ticket を作らない。
|
||||
この時点ではまだ Ticket を作らない。`Next Ticket operation` が `draft_only` / `no_ticket` の場合は、ユーザー合意があっても `TicketCreate` ではなく追加同期または調査へ戻す。
|
||||
|
||||
### 7. ユーザー合意を取る
|
||||
|
||||
|
|
@ -222,7 +260,7 @@ canonical ID は作成時に storage が opaque/path-derived value として割
|
|||
- ユーザーが draft を明示的に承認する。
|
||||
- ユーザーが「作って」「切って」「記録して」など、作成を明示する。
|
||||
|
||||
未決定のまま記録する場合は、`requirements_sync_needed` / `spike_needed` / `blocked` として未決定点を明示する。
|
||||
未決定のまま記録する場合は、`requirements_sync_needed` / `spike_needed` / `blocked` として未決定点を明示する。ユーザー合意は「この未決定状態で記録する」ことへの合意であり、未確認仮説を requirements 化する許可ではない。
|
||||
|
||||
### 8. Ticket を作成または更新する
|
||||
|
||||
|
|
@ -231,6 +269,7 @@ canonical ID は作成時に storage が opaque/path-derived value として割
|
|||
- `TicketCreate` を使う。
|
||||
- title / priority / body と、必要な readiness / risk flags を指定する。canonical ID は storage が割り当てる。
|
||||
- body に readiness / open questions / risk flags と、binding decisions / invariants、implementation latitude、escalation conditions を Markdown で明記する。
|
||||
- user claims、confirmed facts、unverified hypotheses、undecided points / open questions を分けて書き、未確認 claim を requirements / acceptance criteria として保存しない。
|
||||
|
||||
既存 Ticket refinement の場合:
|
||||
|
||||
|
|
@ -253,6 +292,14 @@ Intake はここで止まる。implementation / worktree / coder / reviewer 起
|
|||
## Ticket body の推奨形
|
||||
|
||||
```markdown
|
||||
## User claims / request snapshot
|
||||
|
||||
## Confirmed facts / sources
|
||||
|
||||
## Unverified hypotheses
|
||||
|
||||
## Undecided points / open questions
|
||||
|
||||
## Background
|
||||
|
||||
## Requirements
|
||||
|
|
|
|||
|
|
@ -1,5 +1,11 @@
|
|||
You are the Ticket Intake role.
|
||||
|
||||
Keep role behavior here and treat the first committed user message as concrete Ticket/action context only. Clarify ambiguous user requests, create or update the appropriate Ticket through typed Ticket tools, and leave implementation side effects to the user/Orchestrator queue flow. Durable Ticket item/thread/resolution text should follow the configured worker language unless a Ticket-specific record language instruction is supplied by the host/environment.
|
||||
Keep role behavior here and treat the first committed user message as concrete Ticket/action context only. Clarify ambiguous user requests and turn agreed work into typed Ticket records, but do not rush from a user claim to `TicketCreate`. Before creating an official Ticket or making a material refinement, pass a minimum investigation gate: check existing Tickets for duplicates/related work, read any targeted Ticket before updating it, and inspect relevant workflow/prompt/docs/code files when the request is ambiguous, claims current behavior, touches authority/scope/history/prompt boundaries, or depends on existing implementation details.
|
||||
|
||||
In drafts and Ticket bodies, separate user claims/request snapshot, confirmed facts with sources, unverified hypotheses, and undecided points/open questions. Do not save all user claims as requirements or acceptance criteria. If the gate cannot be satisfied with available context, stop at a draft and classify the next step as `requirements_sync_needed`, `spike_needed`, or `blocked` instead of creating an official Ticket.
|
||||
|
||||
Create or update Tickets only after user agreement or an explicit user instruction to record the agreed draft. Durable Ticket item/thread/resolution text should follow the configured worker language unless a Ticket-specific record language instruction is supplied by the host/environment.
|
||||
|
||||
Intake is not a scheduler. Do not spawn coder/reviewer/read-only investigation helper Pods, create implementation worktrees, route implementation/review, merge, close, or perform implementation side effects; leave those to the user/Orchestrator queue flow.
|
||||
|
||||
When a workflow is invoked, follow that workflow as the procedural authority. Do not infer requirements from a Ticket id or title alone; read the relevant Ticket record before updating it.
|
||||
|
|
|
|||
|
|
@ -4,11 +4,125 @@ model_invokation: true
|
|||
user_invocable: true
|
||||
requires: [workflow-resource-boundary]
|
||||
---
|
||||
# Ticket Intake Workflow
|
||||
|
||||
# Ticket intake workflow
|
||||
この bundled workflow は reusable な最小 Intake 手順である。Workspace override は dogfooding 固有の Ticket/Objective/split policy 例を追加してよいが、この workflow の調査ゲート、Ticket 作成前の user agreement、Intake の非 scheduler 境界を弱めてはならない。
|
||||
|
||||
1. ユーザー依頼と既存 Ticket を同期し、重複作成を避ける。既存 Ticket を対象にする場合は body/thread/artifacts を読んでから更新する。
|
||||
2. 要件・背景・受け入れ条件・未決事項を Ticket に記録する。実装手順は必要になるまで増やしすぎない。
|
||||
3. Ticket が queue 可能な粒度と明確さになったら、typed Ticket tool surface で intake summary を残し、`state = ready` にする。未決事項がある場合は planning に留め、必要な質問やリスクを明示する。
|
||||
4. Handoff report は `created_or_updated_ticket_id`、`state`、`open_questions_or_risk_flags`、`intake_summary` を含める。
|
||||
5. Intake は実装を開始しない。ユーザーが panel 等で `ready -> queued` し、Orchestrator が queued Ticket を routing する。
|
||||
Intake の目的は、曖昧な依頼をいきなり実装委譲せず、Orchestrator が routing できる合意済み Ticket または「まだ Ticket 化しない」判断に変換することである。
|
||||
|
||||
## 境界
|
||||
|
||||
Intake は以下をしない。
|
||||
|
||||
- coder / reviewer / read-only investigation helper Pod を起動しない。
|
||||
- implementation worktree を作らない。
|
||||
- implementation / review routing、merge、close、branch cleanup をしない。
|
||||
- unattended scheduler として自動実行しない。
|
||||
- ユーザー合意なしに official Ticket を作らない。
|
||||
|
||||
## Ticket 化前の最小調査ゲート
|
||||
|
||||
`TicketCreate` または material な `TicketComment` の前に、必要最小限の調査を行う。
|
||||
|
||||
必ず行うこと:
|
||||
|
||||
- `TicketList` / `TicketShow` で duplicate / related / blocking-looking work を確認する。
|
||||
- 既存 Ticket を更新する場合は、その Ticket の item/thread を読む。
|
||||
|
||||
次のいずれかに当たる場合は、Ticket 作成前に関連 workflow / prompt / docs / code / config を読む。
|
||||
|
||||
- ユーザー依頼が曖昧、または複数の concrete work item を含む。
|
||||
- 「現在の挙動」「既存仕様」「壊れている」「既にある」など、事実確認を要する claim がある。
|
||||
- scope / permission / history / prompt context / persistence / public API など authority boundary に触れる。
|
||||
- 既存 workflow/resource/file の文言変更や source-of-truth 境界に触れる。
|
||||
|
||||
調査結果は draft で分けて書く。
|
||||
|
||||
- User claims / request snapshot: ユーザーが述べたこと。
|
||||
- Confirmed facts / sources: Intake が読んで確認したことと source。
|
||||
- Unverified hypotheses: ありそうだが未確認の推測。
|
||||
- Undecided points / open questions: ユーザーまたは Orchestrator の判断が必要なこと。
|
||||
|
||||
確認できない claim を requirements / acceptance criteria として保存しない。必要な調査が大きい、current-code map がない、または仕様同期が足りない場合は、official Ticket を作らず draft で止め、readiness を `spike_needed` / `requirements_sync_needed` / `blocked` として報告する。
|
||||
|
||||
## 手順
|
||||
|
||||
1. 依頼を短く言い換え、目的、影響範囲、既決事項、未決定点を分ける。この段階では Ticket を作らない。
|
||||
2. Ticket 化前の最小調査ゲートを実施する。
|
||||
3. 要件を同期する。少なくとも observable な完了条件、受け入れ条件、binding decisions / invariants、implementation latitude、validation、escalation conditions を確認する。
|
||||
4. readiness を分類する。
|
||||
|
||||
```text
|
||||
implementation_ready:
|
||||
- 意図、受け入れ条件、binding decisions / invariants、implementation latitude、reviewer 判断基準、validation が明確。
|
||||
|
||||
requirements_sync_needed:
|
||||
- 目的は見えているが、仕様・用語・UX・責務境界・受け入れ条件が未同期。
|
||||
|
||||
spike_needed:
|
||||
- 技術調査、依存関係、性能、license、diagnostics、現在コード map が先に必要。
|
||||
|
||||
blocked:
|
||||
- 人間判断、外部イベント、別 Ticket の完了が必要。
|
||||
```
|
||||
|
||||
5. 作成前 draft を提示する。
|
||||
|
||||
```text
|
||||
Title:
|
||||
Priority:
|
||||
Readiness:
|
||||
Next Ticket operation: draft_only | create_after_user_agreement | update_existing_after_user_agreement | no_ticket
|
||||
Risk flags:
|
||||
|
||||
User claims / request snapshot:
|
||||
Confirmed facts / sources:
|
||||
Unverified hypotheses:
|
||||
Undecided points / open questions:
|
||||
|
||||
Background:
|
||||
Requirements:
|
||||
Acceptance criteria:
|
||||
Binding decisions / invariants:
|
||||
Implementation latitude:
|
||||
Escalation conditions:
|
||||
Validation:
|
||||
Related tickets/docs/files:
|
||||
```
|
||||
|
||||
6. ユーザーの明示承認、または「作って」「切って」「記録して」など official record 作成の明示指示を待つ。
|
||||
7. 合意後だけ `TicketCreate` / `TicketComment` を使う。canonical ID は storage が割り当てるため draft では提案しない。
|
||||
8. 作成/更新後は id/title、readiness、open questions/risk flags、次の Orchestrator routing 候補を報告して止まる。
|
||||
|
||||
## 推奨 Ticket body
|
||||
|
||||
```markdown
|
||||
## User claims / request snapshot
|
||||
|
||||
## Confirmed facts / sources
|
||||
|
||||
## Unverified hypotheses
|
||||
|
||||
## Undecided points / open questions
|
||||
|
||||
## Background
|
||||
|
||||
## Requirements
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
## Binding decisions / invariants
|
||||
|
||||
## Implementation latitude
|
||||
|
||||
## Readiness
|
||||
|
||||
- readiness: implementation_ready | requirements_sync_needed | spike_needed | blocked | unspecified
|
||||
- risk_flags: [...]
|
||||
|
||||
## Escalation conditions
|
||||
|
||||
## Validation
|
||||
|
||||
## Related work
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user