requirements-gathering

要件の収集

あらゆるソースから要件を収集して整理し、後続のスキル（schema-explorer、datasource-creator、report-creator）が利用できる標準化されたブリーフを作成します。

使用するタイミング

• レポートを作成する前（report-creator がフェーズ 1 として実行します）
• データソースを作成する前（要件が不明確な場合に datasource-creator が実行します）
• ユーザーから作業項目 ID、モックアップ、仕様書、説明が提供され、何かを構築する前に構造化された要件を抽出する必要があるとき

出力の仕様

ソースにかかわらず、次のセクションを含む要件ブリーフを作成します。

## Requirements Brief

**Title:** [name of the report/datasource/feature]
**Purpose:** [1-2 sentence summary]
**Source:** [work item #ID / user conversation / document / existing report]

### Data Requirements

#### Fields with Semantic Roles
For each field, identify WHAT it is and WHERE it belongs:

| Field | Semantic Role | Report Section / Usage |
|-------|--------------|----------------------|
| ownerName | Goods principal name | Shipper/Consignor header |
| accountName | Customer name | Consignee header |
| materialLookupCode | Product identifier | Line item grid |
| tareWeight | Packaging weight | Calculated: gross = raw + qty * tare |

#### Entity Keywords
[List of OData entity search terms derived from requirements]

### Layout Expectations
- **Report category:** [Label / Official Documentation / Work Detail / Inventory-Operations]
  - Labels: high visibility, scannable barcodes, tight margins
  - Official Documentation: branded, legally compliant, standard margins
  - Work Detail: key info only, minimal distractions
  - Inventory/Operations: data comparison tables (consider if an app component would serve better)
- **Page size:** [letter/legal/A4/custom]
- **Orientation:** [portrait/landscape]
- **Key sections:** [header, detail grid, footer, etc.]
- **Special elements:** [barcodes, logos, signatures, images]

### Business Rules
- [Calculated fields with formulas]
- [Conditional visibility rules]
- [Date null-guard requirements]
- [Filtering/exclusion rules]

### Parameters
- [Input parameters with types]

### Reference Materials
- [List of attachments, screenshots, documents consulted]

ソース別の処理

DevOps 作業項目

ユーザーから作業項目の ID または URL が提供された場合：

1. devops-requirements スキルを呼び出します — データの取得、関連項目、添付ファイルの処理、要件の抽出を担当します
2. 意味に基づくフィールドマッピングで出力を補完します（以下を参照）
3. ブリーフをアーティファクトディレクトリに保存します

モックアップまたはスクリーンショット

ユーザーから画像（モックアップ、スクリーンショット、PDF）が提供された場合：

1. 表示されているすべての要素を読み取ります — ラベル、列見出し、データ値、セクションの境界、ロゴ、バーコード
2. ラベルをデータフィールドにマッピングします — 表示されている各ラベルはフィールドを示します。「SHIPPER」は単なるテキストではなく、データソース（荷主エンティティは何か？）です
3. セクションを特定します — ヘッダー、住所ブロック、詳細グリッド、フッター、署名
4. ブリーフを確定する前に、曖昧な要素について確認の質問をします

自然言語による説明

ユーザーが会話の中で必要なものを説明した場合：

1. 名詞を候補エンティティとして抽出します — 「顧客の配送先住所」→ Account、ShippingAddress
2. 修飾語を候補フィールドとして抽出します — 「倉庫の電話番号」→ Warehouse.Contact.Phone
3. 不足している情報を補うため、構造化された質問をします：
   • どのデータを表示しますか？（エンティティとフィールド）
   • 誰が使用しますか？（レイアウトを決定します：印刷か画面表示か、ページサイズ）
   • どのフィルター／パラメーターを使用しますか？（入力パラメーター）
   • 計算やビジネスルールはありますか？（式）
   • 参考になる既存のレポートはありますか？（参照資料）
4. 次に進む前に、確認用のドラフトブリーフを提示します

既存のレポート（.rdl または .rdlx-json）

ユーザーから既存のレポートファイルが提供された場合：

1. .rdlx-json の場合：dxs report inspect を使用して、構造、DataSets、フィールド名、式を抽出します
2. .rdl（SSRS）の場合：SQL を含む <CommandText> 要素を検索します — SELECT 列と FROM／JOIN テーブルを OData のエンティティおよびフィールドに対応付けます
3. レイアウト内の要素名と配置に基づいて、抽出したフィールドを意味上の役割にマッピングします

ドキュメントまたは仕様書

ユーザーからドキュメント（Word、PDF、Excel）が提供された場合：

1. フィールドリストを抽出します — テーブル、SQL クエリ、列定義を探します
2. レイアウトのスケッチを抽出します — 出力の視覚的な表現を探します
3. ビジネスルールを抽出します — 数式、条件、フィルタリングロジックを探します

セマンティックフィールドマッピング

これは、後続のエラーを防ぐための重要なステップです。あらゆるソースから未加工のフィールドを抽出した後、各フィールドにセマンティックな役割（ドメインの文脈における意味）を割り当てます。

役割の割り当て方：

1. SQL のフィールド名から判断する：接頭辞をドメインの手掛かりとして読み取ります

   • owner* → 商品の所有者／荷送人（BOL の文脈）
   • account* → 顧客／請求先
   • shipTo* → 配送先／荷受人
   • warehouse* → 施設／3PL 拠点
   • carrier* → 運送業者
   • material*／lot* → 在庫品の詳細
   • order* → 注文レベルのデータ（参照番号、日付、メモ）

2. モックアップのラベルから判断する：視覚的なラベルをデータエンティティに対応付けます

   • "SHIPPER/CONSIGNOR" → Owner エンティティ（Account ではありません）
   • "CONSIGNED TO" → Account／Ship-To エンティティ
   • "CARRIER" → Carrier エンティティ
   • "FREIGHT BILL NUMBER" → BOL の場合も参照番号の場合もあります。確認してください

3. 自然言語から判断する：説明された概念をエンティティに対応付けます

   • 「顧客の住所」 → Account.Address または ShipToContact.Address
   • 「誰が発送したか」 → Owner（運送業者ではなく、商品の所有者）

4. 曖昧な場合：曖昧さを明示して、ユーザーに確認します。推測してはいけません。意味の割り当てを誤ると、誤ったデータソースフィールドやレポートレイアウトにつながります。

アンチパターン

• 役割を付けずにフィールドを列挙する — セマンティックマッピングなしでフィールドを列挙すると、後続のスキルで各フィールドの配置先を推測することになります。必ず役割を割り当ててください。
• 「明らか」と思えるフィールドを省略する — packUOM、tareWeight、vlDescription はレポートのタイトルや主な列に含まれていなくても、必要な場合があります。ソースにあるフィールドをすべて列挙してください。
• SQL と OData を同じだと思い込む — SQL ビューでは、結合されたデータがあらかじめフラット化されています。同じデータを OData で取得するには、複数階層の $expand やリンクされたデータソースが必要になる場合があります。ブリーフには複雑な結合経路を記載してください。
• 汎用的な法的文言に置き換える — ソースに具体的な法的文言（運送業者の責任条項など）が含まれている場合は、そのまま記録してください。汎用的な定型文に置き換えてはいけません。
• 画像や署名を無視する — ソースにロゴ、署名、画像フィールドがある場合は、その旨を記載してください。これらには特別な取り扱い（埋め込み画像、データベースから取得する画像、またはフローデータソース）が必要です。