contribute

貢献

ユーザーは臨床医で、プルリクエストを作成したことがない可能性が高いです。Git に関する作業は代わりに行ってください。Git コマンドを入力させてはいけません。また、ユーザーが読むものに「rebase」「upstream」「HEAD」という語を使ってはいけません。ユーザーのローカル編集は、実際の患者や実際の原稿と並んでいます。これがスキルである理由は、Git の仕組みではなく、以下の安全手順にあります。

絶対に曲げてはいけない唯一のルール

**作成者が、外部に送られるすべての行を確認して承認するまで、何もそのマシンから外に出してはいけません。**何かが送信されるまでは、毎回、何も送信されていないと明確に伝えてください。

安全スキャンは補助であり、証明書ではありません。患者の名前や病院をすべて認識できるパターンリストはありません。ユーザーがそのことを忘れずにいられるよう、はっきり伝えてください。スキャナーが完全だと思い込むと差分を読まなくなり、そのときこそ情報漏えいが起きます。

スキャンでブロッカー（患者レベルのデータ、認証情報）が検出された場合は、回避策を提案してはいけません。その行は削除します。貢献の要点を伝えるのに患者データは必要ありません。

フェーズ 0：何を変更しましたか？

python3 "${CLAUDE_SKILL_DIR}/scripts/find_local_changes.py" --target claude --json \
  --out qc/local_changes.json

インストールされているスキルを、配布時のハッシュと照合します。読み取りのみを行います。

• 変更なし → そのまま明確に伝えて終了します。これは通常のことで、失敗ではありません。代わりにフィードバック経路（フェーズ 4）を案内します。
• 変更あり → スキルごとに分類して表示します。
  • 新しいファイル（ジャーナルのプロファイル、引用スタイル、報告用の実例など） — 通常、最も価値の高い貢献です。プロジェクト内の誰も持っていない専門知識だからです。そのことを伝えてください。
  • 編集されたファイル — その専門分野において何が問題だったかを尋ねます。その回答がプルリクエストの説明になります。編集の理由を推測してはいけません。
  • 削除されたファイル — 通常は貢献ではありません。含める前に確認してください。

ある病院でしか意味をなさない変更（内部規則、診療科のレターヘッド入りテンプレートなど）は、ローカルな調整であり、貢献ではありません。そのように伝えて対象から外し、手元に残して問題ないと伝えてください。

フェーズ 1：安全スキャン（ブロッキング）

python3 "${CLAUDE_SKILL_DIR}/scripts/check_contribution_safety.py" \
  --changes qc/local_changes.json --out qc/safety.json

このゲートはフェイルクローズです。何かが見つかると、ほかのリポジトリ内の検出器とは異なり、必ずゼロ以外の終了コードになります。病院名を出力しながら成功を返すツールは、いずれ「何も出力しなかった」と信頼されることになるため、意図的にそう設計されています。

判定結果：PHI_SUSPECTED、SECRET（ブロッカー — 議論するのではなく、その行を削除します）、IDENTITY、INSTITUTION、APPROVAL_ID、MANUSCRIPT_ID、LOCAL_PATH。スキャン結果に表示される各項目の do 行に従って、該当箇所をユーザーと一緒に修正します（名前 → 役割、病院名 → 一般的な表現、IRB または原稿 ID → 削除、ホームディレクトリのパス → ~）。審査中の論文は機密情報であり、原稿 ID からその論文を特定できるため、原稿 ID も重要です。

UTF-8 テキストではないファイル（画像、バイナリなど）はスキャンも読み取りもできないため、NOT SCANNED として一覧表示されます。貢献の対象から外すまで、スキャンは失敗します。qc/safety.json には、スキャンしたすべてのファイルの sha256 が記録されます。送信しようとしているファイルが、そのファイルと完全に一致し、変更されていない場合を除き、送信手順は先に進みません。**編集したら、必ずスキャンを再実行してください。**古いレポートや、別のファイルに対して --text を使って作成したレポートでは、何もクリアされません。

次に、送信対象となるすべてのファイルの全文を表示し、ユーザーに読んでもらいます。要約ではなく、全文です。実際にユーザーを守るのはこの手順です。

フェーズ 2：プロジェクト独自の基準を満たしていますか？

リポジトリをローカルで利用できる場合は、変更に対してリポジトリのバリデーターを実行してください。利用できない場合は、目視で確認してください。

• ジャーナルのプロフィールには、そのジャーナルの公開されている投稿者向けガイドラインが引用されています。語数制限、抄録の構成、AI ポリシーは、ガイドラインから引用するか、記載しないでください。インパクトファクターや、記憶に頼った数値は記載しないでください。
• 引用スタイルは、Zotero リポジトリの公式 CSLです。
• スキルの編集後も、そのスキルの役割が説明されています。また、変更は一般化されており、別の病院の人にも役立つ内容です。そうでなければ、ローカル向けの調整です。ローカルにとどめてください。

基準を満たしていない場合は、何を変更すればよいか、相手自身の言葉で伝えてください。却下される投稿は送らないでください。投稿しないことよりも、悪い体験になります。

フェーズ 3：送信する

python3 "${CLAUDE_SKILL_DIR}/scripts/submit_contribution.py" \
  --changes qc/local_changes.json --safety qc/safety.json \
  --title "Add a journal profile for <journal>" --dry-run

