issue-fix-design

description	設計レビューの指摘事項に基づき、設計ドキュメントを修正または議論する。
name	issue-fix-design

Issue Fix Design

設計レビューで指摘された内容に対し、論理的な妥当性を検討した上で、設計ドキュメントを更新します。

いつ使うか

タイミング	このスキルを使用
/issue-review-design で Changes Requested 後	✅ 必須
一次情報の記載を求められた後	✅ 必須

ワークフロー内の位置: design → review-design → (fix → verify) → implement

入力

ハーネス経由（コンテキスト変数）

常に注入される変数:

変数	型	説明
issue_id	str	正規化済み Issue ID（GitHub 数値または local ID）
issue_ref	str	人間可読の Issue 参照（GitHub では #<issue_id>、local では bare ID）
step_id	str	現在のステップ ID

条件付きで注入される変数:

変数	型	条件	説明
previous_verdict	str	resume または inject_verdict: true 指定ステップ	前ステップの verdict
cycle_count	int	サイクル内ステップのみ	現在のイテレーション番号
max_iterations	int	サイクル内ステップのみ	サイクルの上限回数

手動実行（スラッシュコマンド）

$ARGUMENTS = <issue_id>

解決ルール

コンテキスト変数 issue_id が存在すればそちらを使用。 なければ $ARGUMENTS の第1引数を issue_id として使用。

issue_ref はハーネス経由ではプロンプトに自動注入される（prompt.py 側で provider 別に整形）。手動実行時は issue_id から導出する: GitHub 数値 ID なら #<issue_id>、local-* 形式なら bare ID（# を付けない）。

前提知識の読み込み

以下のドキュメントを Read ツールで読み込んでから作業を開始すること。

1. テスト規約: docs/dev/testing-convention.md
2. コーディング規約: docs/reference/python/python-style.md
   • 必要に応じて docs/reference/python/naming-conventions.md / type-hints.md / docstring-style.md / error-handling.md / logging.md を追加読込
3. 開発ワークフロー: docs/dev/development_workflow.md

共通ルール

• _shared/report-unrelated-issues.md — 作業中に発見した無関係な問題の報告ルール

実行手順

Step 1: コンテキスト取得

1. _shared/worktree-resolve.md の手順に従い、Worktree の絶対パスを取得。

2. レビュー結果の取得:

   1. コンテキスト変数 previous_verdict が存在する場合はそれを確認（ハーネス経由）
   2. 存在しない場合は Issue コメントから最新のレビュー結果を取得（手動実行時）

3. レビュー内容の取得:

   kaji issue view [issue_id] --comments
   

   最新の「設計レビュー結果」を取得。

4. 設計書の現状確認:

   cat [worktree_dir]/draft/design/issue-[issue_id]-*.md
   

Step 2: 対応方針の検討

各指摘事項について検討します。

一次情報の追記を求められた場合

設計書に「参照情報（Primary Sources）」セクションを追加：

## 参照情報（Primary Sources）

| 情報源 | URL/パス | 根拠（引用/要約） |
|--------|----------|-------------------|
| (公式ドキュメント名) | (URL) | (設計判断の裏付けとなる引用または要約) |

一次情報の例:

• 公式ドキュメント（Python、Pydantic、typer 等）
• RFC、仕様書
• ライブラリのソースコード（GitHub URL）
• API仕様書（OpenAPI等）

根拠の書き方:

• 引用: 「〜である」（原文ママ）
• 要約: 〜が推奨されている（要約）

アクセス可能性ルール:

レビュワー（agent）がアクセスできない一次情報は使用できません。

情報の種類	対応方法
公開URL	そのまま記載（推奨）
ログイン必須/有償	ローカルにダウンロードしてリポジトリに配置、または該当箇所を引用
社内限定/NDA	使用不可。公開版ドキュメントを探すか、該当箇所のスクリーンショット・引用で代替

その他の指摘事項

• A: 修正する (Agree)

  • 指摘により設計がより明確になる、矛盾が解消される、使い勝手が向上する場合。

• B: 反論する/議論する (Discuss)

  • 指摘が要件定義から逸脱している、実装コストが過大になる、あるいは別のトレードオフがある場合。
  • 設計には「正解」がないことが多いため、なぜその設計にしたかの Rationale（根拠） を明確にして回答する。

Step 3: 設計書の更新

指摘を受け入れる場合、設計書を修正します。

Step 4: コミット

cd [worktree_dir] && git add draft/design/ && git commit -m "docs: update design for [issue_ref]"

Step 5: 結果報告

Issueにコメントします:

kaji issue comment [issue_id] --commit --body-file - <<'EOF'
# 設計修正報告

## 対応済み

- **(指摘内容)**
  - 修正: (どのように設計を変更したか)

## 議論/見送り

- **(指摘内容)**
  - 理由: (なぜその設計を維持するのか、トレードオフの説明)

## 次のステップ

`/issue-verify-design [issue_id]` で修正確認をお願いします。
EOF

Step 6: 完了報告

以下の形式で報告してください:

## 設計修正完了

| 項目 | 値 |
|------|-----|
| Issue | [issue_ref] |
| 対応済み | N 件 |
| 見送り | M 件 |

### 次のステップ

`/issue-verify-design [issue_id]` で修正確認を実施してください。

Verdict 出力

実行完了後、以下の形式で verdict を出力すること:

---VERDICT---
status: PASS
reason: |
  修正完了
evidence: |
  全指摘事項に対応済み
suggestion: |
---END_VERDICT---

重要: verdict は stdout にそのまま出力 すること。Issue コメントや Issue 本文更新とは別に、最終的な verdict ブロックは stdout に残す。

status の選択基準

status	条件
PASS	修正完了
ABORT	修正不可能