docs(contributing): require PR rationale and UI screenshots (MUL-8705)

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,16 @@
-## What does this PR do?
+<!-- Complete every required section. See https://github.com/multica-ai/multica/blob/main/CONTRIBUTING.md#pull-request-requirements -->
 
-<!-- Describe the change clearly. What problem does it solve? Why is this approach the right one? -->
+## Problem (required)
 
+<!-- What concrete problem are you solving, who is affected, and what should happen instead? Include reproduction steps or a specific example where relevant. A list of code changes is not a problem statement. -->
 
+## Proposal and rationale (required)
+
+<!-- Describe the proposed behavior and approach, why it solves the problem, and why you chose it. Explain the relevant constraints, tradeoffs, and risks. -->
+
+## Alternatives considered (required)
+
+<!-- Describe the alternatives you considered and why you rejected each one, including leaving the behavior unchanged where relevant. If there is no meaningful alternative, explain why. -->
 
 ## Related Issue
 
@@ -27,18 +35,28 @@ Closes #
 
 ## How to Test
 
-<!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. -->
+<!-- Give verification steps, commands actually run, and their results. State what was not tested and why. For bugs: reproduction steps + proof that the fix works. -->
 
 1.
 2.
 3.
 
+## Screenshots (required for UI or interaction changes)
+
+**UI or interaction changes without screenshots are rejected by default.**
+
+<!-- Attach screenshots from the running app showing the affected screens and states. Before/after comparisons are strongly preferred. For a new screen with no before state, explain that and include the after screenshot. A recording may supplement screenshots, but does not replace them. For changes with no UI or interaction impact, write "N/A" and explain why. -->
+
+**Before:**
+
+**After:**
+
 ## Checklist
 
-- [ ] I have included a thinking path that traces from project context to this change
-- [ ] I have run tests locally and they pass
+- [ ] I have described the problem, the proposal, why I chose it, and why I rejected alternatives
+- [ ] I have run relevant checks and documented their results and any skipped verification
 - [ ] I have added or updated tests where applicable
-- [ ] If this change affects the UI, I have included before/after screenshots
+- [ ] I have attached screenshots for UI or interaction changes, or explained why screenshots are not applicable
 - [ ] I have updated relevant documentation to reflect my changes
 - [ ] If I added a new runtime / coding tool / UI tab, I synced the change to **landing copy** (`apps/web/features/landing/i18n/`) and **relevant docs** (`apps/docs/content/docs/`)
 - [ ] If this PR touches Chinese product copy, I checked it against `apps/docs/content/docs/developers/conventions.zh.mdx` (terminology, mixed-rule for `task` / `issue` / `skill`)
@@ -49,12 +67,9 @@ Closes #
 
 <!-- Most PRs involve AI coding tools — that's totally fine! We're curious about your process. -->
 
+You are responsible for understanding the change, explaining its design, and verifying it. AI output does not replace the required rationale or evidence.
+
 **AI tool used:** <!-- e.g. Claude Code, Cursor, GitHub Copilot, Multica Agent, N/A -->
 
 **Prompt / approach:**
 <!-- How did you use AI to produce this code? Share your prompt, conversation link, or describe your approach. This helps the team learn from each other's AI workflows. -->
-
-
-## Screenshots (optional)
-
-<!-- If applicable, add screenshots showing the change in action. -->

AGENTS.md

