incu-way-po

プロダクトオーナーシッププロセス

生のニーズを、1つ以上の開発着手可能なチケットに変える、ゲート主導のワークフローです。各チケットは、実際のコードベースに照らして検証されます。何が可能で何が不可能か、どこに影響するか、どの点で人間の判断がまだ必要かを確認します。目的は、未解決の質問への回答を、incu-way-development または incu-way-bugs の開始後ではなく、開始前に得ることです。

このフローは、開発フローの上流に位置します。

raw need ──▶ incu-way-po ──▶ TICKET.md (Ready) ──▶ incu-way-development (Phase 0 consumes it)
                                                └▶ incu-way-bugs (for defect-shaped items)

これは分析フローです。incu-way-docs や各種評価と同様に、.ways/state.json は管理しません。要件ドキュメントを作成し、コードは一切書きません。出力先は docs/requirements/{slug}/TICKET.md です。チケットごとに1つのフォルダーを作成し、そのチケットのスラッグは開発開始時に PRD のスラッグになるよう設計されています。

ニーズに合わせて規模を調整してください。単一リポジトリ内の小さな変更であれば、短い実現可能性の確認と1件のチケットで十分です。探索プロジェクトにする必要はありません。調査の深さは、曖昧さと影響範囲に応じて決めます。

---

リポジトリの対象可否チェック（何よりも先に実施）

Phase 0 の前に、現在のリポジトリについて ~/.ways/config.yaml の blacklist（形式：常時インストールされる incu-base の global-config ルール）を確認します。一致する場合は、このリポジトリが incu-way のブラックリストに登録されていることをユーザーに伝え、今回限りの例外として続行するか、停止するかを尋ねます。回答があるまで、どのフェーズも実行しないでください。ファイルがない場合、または一致しない場合は、通常どおり続行します。

---

Phase 0 — 受付と実現可能性の調査（読み取り専用）

目標： 何が可能で何が不可能か、何を人間が判断する必要があるかを説明できるよう、ニーズとコードの実態を十分に理解します。このフェーズではファイルを一切作成しません。

受付

1. ニーズをプロダクトの観点から把握します。
   • どのような問題を解決するのか、誰がその問題を感じているのか
   • クライアントまたはステークホルダーが期待する成果
   • すでに判明している制約と対象外事項
   • 成功をどのように測定するか
2. 既存のプロダクトコンテキストを確認します。PRD.md、docs/、docs/requirements/ 内の過去のチケット、docs/prds/ 内の関連 PRD を読みます。

影響を受けるリポジトリの特定

3. このプロダクトの対象リポジトリをユーザーに尋ねるか、ハブリポジトリの CLAUDE.md に repos: セクションがあれば、そこからリポジトリの一覧を読み取ります。この一覧が存在する場合は常に優先します。プロダクトとともにバージョン管理されているためです。repos: セクションがない場合は、~/.ways/config.yaml の linkedRepos（形式：常時インストールされる incu-base の global-config ルール）を参照します。該当する場合は、現在のリポジトリを含むグループを探し、ユーザーから別の指示がない限り、そのほかのメンバーを対象として扱います。単一リポジトリのプロダクトでは簡単ですが、複数リポジトリにまたがるプロダクト（例：ウェブアプリ＋API＋ワーカー）では、調査の前にニーズが影響する可能性のあるすべてのリポジトリを列挙します。

実現可能性の確認（リポジトリごとにコードに基づいて実施）

4. 対象となる各リポジトリを読み取り専用で調査します。ニーズに関連する現在の動作、影響を受ける可能性のあるモジュール、エントリーポイント、統合、維持すべき既存のパターンを確認します。
5. 実現可能性の全体像を、repo:path:line で追跡できる形で記録します。推測で補ってはいけません。
   • 現在のシステムがすでにサポートしていること
   • 妥当な労力で実現可能なこと
   • より大規模な変更なしには実現できないこと（およびその理由）
   • 変更されるリポジトリ間の契約：API、イベント、スキーマ、共有パッケージなど。また、それに伴うリポジトリ間の変更順序に関する制約