必ず最初に --dry-run を実行し、計画を相手に示してください。その後、相手が明示的に承諾したら、--dry-run を付けずに再実行してください。スクリプトは、利用できる最も上位の方法を実行します。

1. GitHub ツールがインストール済みで、サインインしている → フォークを作成し、ファイルをコピーして、プルリクエストを開きます。相手は何も入力する必要がありません。
2. インストール済みだが、サインインしていない → 単一のコマンド（gh auth login）を表示して停止します。手順を案内してください。GitHub.com → HTTPS → ブラウザーからログイン、の順です。
3. インストールされていない → 変更をファイルに書き出し、内容をあらかじめ入力した Issue をブラウザーで開きます。開発者向けツールのインストールを、支援の条件にしないでください。

次に何が起きるかも伝えてください。メンテナーが内容を確認し、変更が必要な場合は、そのページで平易な言葉を使って返信できます。Git の作業を求められることはありません。

フェーズ 4：コード変更以外のフィードバック

誤検知やステップの失敗は、臨床医が持つ最も有用な情報であることがよくあります。実際の原稿に対して検出器がどのように動作するかを示す、合成テストデータではない唯一の証拠だからです。次の情報を集めてください。

• 検出器が誤って作動した：どの検出器か（その検出器の qc/*.json にある detector フィールド）、判定、再現に必要な最小限の抜粋。実際の内容を見せられない場合は、数値と名前を架空のものに書き換えてください。重要なのは文の形です。
• ステップが失敗した：コマンド、エラー、ホスト（Claude Code / Codex / Cursor / Copilot）、オペレーティングシステム。
• 専門分野に合わない点があった：ツールキットが何を前提としていたか、実際にはどうなのか。

同じ安全確認を行ったうえで、Issue として送ってください。実際の原稿からの再現例は、PHI が紛れ込むまさにその場所です。

python3 "${CLAUDE_SKILL_DIR}/scripts/check_contribution_safety.py" --text qc/feedback.md
gh issue create --repo Aperivue/medsci-skills --title "<one sentence>" --body-file qc/feedback.md --web

--web を指定すると、内容があらかじめ入力された状態でブラウザーに開きます。相手は内容を確認して送信ボタンを押します。こちらから何かが送信されることはありません。

フェーズ 5：更新後も変更を維持する

インストーラーは、変更したスキルを上書きする前に、すでに永続的なバックアップ（~/.medsci-skills/backups/ 以下）を作成することを伝えてください。そのため、更新によって作業が失われることはありません。多くの人は失われると思い込んでいるため、更新を避けています。変更を残す価値があるなら、投稿することで次回の更新に含めることができます。

設定 — しつこい通知はありません

python3 "${CLAUDE_SKILL_DIR}/scripts/contribution_prefs.py" --status
python3 "${CLAUDE_SKILL_DIR}/scripts/contribution_prefs.py" --on    # remind me
python3 "${CLAUDE_SKILL_DIR}/scripts/contribution_prefs.py" --off   # never mention it (default)

• リマインダーはオプトイン方式で、デフォルトではオフです。インストーラーが選択肢を案内するのは、初回インストールの最後に一度だけで、その後は案内しません。オプトインした場合も、実際に何かを変更したときだけリマインダーが表示され、頻度は月に 1 回までです。
• この設定が制御するのはリマインダーのみです。/contribute は実行するたびに利用できます。
• この設定で安全性が損なわれることはありません。そのためのキーは存在せず、check_contribution_safety.py は設定を読み取りません。オプトインしても、「確認なしで送信する」という意味にはなりません。

感謝を伝える

このツールキットが役立つと感じている臨床医の多くは、スターが何のためにあるのかを誰からも聞いていないため、リポジトリにスターを付けたことがありません。ツールキットが実際に役立ったら、スターについて伝えてください。このスクリプトはスターの役割を説明し、1つのコマンドでスターを付けられるようにします。

python3 "${CLAUDE_SKILL_DIR}/scripts/star_repo.py" --how   # explain + show both ways
python3 "${CLAUDE_SKILL_DIR}/scripts/star_repo.py" --now   # do it from here (GitHub CLI)

• 二度と頼まない — 一度案内したことは記録され、何もしないことも返答です。
• 美化して伝えないでください。スターがないとツールキットが困るとほのめかしたり、ツールキットが役立つ前に頼んだりしてはいけません。お礼を先回りして求めるのは物乞いです。

対象範囲

インストール済みのスキルだけに作用し、ユーザーの原稿、データ、その他のファイルには一切触れません。コントリビューションはフォークのプルリクエストまたはイシューとして受け付けます。メインリポジトリには決してプッシュしません。

既知の制限事項

• 患者識別子のパターンが対象とするラベルや形式は固定されています。認識できないものには、登録番号や患者番号を表す韓国語のラベル、ハイフンなしで記載された住民登録番号、英数字の患者 ID、「hospital number」、月名を使った、または「born」で始まる生年月日などがあります。パターンを拡張すると、文章全体を対象にキーワード照合することになり、これまでも誤検出が発生しているため、拡張していません。これらを網羅するのは、すべての行を読み取るフェーズ 1 の役割です。