From b42924f391fd63058518294a36c196678ff733c6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 17 Jan 2026 15:01:39 +0000
Subject: [PATCH] docs: improve PR template and add agent guidance for
 descriptive PRs

- Update PR template with REQUIRED markers for summary and changes
- Add "Changes" section to explicitly list modifications
- Add AI agent instructions in HTML comment for PR creation
- Add "Pull Request Requirements" section to AGENT.md with examples
- Reference git-workflows skill before commits and PRs
- Simplify template by removing redundant documentation checklist
---
 .github/PULL_REQUEST_TEMPLATE.md | 53 ++++++++++++++++++++++----------
 AGENT.md                         | 50 +++++++++++++++++++++++++++++-
 2 files changed, 85 insertions(+), 18 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 13d6ccc7..9d83859f 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,6 +1,13 @@
 ## Summary
 
-<!-- Brief description of what this PR does -->
+**REQUIRED: Write 2-4 sentences describing WHAT this PR does and WHY.**
+
+## Changes
+
+**REQUIRED: List the specific changes made in this PR:**
+-
+-
+-
 
 ## Type of Change
 
@@ -13,36 +20,48 @@
 
 ## Testing
 
-<!-- How was this tested? -->
+**Describe how this was tested:**
 
 - [ ] Unit tests added/updated
 - [ ] Manual testing performed
 - [ ] N/A (documentation only)
 
-## Documentation Checklist
-
-<!-- Check all that apply -->
+## Documentation
 
 - [ ] **No docs needed** — This change doesn't affect user-facing features
 - [ ] **Docs updated** — Help center articles updated to reflect this change
-- [ ] **Docs flagged** — This needs doc updates but they're tracked elsewhere (link issue/TODO)
-
-### If docs are affected:
-
-**Which articles need updates?**
-<!-- List specific files in docs/help-center/articles/ or docs/legal/ -->
-
-**What changed?**
-<!-- Brief description of what documentation needs to say -->
+- [ ] **Docs flagged** — This needs doc updates but they're tracked elsewhere
 
 ## Checklist
 
 - [ ] My code follows the project's style guidelines
 - [ ] I have performed a self-review of my code
-- [ ] I have commented my code where necessary
 - [ ] My changes generate no new warnings
-- [ ] Any dependent changes have been merged and published
 
 ---
 
-*Remember: Documentation accuracy is a feature. If this PR changes behavior, update the docs.*
+<!--
+## For AI Agents
+
+When creating a PR, you MUST:
+
+1. **Write a descriptive PR title** using conventional commits format:
+   - `feat: Add dark mode toggle to settings`
+   - `fix: Correct timezone handling in scheduler`
+   - `refactor: Extract validation into shared utility`
+
+2. **Fill in the Summary** with actual content (not placeholders):
+   - What problem does this solve?
+   - What was the approach?
+   - Any important context?
+
+3. **List specific Changes** as bullet points:
+   - Be specific: "Add `validateEmail()` function to auth module"
+   - Not vague: "Update files"
+
+4. **Check the appropriate Type of Change** checkbox
+
+5. **Describe Testing** - what did you do to verify this works?
+
+DO NOT leave HTML comments as placeholders. Replace ALL template text with actual content.
+-->
diff --git a/AGENT.md b/AGENT.md
index aa4c213b..0093b292 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -157,6 +157,8 @@ This lesson learned the hard way: the mobile menu z-index fix (#367) only worked
 
 ### Git Workflow Essentials
 
+> **⚠️ IMPORTANT:** Before making commits or PRs, invoke the `git-workflows` skill for full guidance.
+
 **After completing major changes, you MUST commit your work.**
 
 **Conventional Commits Format:**
@@ -177,6 +179,51 @@ docs: Update README
 
 **For complete details:** See `AgentUsage/git_guide.md`
 
+### Pull Request Requirements
+
+**When creating PRs, you MUST write descriptive titles and descriptions.**
+
+**PR Title Format:** Use conventional commits format
+```
+feat: Add dark mode toggle to settings
+fix: Correct timezone handling in scheduler
+refactor: Extract validation into shared utility
+```
+
+**PR Description Requirements:**
+1. **Summary** — 2-4 sentences explaining WHAT and WHY (not placeholders)
+2. **Changes** — Specific bullet points of what changed
+3. **Type of Change** — Check the appropriate checkbox
+4. **Testing** — Describe how you verified it works
+
+**Example good PR description:**
+```markdown
+## Summary
+Adds a dark mode toggle to the settings page, allowing users to switch
+between light and dark themes. This addresses user feedback about eye
+strain during nighttime use.
+
+## Changes
+- Add `ThemeToggle` component to settings page
+- Create `useTheme` hook for theme state management
+- Update CSS variables for dark mode colors
+- Add theme preference to user settings storage
+
+## Type of Change
+- [x] New feature
+
+## Testing
+- Manually tested toggle in Chrome and Firefox
+- Verified theme persists across page reloads
+- Checked accessibility contrast ratios in both modes
+```
+
+**DO NOT:**
+- Leave template placeholders like `<!-- Brief description -->`
+- Use vague descriptions like "Update files" or "Fix things"
+- Skip the summary section
+- Create PRs with empty descriptions
+
 ---
 
 ## 🌲 Engine-First Pattern (CRITICAL)
@@ -290,6 +337,7 @@ cat packages/engine/package.json | grep -A2 '"\./'
 
 ### Version Control
 - **Before making a git commit** → Use skill: `git-workflows`
+- **Before creating a pull request** → Use skill: `git-workflows`
 - **When initializing a new repo** → Use skill: `git-workflows`
 - **For git workflow and branching** → Use skill: `git-workflows`
 - **When setting up git hooks** → Use skill: `git-hooks`
@@ -505,5 +553,5 @@ For in-depth reference beyond what skills provide, see:
 
 ---
 
-*Last updated: 2026-01-15*
+*Last updated: 2026-01-17*
 *Model: Claude Opus 4.5*