6. 未知の事項はすべて明示的な未解決の質問として記録し、決して仮定として扱いません。それぞれにタグを付け、現時点でユーザーまたはステークホルダーへの確認が必要か、追加調査で解決できるかを示します。

フェーズ 0 の終了基準

ゲート 1 に進む前に、Claude が次の内容を説明できる状態にします。

• 問題と期待される結果を、プロダクトの観点から
• 影響を受ける可能性が高いリポジトリとモジュール
• 実現可能性の全体像：現時点で対応可能／実現可能／大規模な作業なしでは不可能
• リポジトリ間の契約変更とその順序に関する制約（複数リポジトリにまたがるニーズ）
• 未解決の質問と、それぞれの解決担当者

名前や README の記述から動作を推測しないでください。コードから明らかでない場合は、仮定ではなく未解決の質問として扱います。

---

ゲート 1 — スコープとチケット分割

チケットを書く前に、次の内容を提案します。

## Proposed scope and split

- **Need:** {one-line restatement}
- **In scope / out of scope:** {explicit}
- **Ticket split:** {one ticket, or several — per repo, per increment, or feature vs bug —
  each independently deliverable, with slugs and dependency order}
- **Feasibility summary:** {supported today / possible / not possible without larger work}
- **Open questions needing you now:** {list}
- **Open questions I can still resolve by survey:** {list}

• 次のように確認します：「これは {need} に対して提案するスコープとチケット分割です。チケットを作成する前に確認してください。」
• 停止します。ユーザーがスコープと分割を確認するまで、チケットを作成しないでください。

---

分離環境の準備（ゲート 1 の後）

ファイルを書く前に、作業をどのように分離するかユーザーに確認します。

現在のチェックアウトで新しいブランチを作成して作業しますか？それとも、別の git worktree を作成しますか？

ユーザーの回答に従ってください。 質問した後は停止し、ユーザーが選択するまでブランチや worktree を作成しないでください。

現在のチェックアウトに未コミットの変更がある場合は、ブランチの切り替えや worktree の作成を行う前に停止し、確認してください。

ニーズが複数のリポジトリにまたがる場合でも、チケットはプロダクトのハブリポジトリ（docs/ を所有するリポジトリ）に作成します。調査中に他のリポジトリを参照することはありますが、それらに書き込みは行いません。

オプション A — 現在のチェックアウトでブランチを作成

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c po/{slug}

オプション B — 別の worktree

worktree は .worktrees/ の下にのみ作成します。パスをユーザーに尋ねないでください。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/po-{slug} -b po/{slug} origin/develop

ここでの {slug} はニーズのスラッグです（例：po/contact-export）。すべての出力は選択した作業場所内に書き込みます。develop や main に直接ファイルを書き込まないでください。

フェーズ 2 — チケットのドラフトを作成する

目標： 承認された分割に基づき、チケットごとに 1 つの docs/requirements/{ticket-slug}/TICKET.md を作成します。

スラッグ形式： {zero-padded-id}-{kebab-ticket-name}（例：004-contact-export-api）。 開発で着手するときにチケットのスラッグが PRD のスラッグになるため、両方の名前空間で一意である必要があります。

次の ID を見つける — このチェックアウトだけでなく、すでに使われている可能性のある場所をすべて確認してください。 現在のブランチだけを確認するカウンターでは、2 つのニーズを並行して作業した瞬間に衝突します。同じベースから分岐した 2 つのワークツリー／ブランチがそれぞれ独立して同じ「次の」番号を計算する場合も同様で、実際にこの問題は発生しています。スキャンだけでは解決しません。2 つのエージェントが同時にスキャンし、同じ番号を計算した後で、それぞれのディレクトリを作成する可能性があるためです。同じマシン上でこれを防ぐには、スキャンから予約までの間、ロックを保持してください。