@@ -126,4 +126,4 @@ Workspace-scoped queries filter by `workspace_id`; membership gates access and `
 - Do not add internal compatibility shims, dual writes, fallback paths, or legacy adapters unless requested. This does not relax API response compatibility above.
 - Use names, types, and tests to express behavior. Code comments are English and kept for non-obvious rationale and constraints; remove superseded plans and incident narratives when updating code. Preserve tool directives and mixed-version contracts.
 - New global pre-workspace routes use a single word or `/{noun}/{verb}`, not hyphenated root names. Update `server/internal/handler/reserved_slugs.json`, run `pnpm generate:reserved-slugs`, and commit `packages/core/paths/reserved-slugs.ts` when changing reserved slugs.
-- Use atomic conventional commits and the repository PR template. For releases, follow [.github/RELEASING.md](.github/RELEASING.md); default to a patch bump unless specified otherwise.
+- Use atomic conventional commits and the repository PR template. Follow the [pull request requirements](CONTRIBUTING.md#pull-request-requirements): explain the problem, proposal, rationale, and rejected alternatives; attach screenshots for UI or interaction changes (missing screenshots mean rejection by default). For releases, follow [.github/RELEASING.md](.github/RELEASING.md); default to a patch bump unless specified otherwise.

CONTRIBUTING.md

@@ -1,9 +1,10 @@
 # Contributing Guide
 
-This guide documents the local development workflow for contributors working on the Multica codebase.
+This guide documents pull request requirements and the local development workflow for contributors working on the Multica codebase.
 
 It covers:
 
+- pull request requirements and review evidence
 - first-time setup
 - environments: starting, inspecting, stopping and deleting them
 - day-to-day development in the main checkout
@@ -28,6 +29,38 @@ other work — you agree to condition 2 of the [Multica License](LICENSE):
 
 See the [LICENSE](LICENSE) file for the full terms.
 
+## Pull Request Requirements
+
+Use the [PR template](.github/PULL_REQUEST_TEMPLATE.md). Every PR must make the
+problem and design decisions clear enough for a reviewer to assess:
+
+1. **Problem:** Describe the concrete problem, who is affected, and the expected
+   behavior. Include reproduction steps or a specific example where relevant.
+2. **Proposal and tradeoffs:** Explain what you propose, why it solves the
+   problem, and why you chose this approach. Describe the alternatives you
+   considered and why you rejected each one, including leaving the behavior
+   unchanged where relevant. If there is no meaningful alternative, explain why.
+3. **Screenshots for UI or interaction changes:** Attach screenshots from the
+   running app showing the affected screens and states. Before/after comparisons
+   are strongly preferred. For a new screen with no before state, explain that
+   and include the after screenshot. Recordings may supplement screenshots, but
+   do not replace them. If there is no UI or interaction impact, write "N/A" in
+   the screenshot section and explain why.
+
+**UI or interaction PRs without screenshots are rejected by default.** Reviewers
+should request changes or close the PR until screenshots are provided. PRs
+missing the problem, proposal, or explanation of alternatives are also not ready
+for review.
+
+Include verification steps, the commands actually run, and their results. State
+what was not tested and why. Screenshots help reviewers assess the design and
+provide evidence that the affected UI was exercised; they complement tests.
+
+AI-assisted contributions are welcome. The author remains responsible for
+understanding the change, explaining its design, and verifying it. Generated
+code, a file list, passing CI, or an AI transcript does not replace the required
+problem statement, rationale, or evidence.
+
 ## Development Model
 
 Local development uses one shared PostgreSQL container and one database per checkout.

apps/docs/content/docs/developers/contributing.fr.mdx

@@ -207,6 +207,18 @@ make start
 - Utilisez des conventional commits tels que `feat(scope)`, `fix(scope)` ou `docs`.
 - Dans la PR, décrivez les changements de comportement et les commandes de vérification réellement exécutées.
 
+### Exigences pour les pull requests
+
+Utilisez le [modèle de PR](https://github.com/multica-ai/multica/blob/main/.github/PULL_REQUEST_TEMPLATE.md) et respectez les [exigences de contribution](https://github.com/multica-ai/multica/blob/main/CONTRIBUTING.md#pull-request-requirements) :
+
+1. **Problème :** Décrivez le problème concret, les personnes concernées et le comportement attendu. Ajoutez les étapes de reproduction ou un exemple précis si nécessaire.
+2. **Proposition et compromis :** Expliquez l'approche proposée, pourquoi vous l'avez choisie, les alternatives envisagées et pourquoi chacune a été écartée. S'il n'existe pas d'alternative pertinente, expliquez pourquoi.
+3. **Vérification de l'interface ou des interactions :** Joignez des captures d'écran de l'application en cours d'exécution montrant les écrans et états concernés. Une comparaison avant/après est fortement recommandée. Pour un nouvel écran sans état antérieur, expliquez-le et joignez la capture après modification. Une vidéo peut compléter les captures, mais ne les remplace pas. Si l'interface et les interactions ne sont pas affectées, indiquez "N/A" et expliquez pourquoi.
+
+**Les PR modifiant l'interface ou les interactions sans captures d'écran sont rejetées par défaut.** Les personnes chargées de la revue doivent demander des modifications ou fermer la PR jusqu'à l'ajout des captures. Une PR sans description du problème, proposition ou explication des alternatives n'est pas non plus prête pour la revue.
+
+Indiquez les étapes de vérification, les commandes réellement exécutées, leurs résultats et ce qui n'a pas été testé, avec la raison. Les contributions assistées par IA suivent les mêmes exigences : l'auteur doit comprendre le changement, expliquer sa conception et le vérifier. Le code généré ou une conversation avec une IA ne remplace ni la justification ni les éléments de vérification.
+
 ## Étapes suivantes
 
 - [Conventions de développement](/developers/conventions) — Contrats du dépôt pour le nommage, la terminologie et les textes en chinois.

apps/docs/content/docs/developers/contributing.ja.mdx

@@ -193,6 +193,18 @@ make start
 - `feat(scope)`、`fix(scope)`、`docs` などの conventional commit を使用します。
 - PR に動作変更と実際に実行した検証コマンドを記載します。
 
+### PR の提出要件
+
+[PR テンプレート](https://github.com/multica-ai/multica/blob/main/.github/PULL_REQUEST_TEMPLATE.md)を使い、[貢献要件](https://github.com/multica-ai/multica/blob/main/CONTRIBUTING.md#pull-request-requirements)に従ってください。
+
+1. **問題：** 解決する具体的な問題、影響を受ける人、期待する動作を説明します。該当する場合は再現手順や具体例を記載します。
+2. **提案とトレードオフ：** 提案する方法、選んだ理由、検討した代替案とそれぞれを採用しなかった理由を説明します。有意義な代替案がない場合も、その理由を記載します。
+3. **UI や操作の検証：** 実際に動かしたアプリのスクリーンショットを添付し、影響する画面と状態を示します。変更前後の比較を強く推奨します。新しい画面で変更前の状態がない場合は、その旨を説明して変更後の画像を添付します。録画は補足として使えますが、スクリーンショットの代わりにはなりません。UI や操作への影響がない場合は "N/A" と理由を記載します。
+
+**UI や操作を変更する PR にスクリーンショットがなければ、原則として受け付けません。** 画像が揃うまでは、レビュアーは変更を要求するか PR を閉じてください。問題、提案、代替案の説明が欠けた PR もレビューの対象になりません。
+
+検証手順、実際に実行したコマンドと結果、未検証の内容と理由を記載します。AI を使った貢献にも同じ要件が適用されます。作者は変更を理解し、設計を説明して検証する責任を負います。生成されたコードや AI との会話記録は、設計理由や検証結果の代わりにはなりません。
+
 ## 次のステップ
 
 - [開発規約](/developers/conventions) — 命名、用語、中国語文言に関するリポジトリの契約。

apps/docs/content/docs/developers/contributing.ko.mdx

@@ -193,6 +193,18 @@ make start
 - `feat(scope)`, `fix(scope)`, `docs` 같은 conventional commit을 사용합니다.
 - PR에 동작 변경과 실제 실행한 검증 명령을 작성합니다.
 
+### PR 제출 요건
+
+[PR 템플릿](https://github.com/multica-ai/multica/blob/main/.github/PULL_REQUEST_TEMPLATE.md)을 사용하고 [기여 요건](https://github.com/multica-ai/multica/blob/main/CONTRIBUTING.md#pull-request-requirements)을 따르세요.
+
+1. **문제:** 해결하려는 구체적인 문제, 영향을 받는 사람, 기대하는 동작을 설명합니다. 해당하는 경우 재현 단계나 구체적인 예시를 작성합니다.
+2. **제안과 장단점:** 제안하는 방법, 선택한 이유, 검토한 대안과 각 대안을 채택하지 않은 이유를 설명합니다. 의미 있는 대안이 없다면 그 이유도 작성합니다.
+3. **UI 또는 상호작용 검증:** 실제 실행한 앱의 스크린샷을 첨부해 영향을 받는 화면과 상태를 보여 줍니다. 변경 전후 비교를 강력히 권장합니다. 새 화면이라 변경 전 상태가 없다면 이유를 설명하고 변경 후 스크린샷을 첨부합니다. 녹화는 보충 자료로 사용할 수 있지만 스크린샷을 대체할 수 없습니다. UI나 상호작용에 영향이 없다면 "N/A"와 이유를 작성합니다.
+
+**UI나 상호작용을 변경하는 PR에 스크린샷이 없으면 기본적으로 거절합니다.** 스크린샷이 제공될 때까지 리뷰어는 수정을 요청하거나 PR을 닫아야 합니다. 문제, 제안 또는 대안에 대한 설명이 빠진 PR도 리뷰할 준비가 되지 않은 것으로 봅니다.
+
+검증 단계, 실제 실행한 명령과 결과, 검증하지 않은 내용과 이유를 작성합니다. AI를 활용한 기여에도 같은 요건이 적용됩니다. 작성자는 변경을 이해하고 설계를 설명하며 검증할 책임이 있습니다. 생성된 코드나 AI 대화 기록은 설계 근거나 검증 자료를 대신하지 못합니다.
+
 ## 다음 단계
 
 - [개발 규칙](/developers/conventions) — 이름, 용어, 중국어 문구에 관한 저장소 규칙을 확인합니다.

apps/docs/content/docs/developers/contributing.mdx

@@ -207,6 +207,18 @@ make start
 - Use conventional commits such as `feat(scope)`, `fix(scope)`, or `docs`.
 - Describe behavior changes and the verification commands actually run in the PR.
 
+### Pull request requirements
+
+Use the [PR template](https://github.com/multica-ai/multica/blob/main/.github/PULL_REQUEST_TEMPLATE.md) and follow the [contribution requirements](https://github.com/multica-ai/multica/blob/main/CONTRIBUTING.md#pull-request-requirements):
+
+1. **Problem:** Explain the concrete problem, who is affected, and the expected behavior. Include reproduction steps or a specific example where relevant.
+2. **Proposal and tradeoffs:** Describe the approach, why you chose it, the alternatives considered, and why you rejected each one. If there is no meaningful alternative, explain why.
+3. **UI or interaction evidence:** Attach screenshots from the running app showing the affected screens and states. Before/after comparisons are strongly preferred. For a new screen with no before state, explain that and include the after screenshot. Recordings may supplement screenshots, but do not replace them. If there is no UI or interaction impact, write "N/A" and explain why.
+
+**UI or interaction PRs without screenshots are rejected by default.** Reviewers should request changes or close the PR until screenshots are provided. Missing problem statements, proposals, or explanations of alternatives also make a PR unready for review.
+
+Include verification steps, commands actually run, results, and anything not tested with the reason. AI-assisted contributions follow the same requirements: the author must understand the change, explain the design, and verify it. Generated code or an AI transcript does not replace the rationale or evidence.
+
 ## Next steps
 
 - [Development conventions](/developers/conventions) — Repository contracts for naming, terminology, and Chinese copy.

apps/docs/content/docs/developers/contributing.zh-Hant.mdx

@@ -193,6 +193,18 @@ make start
 - 使用 `feat(scope)`、`fix(scope)`、`docs` 等 conventional commit；
 - 在 PR 中寫清行為變化和實際執行的驗證命令。
 
+### PR 提交要求
+
+使用 [PR 範本](https://github.com/multica-ai/multica/blob/main/.github/PULL_REQUEST_TEMPLATE.md)，並遵守[貢獻要求](https://github.com/multica-ai/multica/blob/main/CONTRIBUTING.md#pull-request-requirements)：
+
+1. **問題：** 說明要解決的具體問題、受影響的人和預期行為。適用時提供重現步驟或具體例子。
+2. **方案與取捨：** 說明方案是什麼、為什麼選擇它、考慮過哪些替代方案，以及分別捨棄它們的原因。如果沒有有意義的替代方案，也要解釋原因。
+3. **UI 或互動驗證：** 必須附上實際執行應用程式的螢幕截圖，展示受影響的頁面和狀態，強烈建議提供 before/after 對比。新頁面沒有變更前的狀態時，說明原因並提供變更後的截圖。螢幕錄影可以補充，但不能替代截圖。不涉及 UI 或互動影響時，填寫 "N/A" 並說明原因。
+
+**涉及 UI 或互動變更卻沒有截圖的 PR，預設拒絕。** 在補齊截圖前，審查者應要求修改或關閉 PR。缺少問題描述、方案或替代方案取捨說明的 PR，同樣不具備審查條件。
+
+寫清驗證步驟、實際執行的命令、結果，以及未驗證的內容和原因。AI 輔助貢獻遵循相同要求：作者必須理解變更、解釋設計並完成驗證。產生的程式碼或 AI 對話紀錄不能替代方案理由與驗證證據。
+
 ## 接下來
 
 - [開發規範](/developers/conventions) — 命名、術語和中文文案的倉庫契約。

apps/docs/content/docs/developers/contributing.zh.mdx

@@ -193,6 +193,18 @@ make start
 - 使用 `feat(scope)`、`fix(scope)`、`docs` 等 conventional commit；
 - 在 PR 中写清行为变化和实际运行的验证命令。
 
+### PR 提交要求
+
+使用 [PR 模板](https://github.com/multica-ai/multica/blob/main/.github/PULL_REQUEST_TEMPLATE.md)，并遵守[贡献要求](https://github.com/multica-ai/multica/blob/main/CONTRIBUTING.md#pull-request-requirements)：
+
+1. **问题：** 说明要解决的具体问题、受影响的人和预期行为。适用时提供复现步骤或具体例子。
+2. **方案与取舍：** 说明方案是什么、为什么选择它、考虑过哪些替代方案，以及分别舍弃它们的原因。如果没有有意义的替代方案，也要解释原因。
+3. **UI 或交互验证：** 必须附上实际运行应用的截图，展示受影响的页面和状态，强烈建议提供 before/after 对比。新页面没有改动前的状态时，说明原因并提供改动后的截图。录屏可以补充，但不能替代截图。不涉及 UI 或交互影响时，填写 "N/A" 并说明原因。
+
+**涉及 UI 或交互改动却没有截图的 PR，默认拒绝。** 在补齐截图前，评审者应要求修改或关闭 PR。缺少问题描述、方案或替代方案取舍说明的 PR，同样不具备评审条件。
+
+写清验证步骤、实际运行的命令、结果，以及未验证的内容和原因。AI 辅助贡献遵循相同要求：作者必须理解改动、解释设计并完成验证。生成的代码或 AI 对话记录不能替代方案理由与验证证据。
+
 ## 接下来
 
 - [开发规范](/developers/conventions) — 命名、术语和中文文案的仓库契约。