windschord 要求管理スキル
要求（Requirement）とその理由（Rationale）を軸に、ユーザーストーリー・用語・要求間の関係までを永続化し、要求どうしの整合性・無矛盾性を機械検証で常に保ちます。設計ドキュメントは作りません。
このスキルの前提
| 項目 | 方針 |
|---|---|
| 永続化するもの | 要求・ユーザーストーリー・理由・用語・要求間の関係のみ |
| 永続化しないもの | 設計書、アーキテクチャ図、API仕様、タスク詳細 |
| 設計の扱い | 実装時に必ず行うが、記録先はPR本文とGitHubコメントのみ（レジストリにはPRのURLだけ残す） |
| テストの合格条件 | すべての有効要求に検証手段があり、全ユーザーストーリーが要求で覆われていること |
| 削除の扱い | 物理削除は禁止。deprecated / superseded として理由付きで残す（墓標） |
このスキルは requirements-defining / software-designing / sdd-document-management の移行先です。これらは非推奨であり、併用は想定していません。既存の docs/sdd/ からの移行手順は references/migration_from_sdd_ja.md を参照してください。
ディレクトリ構成
docs/requirements/
├── glossary.yaml # 用語集＋ポリシー（曖昧語・多値キー・鮮度しきい値）
├── <ドメイン>.yaml # 要求とストーリー（ファイル分割は自由）
└── generated/ # 自動生成（手で編集しない・レビュー対象）
├── index.md # 全要求一覧＋墓標
├── traceability.md # ストーリー→要求→検証 マトリクス
└── graph.md # Mermaid関係グラフ
中核ルール（破ってはならない不変条件）
- 理由なき要求を作らない: すべての要求に
rationale.whyが必須。 - リンクは片方向のみ: ストーリーと要求の紐付けは要求側の
storiesにだけ書く。ストーリー側にacceptanceを書くと二重管理となりエラー。 - 検証不能な要求を残さない:
status: activeの要求にはverificationが必須。 - 削除せず廃止する: 削除時は
statusをdeprecated/supersededにし、rationale.retired_whyを書く。 - 矛盾は宣言するか解消する: 数値・事実の衝突は、要求を直すか、双方に
conflicts_withとrationale.tradeoffを書いて許容を明示する。 - 生成物は手で書かない:
generated/は必ずreqctl.py generateで再生成する。生成結果は入力が同じなら常に同一になるため、CIで再生成して差分がないことを確認できる。
コマンド
すべて reqctl.py（Python 3.9+ / PyYAML のみ）で実行します。
実行パスは導入方法によって変わります。初期化時にプロジェクトへコピーした場合は scripts/reqctl.py、スキルから直接実行する場合は <スキルのパス>/sdd/requirement-management/scripts/reqctl.py を指定します。以下はコピーした場合の例です（CI設定例も同じ前提）。
python3 scripts/reqctl.py validate # 検査（エラーがあれば exit 1）
python3 scripts/reqctl.py validate --strict # 警告もエラー扱い（exit 2）
python3 scripts/reqctl.py validate --check-tests # 検証手段のテストファイル存在も確認
python3 scripts/reqctl.py validate --json # 機械処理用の出力
python3 scripts/reqctl.py generate # generated/ を再生成
python3 scripts/reqctl.py impact REQ-0002 # 変更前の影響範囲確認
python3 scripts/reqctl.py next-id req # 次の採番
python3 scripts/reqctl.py stats # 件数サマリ
--dir でレジストリの場所を変更できます（既定 docs/requirements）。
ワークフロー
読み込みの原則: テンプレートとリファレンスは、使用する直前に必要なものを1つだけ読み込む。手順の冒頭で一括して読み込まない。
0. 初期化（レジストリが存在しない場合）
docs/requirements/を作成する。assets/templates/glossary_template_ja.yamlを読み込み、glossary.yamlとしてコピーして用語を埋める。assets/templates/requirements_registry_template_ja.yamlを読み込み、<ドメイン>.yamlとしてコピーする。scripts/reqctl.pyをプロジェクトのscripts/にコピーするか、スキルのパスを直接実行する。validate→generateを実行して初期状態を確定する。assets/templates/ci_req_lint_template.ymlを読み込み、CI設定を導入する。
1. 要求の追加
ステップ 1/6: 情報分類（明示された情報／不明な情報を分ける）
ステップ 2/6: 不明点をユーザーに質問（推測で埋めない）
ステップ 3/6: 既存要求との衝突を先に調べる（同じ subject/key を持つ要求を impact で確認）
ステップ 4/6: next-id で採番し、要求とストーリーをYAMLに追記
ステップ 5/6: validate を実行し、エラーゼロになるまで修正
ステップ 6/6: generate で generated/ を更新し、差分をユーザーに提示して承認を得る
理由（rationale.why）が書けない要求は追加しないでユーザーに確認します。
2. 要求の変更
ステップ 1/6: impact <ID> で影響範囲（被依存要求・ストーリー・テスト・同一subject）を取得
ステップ 2/6: change_proposal_template_ja.md を読み込み、変更提案レポートを作成
ステップ 3/6: ★ ユーザー承認 ★（必須ゲート）
ステップ 4/6: YAMLを変更し、rationale.why を更新（理由が変わったなら理由も書き換える）
ステップ 5/6: validate --strict を実行し、波及した矛盾をすべて解消
ステップ 6/6: generate → 差分提示
要求の意味が変わる変更は、変更ではなく置換（supersede）です。 影響が大きい場合は新IDを作り、旧要求を superseded にします。判断基準は references/change_workflow_ja.md を参照。
3. 要求の廃止・削除
行を消してはいけません。
ステップ 1/5: impact <ID> で、その要求に依存している要求とストーリーを特定
ステップ 2/5: 依存元の扱いを決める（同時廃止／付け替え／置換）
ステップ 3/5: ★ ユーザー承認 ★
ステップ 4/5: status を deprecated（単純廃止）または superseded（置換）にし、rationale.retired_why を記入。
置換の場合は新要求に supersedes: [旧ID] を書く
ステップ 5/5: validate → generate
4. 実装時（設計はここで行いPRに書く）
- 実装対象の要求IDを確定する（
generated/traceability.mdから選ぶ）。 - 設計を検討する。設計内容はレジストリに書かない。
assets/templates/pr_design_note_template_ja.mdを読み込み、PR本文に設計ノートを書く。- 実装とテストを書き、テスト名を要求の
verificationに登録する。 validate --check-testsでテストの存在を確認する。- PRのURLを
design_refsに追加する（URLのみ。設計内容は書かない）。設計判断が要求の理由そのものを変えた場合は、あわせてrationaleを更新する。
詳細は references/design_in_pr_ja.md を参照。
5. 定期点検
リリース前や週次で validate --strict を実行し、警告（曖昧表現・用語ゆれ・重複疑い・理由の陳腐化）を棚卸しします。
検査項目の概要
| 分類 | 代表コード | 内容 |
|---|---|---|
| 構造 | E-SCHEMA / E-IDFMT / E-REF | 必須項目・ID書式・参照先の実在 |
| 理由 | E-RATIONALE / W-STALE | 理由の有無と鮮度 |
| ライフサイクル | E-SUPERSEDE / E-RETIRE / E-DEAD-REF | 廃止の整合、廃止済みへの参照禁止 |
| 矛盾 | E-CONFLICT-NUM / E-CONFLICT-FACT | 数値制約・事実主張の充足不能 |
| 循環 | E-CYCLE | 依存関係の循環 |
| カバレッジ | E-NOVERIFY / E-ORPHAN-US / W-ORPHAN-REQ | 検証手段とストーリー被覆 |
| 品質 | W-AMBIGUOUS / W-EARS / W-TERM-ALIAS / W-DUP | 曖昧表現・記法・用語ゆれ・重複疑い |
全コードと対処法は references/consistency_rules_ja.md を参照。
ユーザー承認が必須の操作
- 要求の変更・廃止・置換
- 既存要求との衝突を
conflicts_withで許容する判断 - 要求の優先度（
priority）の変更 - レジストリの分割・移動などの構成変更
追加のみ・警告解消のみの場合は、差分提示で足ります。
リソース
スクリプト
scripts/reqctl.py: 検証・生成・影響分析ツール
テンプレート
assets/templates/requirements_registry_template_ja.yaml: 要求レジストリ雛形assets/templates/glossary_template_ja.yaml: 用語集・ポリシー雛形assets/templates/change_proposal_template_ja.md: 変更提案レポートassets/templates/pr_design_note_template_ja.md: PR設計ノートassets/templates/ci_req_lint_template.yml: CI設定例
リファレンス
references/data_model_ja.md: YAMLスキーマ全仕様references/consistency_rules_ja.md: 検査コード一覧と対処法references/change_workflow_ja.md: 追加・変更・廃止の判断基準references/design_in_pr_ja.md: 設計をPRに閉じる運用references/management_options_ja.md: 管理方式の比較検討と採用理由references/migration_from_sdd_ja.md: 既存 docs/sdd/ からの移行手順