0. スキャンを開始する前に、同じマシン上のロックを取得します：

   LOCK="$(git rev-parse --git-common-dir)/incu-way-prd-slug.lock"
   until mkdir "$LOCK" 2>/dev/null; do sleep 0.2; done
   trap 'rmdir "$LOCK"' EXIT
   

   mkdir が同時に成功するプロセスは 1 つだけです。また、--git-common-dir はこのリポジトリのすべてのワークツリーで同じ共有パスに解決されるため、ロックはワークツリー間で確認できます。このロックは incu-way-development と共有されます（incu-way-prd-slug.lock、同じ ID 空間：docs/requirements/ + docs/prds/）。incu-way-bugs とは共有されません。
1. このチェックアウトの docs/requirements/ と docs/prds/ ですでに使われている ID を一覧表示します。
2. このリポジトリのほかのすべてのワークツリー（git worktree list）を一覧表示し、それらの docs/requirements/ と docs/prds/ も読み取ります。兄弟ワークツリーのチケットは、ここでの git status には表示されませんが、ディスク上には存在します。
3. デフォルトブランチをフェッチし（git fetch origin {default}）、すでにマージされているものを一覧表示します（git ls-tree --name-only origin/{default} -- docs/requirements/ docs/prds/）。このブランチの作成後に別の人がマージした ID は、まだローカルツリーに存在しません。

3 つすべてで見つかった ID の最大値より 1 つ大きい ID を使い、ロックを解放する前にすぐに docs/requirements/{id}-{slug}/ を作成してください（空のプレースホルダーファイルだけでも予約できます）。その後にのみロックを解放します（上記の trap が失敗時を含めて自動的に処理します）。スキャンだけではなく、ロックを保持したまま行うこの予約によって、同じマシン上での競合を実際に防げます。

TICKET.md の構成

# Ticket — {title}

## Status
Draft | In Review | Ready | Handed off

## Problem / outcome
What pain, for whom, what changes when it ships.

## Scope
In / out. Explicit non-goals.

## Feasibility notes
What the codebase already supports, what this requires, what is not possible without
larger work — each point traceable to `repo:path:line`.

## Affected repositories / modules
| Repo | Modules touched | Nature of change (code / contract / config) |
|------|-----------------|----------------------------------------------|

## Cross-repo dependencies
API/event/schema contracts that change, and the ordering constraints between tickets
or repos. "None" for single-repo tickets.

## Acceptance criteria
Numbered, concrete, testable. These become the PRD's functional requirements.

## Risks / assumptions
Explicitly labeled; every assumption must be confirmed or promoted to an open question.

## Open questions
Must be empty — or every remaining item explicitly marked "deferred, accepted by {who}"
— before the ticket can be marked Ready.

## Suggested flow
incu-way-development | incu-way-bugs (with the suggested slug)

ドラフト作成ルール（必須）

• 追跡可能であること。 実現可能性に関するすべての主張には repo:path:line を引用します。引用できない場合は未解決の質問として扱います。
• テスト可能であること。 すべての受け入れ基準は、テストにできるほど具体的である必要があります。
• 創作しないこと。 Gate 1 でユーザーが述べていない、または確認していない要件、スコープ、受け入れ基準を追加しないでください。
• 複数リポジトリにまたがる場合は明記すること。 複数リポジトリにまたがるニーズについては、契約の変更と順序の制約をチケットに記載し、Claude の頭の中だけに留めないでください。

---

ゲート 2 — Ready の定義レビュー

各チケットについて、Ready の定義チェックリストを提示します。

• 問題と成果がプロダクトの観点から記載されている

• スコープと対象外事項が明確である

• 実際のコードに基づいて実現可能性が検証されている（追跡可能である）

• 影響を受けるリポジトリ／モジュールが特定され、リポジトリ間の契約が識別されている

• 受け入れ基準が具体的でテスト可能である

• 未解決の質問が解決されているか、ユーザーの了承を得て明示的に先送りされている

• 次のように伝えます：「チケットは docs/requirements/{slug}/ にあります。レビュー用に Ready の定義チェックリストを含めています。」

• 停止します。ユーザーのレビューを待ちます。

未解決の項目が「未解決の質問」セクションに残っている間、チケットをこのゲートから Ready の状態で進めることはできません。ここで繰り返し対応してください。質問の解決によって分割、実現可能性に関する記載、受け入れ基準が変わる可能性があります。ユーザーが各チケットを Ready とするか、先送りする項目を明示的に了承するまで続けます。

---

フェーズ 3 — 引き継ぎ

Gate 2 でユーザーが承認したら：

• 各チケットのステータスを Ready に更新します。
• Jira との同期（任意、ユーザーが要求した場合のみ）： ユーザーから明示的な依頼（例： 「Jira チケットを作成して」「これを Jira に同期して」）があった場合に限り、Atlassian MCP ツールを使って TICKET.md から Jira の課題を作成または更新し、課題キーをチケットに記録します。 明示的な依頼がない限り、Jira の課題を作成、更新、またはトランジションしてはいけません。これは incu-way-prepare-pr が git への永続化に適用する考え方と同じです。
• 次のステップを案内します。各チケットの 推奨フロー を示してください。incu-way-development（または incu-way-bugs）が開始すると、そのフェーズ 0 で TICKET.md を読み込み、受け入れ条件を機能要件の出発点として扱います。

---

Gate 3 — PR

incu-way-prepare-pr を呼び出して po/{slug} をプッシュし、develop 宛てに PR を作成するよう提案します。 自分でプッシュしたり、PR を作成したりしてはいけません。

incu-way-prepare-pr で使用する PR のタイトルと本文の案：

Title: po({slug}): {short need name}

PR 本文には以下を含める必要があります：

• 必要性： 問題と期待される結果。
• チケット： docs/requirements/{slug}/TICKET.md ファイルの一覧と各ステータス。
• 分割の根拠： このように分割した理由と依存関係の順序（複数リポジトリが必要な場合）。
• 未解決の質問： 解決済みの件数と、明示的に保留した項目および保留を承認した人。

作成したら、PR の URL を共有します。そこで停止してください。ユーザーの承認を得るまでマージしてはいけません。

---

クイックリファレンス — ゲート

ゲート	トリガー	伝える内容	停止条件
1	スコープと分割案を提示	「{need} について、提案するスコープとチケットの分割案です。チケットのドラフトを作成する前に確認してください。」	ユーザーの確認
2	チケットのドラフトを作成	「チケットを docs/requirements/{slug}/ に用意しました。Definition of Ready のチェックリストも含めていますので、ご確認ください。」	ユーザーのレビュー
3	チケットが Ready	PR po/{slug} → develop 用に incu-way-prepare-pr を提案し、ユーザーが実行したら URL を共有	ユーザーの PR 承認

---

作成されるもの

docs/requirements/{ticket-slug}/
  TICKET.md   # Problem, scope, feasibility notes, repo map, acceptance criteria, open questions

---

やってはいけないこと

• Gate 1 でスコープと分割が確認される前に、チケットのドラフトを作成しないでください。
• 未解決の質問が残るチケットを Ready にしてはいけません。質問を解決するか、保留についてユーザーから明示的な承認を得てください。
• 追跡できない実現可能性の主張をしてはいけません。repo:path:line を引用するか、未解決の質問として記録してください。
• ユーザーが確認していない要件、スコープ、受け入れ条件を作り出してはいけません。
• その場でユーザーから明示的な依頼がない限り、Jira の課題を作成、更新、またはトランジションしてはいけません。
• ここでコード、PRD、計画を書いてはいけません。このフローは incu-way-development と incu-way-bugs の開始時点で終了します。
• 調査対象のリポジトリには書き込まないでください。調査中は読み取り専用です。 チケットはハブリポジトリに置きます。
• develop または main に直接書き込んではいけません。po/{slug} を使用してください。