Epic: Integrate GitHub keywords and PR etiquette into agents/skills

[rjmurillo-bot]

Summary

Integrate GitHub keywords (Closes, Fixes, Resolves) and PR etiquette best practices into the agent/skill/command structure to enforce standards and reduce reviewer friction.

Background

Research completed in PR #864 documents:

• GitHub's 9 issue linking keywords (Closes, Fixes, Resolves)
• Conventional Commit format standards
• PR template compliance requirements
• Review and CI etiquette best practices

Reference: .agents/analysis/github-keywords-integration-plan.md

Integration Phases

Phase 1: Skill Enhancement (High Value, Low Effort)

Effort: 2-3 hours
Impact: Immediate validation feedback on PR creation

• Create Test-PRDescription.ps1 in github skill
  • Validate issue linking keywords present
  • Check PR template section completion
  • Validate Conventional Commit title format
• Update New-PR.ps1 to call validator (warning mode)
• Update github SKILL.md with keyword documentation

Phase 2: Agent Prompt Updates (Medium Value, Low Effort)

Effort: 1-2 hours
Impact: Agents apply etiquette patterns automatically

• Update implementer.md with commit message standards
  • Add Conventional Commit format section
  • Add issue linking keywords in commit bodies
• Update pr-comment-responder.md with response etiquette
  • Response format: Action + location + commit reference
  • Thread resolution protocol
  • Force push communication
• Update qa.md with PR description validation checklist

Phase 3: Command Enhancements (Low Value, Low Effort)

Effort: 30 minutes
Impact: Better user guidance

• Update push-pr.md with keyword reminder
• Create validate-pr-description.md command

Phase 4: Dedicated Skill (Optional, High Effort)

Effort: 4-6 hours
Impact: Centralized validation, reusable

• Extract validation to pr-etiquette skill
• Add comprehensive test suite
• Add etiquette report generator

Success Metrics

Metric	Target	Measurement
PRs with issue keywords	90%	GitHub API search
Template compliance	95%	CI validation pass rate
Conventional Commit titles	100%	Pre-commit enforcement
Reviewer time saved	20% reduction	Time from open to merge
PR iteration cycles	1-2 fewer	Average comment rounds

Recommended Approach

Phase 1 + Phase 2 (combined: 3-5 hours)

Rationale:

• Highest value from validation + agent prompts
• Builds on existing github skill infrastructure
• Incremental approach allows iteration
• Can add Phase 3/4 later if needed

Test Strategy

Pre-Creation Validation

• Run before gh pr create
• Check: Conventional Commit title, issue keywords, template sections
• Action: Warn if missing, block on critical errors

Post-Creation Validation

• Run in CI after PR created
• Check: Same as pre-creation + security review alignment
• Action: Add comment with validation report

Agent Self-Check

• QA agent validates before marking complete
• Implementer includes keywords in commits
• PR comment responder follows etiquette

Related Documentation

• Analysis: .agents/analysis/github-keywords-pr-etiquette.md
• Integration Plan: .agents/analysis/github-keywords-integration-plan.md
• Memory: .serena/memories/github-keywords-pr-etiquette.md
• PR Template: .github/PULL_REQUEST_TEMPLATE.md

Acceptance Criteria

• Phase 1 complete: Validation script created and integrated
• Phase 2 complete: All 3 agent prompts updated
• Success metrics baseline established
• 5 PRs tested with new validation
• Documentation updated
• Validation integrated into CI pipeline

Dependencies

• None (builds on existing infrastructure)

Risks

• False positives in validation (mitigate: tune thresholds based on feedback)
• Agent prompt changes may require iteration (mitigate: test on 5 PRs first)

---

📋 Type: Epic
🎯 Priority: Medium
⏱️ Estimated Effort: 3-5 hours (Phase 1+2), 8-12 hours (all phases)
🔗 Related PR: #864

[traycerai]

Plan

Observations

The repository has a well-established agent/skill/command infrastructure with PowerShell-based GitHub operations. The file:.claude/skills/github/scripts/pr/New-PR.ps1 already validates conventional commit format and has a validation framework. Agent prompts (implementer.md, pr-comment-responder.md, qa.md) exist but lack GitHub keyword integration and PR etiquette patterns. The PR template (file:.github/PULL_REQUEST_TEMPLATE.md) already references issue linking keywords but lacks enforcement. No validation script for PR descriptions exists yet.

Approach

Following the ticket's recommended Phase 1+2 approach (3-5 hours total), focusing on high-value, low-effort enhancements. Create a validation script within the existing github skill infrastructure, integrate it into the PR creation workflow in warning mode, and update agent prompts with keyword standards and etiquette patterns. This builds incrementally on existing patterns without introducing new complexity. Phase 3 and 4 are deferred as optional future enhancements.

Implementation Plan

Phase 1: Skill Enhancement (2-3 hours)

1.1 Create PR Description Validator Script

Create file:.claude/skills/github/scripts/pr/Test-PRDescription.ps1 with the following validation logic:

Validation Checks:

• Issue Linking Keywords: Detect presence of GitHub's 9 keywords (Closes, Fixes, Resolves with variations: close, closed, fix, fixed, resolve, resolved)
• Conventional Commit Title: Validate title format matches type(scope)?: description pattern
• PR Template Compliance: Check for required sections from file:.github/PULL_REQUEST_TEMPLATE.md
  • Summary section populated
  • Specification References table has at least one entry
  • Type of Change checkboxes marked
  • Testing section completed

Parameters:

• -Title (string, required): PR title to validate
• -Body (string, optional): PR description body
• -BodyFile (string, optional): Path to file containing PR body
• -FailOnViolation (switch): Exit with code 1 on validation failure (default: warning mode)

Output Format:
Return structured JSON with Success boolean and validation results:

{
  "Success": true/false,
  "Validations": {
    "ConventionalCommit": { "Status": "PASS/FAIL", "Message": "..." },
    "IssueKeywords": { "Status": "PASS/WARN", "Message": "...", "Keywords": [] },
    "TemplateCompliance": { "Status": "PASS/WARN", "Sections": {...} }
  },
  "Warnings": [],
  "Errors": []
}

Exit Codes:

• 0: All validations pass or warnings only (default mode)
• 1: Validation failures (when -FailOnViolation specified)
• 2: Usage/environment error

1.2 Integrate Validator into New-PR.ps1

Modify file:.claude/skills/github/scripts/pr/New-PR.ps1 in the Invoke-Validation function (lines 91-145):

Add Validation 4: PR Description Validation

After existing validations (Session End, Skill violations, Test coverage), add:

Write-Host ""
Write-Host "[4/4] Validating PR description..."
$validatePRScript = Join-Path $RepoRoot ".claude/skills/github/scripts/pr/Test-PRDescription.ps1"
if (Test-Path $validatePRScript) {
    $validationArgs = @('-Title', $Title)
    if ($Body) { $validationArgs += @('-Body', $Body) }
    elseif ($BodyFile) { $validationArgs += @('-BodyFile', $BodyFile) }
    
    & pwsh -NoProfile -File $validatePRScript @validationArgs
    # Note: Runs in warning mode (exit code 0 even with warnings)
    # Future: Add -FailOnViolation for blocking mode
}

Update validation counter from [3/3] to [4/4] in output messages.

1.3 Update GitHub Skill Documentation

Modify file:.claude/skills/github/SKILL.md:

Add to Decision Tree (after line 71):

   ├─ Validate PR description → Test-PRDescription.ps1

Add to Script Reference table (in PR Operations section, after line 103):

| `Test-PRDescription.ps1` | Validate PR description | `-Title`, `-Body`, `-BodyFile`, `-FailOnViolation` |

Add new section before "Anti-Patterns" (after line 135):

## GitHub Keywords for Issue Linking

GitHub automatically links and closes issues when PRs use specific keywords in:
- PR descriptions
- Commit messages
- PR comments

### Supported Keywords

| Keyword | Variations | Example |
|---------|-----------|---------|
| Closes | close, closed | `Closes #123` |
| Fixes | fix, fixed | `Fixes #456` |
| Resolves | resolve, resolved | `Resolves #789` |

### Usage Patterns

**In PR Descriptions:**
```markdown
## Summary
This PR adds feature X.

Closes #123
Fixes #456

In Commit Messages:

feat: Add feature X

Implements the new feature as specified in the plan.

Closes #123

Best Practices:

• Use keywords in PR description for primary issue
• Use keywords in commit bodies for related issues
• One keyword per line for clarity
• Place keywords in dedicated section or at end of description

### Phase 2: Agent Prompt Updates (1-2 hours)

#### 2.1 Update Implementer Agent Prompt

Modify `file:.claude/agents/implementer.md`:

**Update Commit Message Format section** (lines 436-445):

Replace existing section with:

```markdown
## Commit Message Format

Follow Conventional Commits with GitHub issue linking:

```text
<type>(<scope>): <short description>

<optional body explaining what and why>

Closes #<issue-number>
Refs: [Plan task reference]

Types: feat, fix, refactor, test, docs, chore, ci, build

GitHub Keywords: Use in commit body to auto-link/close issues:

• Closes #123 - Closes issue when PR merges
• Fixes #456 - Fixes issue when PR merges
• Resolves #789 - Resolves issue when PR merges
• Refs #101 - References without closing

Examples:

feat(auth): Add OAuth2 authentication

Implements OAuth2 flow with token refresh.
Adds middleware for protected routes.

Closes #234
Refs: planning/auth-implementation.md

fix(parser): Handle null values in JSON

Adds null checks before property access.
Prevents NullReferenceException in edge cases.

Fixes #567

Best Practices:

• Use Closes/Fixes/Resolves for issues this commit addresses
• Use Refs for related issues or documentation
• Place keywords in commit body, not title
• One keyword per line for clarity

#### 2.2 Update PR Comment Responder Agent Prompt

Modify `file:.claude/agents/pr-comment-responder.md`:

**Update Step 6.2: Batch Commit section** (lines 1082-1101):

Replace commit message example with:

```markdown
#### Step 6.2: Batch Commit

After implementing a logical group of changes (or single critical fix):

```bash
# Stage changes
git add [files]

# Commit with conventional message and issue reference
git commit -m "fix: [description]

Addresses PR review comment from @[reviewer]

- [Change 1]
- [Change 2]

Refs #[pr-number]
Comment-ID: [comment_id]"

# Push
git push origin [branch]

Commit Message Etiquette:

• Use conventional commit format: type: description
• Reference PR number with Refs #[number] in body
• Include Comment-ID: [id] for traceability
• Avoid Closes/Fixes in review response commits (reserve for main implementation)

**Update Step 6.3: Reply with Resolution section** (lines 1104-1126):

Add etiquette guidance after the code examples:

```markdown
**Response Format Best Practices:**

Follow the pattern: **Action + Location + Reference**

✅ **Good Examples:**
```text
Fixed in abc1234.

Updated validation logic to handle null values.

Refactored in def5678.

Extracted method to reduce complexity from 15 to 8.

❌ Avoid:

Done. (no context)
Fixed. (no commit reference)
I've updated the code. (vague)

Force Push Communication:

If force push is required (rebase, squash):

Force pushed to update commit history.

Previous: abc1234
Current: def5678

Changes: [brief explanation]

Thread Resolution Protocol:

• Auto-resolve bot comments after fixing
• Let human reviewers resolve their own threads
• Resolve only after: fix committed + reply posted

#### 2.3 Update QA Agent Prompt

Modify `file:.claude/agents/qa.md`:

**Add PR Description Validation to Pre-PR Quality Gate** (after line 366, before "### Pre-PR Validation Report"):

```markdown
#### Step 5: PR Description Validation

Verify PR description meets GitHub standards and template compliance:

```powershell
# Run PR description validator
pwsh .claude/skills/github/scripts/pr/Test-PRDescription.ps1 `
  -Title "[PR title]" `
  -BodyFile "[path-to-pr-body.md]"

Pass criteria:

• Title follows conventional commit format
• At least one GitHub keyword present (Closes/Fixes/Resolves)
• PR template sections completed:
  • Summary populated
  • Specification References table has entries
  • Type of Change marked
  • Testing section completed
  • Security Review section addressed

Evidence generation:

## PR Description Validation

| Check | Status | Details |
|-------|--------|---------|
| Conventional Commit Title | [PASS]/[FAIL] | [Title format] |
| Issue Keywords Present | [PASS]/[WARN] | [Keywords found: Closes #123] |
| Template Compliance | [PASS]/[WARN] | [Sections: 5/6 complete] |

**Missing Sections:**
- [Section name if incomplete]

**Update Validation Summary table** (line 380):

Add new row:
```text
| PR Description | [PASS]/[FAIL] | Yes |

Update gate count in text from "All 4 gates PASS" to "All 5 gates PASS" (line 418).

Update Verdict Decision Logic table (line 417):

| Condition | Verdict |
|-----------|---------|
| All 5 gates PASS | APPROVED |
| Any gate FAIL | BLOCKED |
| PR description warnings only AND other gates PASS | CONDITIONAL (document gap, proceed with warning) |

Phase 3: Command Enhancements (Optional - 30 minutes)

3.1 Update Push-PR Command

Modify file:.claude/commands/push-pr.md (after line 30, before step 4):

Add reminder step:

   - Title MUST follow conventional commit format (e.g., `feat: Add feature`, `fix(auth): Resolve bug`)
   - Body SHOULD include GitHub keywords to link issues:
     - `Closes #123` - Auto-closes issue when PR merges
     - `Fixes #456` - Auto-fixes issue when PR merges
     - `Resolves #789` - Auto-resolves issue when PR merges
   - Ensure PR template sections are completed

3.2 Create Validate PR Description Command

Create file:.claude/commands/validate-pr-description.md:

---
description: Validate PR description against GitHub standards
allowed-tools: [Bash(pwsh .claude/skills/github/scripts/pr/Test-PRDescription.ps1:*)]
---

# Validate PR Description Command

## Context

- PR title: [User provides]
- PR body file: [User provides path or content]

## Your task

Validate the PR description using the Test-PRDescription skill:

```bash
pwsh .claude/skills/github/scripts/pr/Test-PRDescription.ps1 \
  -Title "[title]" \
  -BodyFile "[path-to-body.md]"

Review the validation output and report:

1. Conventional commit title compliance
2. GitHub keyword presence (Closes/Fixes/Resolves)
3. PR template section completion
4. Any warnings or errors

Provide actionable recommendations for any validation failures.

### Verification & Testing

After implementation, validate with these test scenarios:

**Test 1: Valid PR Description**
- Title: `feat: Add user authentication`
- Body includes: `Closes #123`, all template sections filled
- Expected: All validations PASS

**Test 2: Missing Keywords**
- Title: `feat: Add feature`
- Body: No Closes/Fixes/Resolves keywords
- Expected: WARNING for missing keywords, validation continues

**Test 3: Invalid Title Format**
- Title: `Add new feature` (no type prefix)
- Expected: FAIL on conventional commit validation

**Test 4: Incomplete Template**
- Body missing Summary or Specification References
- Expected: WARNING for template compliance

**Test 5: Integration Test**
- Run `New-PR.ps1` with valid inputs
- Verify validator runs as 4th validation step
- Verify warnings displayed but PR creation proceeds

### Documentation Updates

Update the following documentation files:

1. **`file:.agents/AGENTS.md`** (if exists): Add note about GitHub keyword integration in agent prompts
2. **`file:.claude/skills/github/references/examples.md`** (if exists): Add examples using GitHub keywords
3. **`file:.claude/skills/github/references/patterns.md`** (if exists): Add PR description validation pattern

### Success Metrics Baseline

Establish baseline measurements before rollout:

| Metric | Measurement Method | Baseline Target |
|--------|-------------------|-----------------|
| PRs with issue keywords | GitHub API search `is:pr Closes OR Fixes OR Resolves` | Track current % |
| Template compliance | Manual review of last 10 PRs | Document current compliance rate |
| Validation script usage | Git log analysis of New-PR.ps1 calls | Track adoption after deployment |

### CI Integration (Future Enhancement)

For post-creation validation in CI pipeline:

1. Create GitHub Actions workflow: `file:.github/workflows/pr-description-validation.yml`
2. Trigger on PR open/edit events
3. Run `Test-PRDescription.ps1 -FailOnViolation`
4. Post validation report as PR comment
5. Set check status (pass/fail)

This is deferred to Phase 4 or future iteration based on Phase 1+2 results.

## Implementation Sequence

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant Cmd as push-pr command
    participant Skill as New-PR.ps1
    participant Val as Test-PRDescription.ps1
    participant GH as GitHub API

    Dev->>Cmd: Execute push-pr
    Cmd->>Skill: Call New-PR.ps1
    Skill->>Skill: Validate conventional commit (existing)
    Skill->>Val: Call Test-PRDescription.ps1
    Val->>Val: Check issue keywords
    Val->>Val: Check template compliance
    Val-->>Skill: Return validation results (warnings)
    Skill->>Skill: Run other validations
    Skill->>GH: Create PR (if validations pass)
    GH-->>Dev: PR created with URL
    
    Note over Val,Skill: Warning mode: continues even with warnings
    Note over Skill,GH: Future: Add -FailOnViolation for blocking mode

Risk Mitigation

Risk	Likelihood	Impact	Mitigation
False positives in keyword detection	Medium	Low	Use regex patterns that match GitHub's exact keyword list; provide clear warning messages
Agent prompt changes require iteration	Medium	Medium	Test with 5 PRs before full rollout; gather feedback from team
Validation adds friction to PR creation	Low	Medium	Run in warning mode initially; only block on critical failures
Template compliance too strict	Low	Low	Use warnings for template sections; only fail on missing critical fields

Rollout Strategy

1. Week 1: Implement Phase 1 (validation script + integration)
2. Week 2: Test with 5 PRs, gather feedback, tune thresholds
3. Week 3: Implement Phase 2 (agent prompt updates)
4. Week 4: Monitor adoption, document patterns, measure success metrics
5. Future: Consider Phase 3 (command enhancements) and Phase 4 (dedicated skill) based on results

Import In IDE

🤖 Prompt for AI Agents

## Observations

The repository has a well-established agent/skill/command infrastructure with PowerShell-based GitHub operations. The `file:.claude/skills/github/scripts/pr/New-PR.ps1` already validates conventional commit format and has a validation framework. Agent prompts (`implementer.md`, `pr-comment-responder.md`, `qa.md`) exist but lack GitHub keyword integration and PR etiquette patterns. The PR template (`file:.github/PULL_REQUEST_TEMPLATE.md`) already references issue linking keywords but lacks enforcement. No validation script for PR descriptions exists yet.

## Approach

Following the ticket's recommended Phase 1+2 approach (3-5 hours total), focusing on high-value, low-effort enhancements. Create a validation script within the existing github skill infrastructure, integrate it into the PR creation workflow in warning mode, and update agent prompts with keyword standards and etiquette patterns. This builds incrementally on existing patterns without introducing new complexity. Phase 3 and 4 are deferred as optional future enhancements.

## Implementation Plan

### Phase 1: Skill Enhancement (2-3 hours)

#### 1.1 Create PR Description Validator Script

Create `file:.claude/skills/github/scripts/pr/Test-PRDescription.ps1` with the following validation logic:

**Validation Checks:**
- **Issue Linking Keywords**: Detect presence of GitHub's 9 keywords (Closes, Fixes, Resolves with variations: close, closed, fix, fixed, resolve, resolved)
- **Conventional Commit Title**: Validate title format matches `type(scope)?: description` pattern
- **PR Template Compliance**: Check for required sections from `file:.github/PULL_REQUEST_TEMPLATE.md`
  - Summary section populated
  - Specification References table has at least one entry
  - Type of Change checkboxes marked
  - Testing section completed

**Parameters:**
- `-Title` (string, required): PR title to validate
- `-Body` (string, optional): PR description body
- `-BodyFile` (string, optional): Path to file containing PR body
- `-FailOnViolation` (switch): Exit with code 1 on validation failure (default: warning mode)

**Output Format:**
Return structured JSON with `Success` boolean and validation results:
```json
{
  "Success": true/false,
  "Validations": {
    "ConventionalCommit": { "Status": "PASS/FAIL", "Message": "..." },
    "IssueKeywords": { "Status": "PASS/WARN", "Message": "...", "Keywords": [] },
    "TemplateCompliance": { "Status": "PASS/WARN", "Sections": {...} }
  },
  "Warnings": [],
  "Errors": []
}
```

**Exit Codes:**
- 0: All validations pass or warnings only (default mode)
- 1: Validation failures (when `-FailOnViolation` specified)
- 2: Usage/environment error

#### 1.2 Integrate Validator into New-PR.ps1

Modify `file:.claude/skills/github/scripts/pr/New-PR.ps1` in the `Invoke-Validation` function (lines 91-145):

**Add Validation 4: PR Description Validation**

After existing validations (Session End, Skill violations, Test coverage), add:

```text
Write-Host ""
Write-Host "[4/4] Validating PR description..."
$validatePRScript = Join-Path $RepoRoot ".claude/skills/github/scripts/pr/Test-PRDescription.ps1"
if (Test-Path $validatePRScript) {
    $validationArgs = @('-Title', $Title)
    if ($Body) { $validationArgs += @('-Body', $Body) }
    elseif ($BodyFile) { $validationArgs += @('-BodyFile', $BodyFile) }
    
    & pwsh -NoProfile -File $validatePRScript @validationArgs
    # Note: Runs in warning mode (exit code 0 even with warnings)
    # Future: Add -FailOnViolation for blocking mode
}
```

Update validation counter from `[3/3]` to `[4/4]` in output messages.

#### 1.3 Update GitHub Skill Documentation

Modify `file:.claude/skills/github/SKILL.md`:

**Add to Decision Tree** (after line 71):
```text
   ├─ Validate PR description → Test-PRDescription.ps1
```

**Add to Script Reference table** (in PR Operations section, after line 103):
```text
| `Test-PRDescription.ps1` | Validate PR description | `-Title`, `-Body`, `-BodyFile`, `-FailOnViolation` |
```

**Add new section before "Anti-Patterns"** (after line 135):

```markdown
## GitHub Keywords for Issue Linking

GitHub automatically links and closes issues when PRs use specific keywords in:
- PR descriptions
- Commit messages
- PR comments

### Supported Keywords

| Keyword | Variations | Example |
|---------|-----------|---------|
| Closes | close, closed | `Closes #123` |
| Fixes | fix, fixed | `Fixes #456` |
| Resolves | resolve, resolved | `Resolves #789` |

### Usage Patterns

**In PR Descriptions:**
```markdown
## Summary
This PR adds feature X.

Closes #123
Fixes #456
```

**In Commit Messages:**
```text
feat: Add feature X

Implements the new feature as specified in the plan.

Closes #123
```

**Best Practices:**
- Use keywords in PR description for primary issue
- Use keywords in commit bodies for related issues
- One keyword per line for clarity
- Place keywords in dedicated section or at end of description
```

### Phase 2: Agent Prompt Updates (1-2 hours)

#### 2.1 Update Implementer Agent Prompt

Modify `file:.claude/agents/implementer.md`:

**Update Commit Message Format section** (lines 436-445):

Replace existing section with:

```markdown
## Commit Message Format

Follow Conventional Commits with GitHub issue linking:

```text
<type>(<scope>): <short description>

<optional body explaining what and why>

Closes #<issue-number>
Refs: [Plan task reference]
```

**Types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`, `build`

**GitHub Keywords**: Use in commit body to auto-link/close issues:
- `Closes #123` - Closes issue when PR merges
- `Fixes #456` - Fixes issue when PR merges  
- `Resolves #789` - Resolves issue when PR merges
- `Refs #101` - References without closing

**Examples:**

```text
feat(auth): Add OAuth2 authentication

Implements OAuth2 flow with token refresh.
Adds middleware for protected routes.

Closes #234
Refs: planning/auth-implementation.md
```

```text
fix(parser): Handle null values in JSON

Adds null checks before property access.
Prevents NullReferenceException in edge cases.

Fixes #567
```

**Best Practices:**
- Use `Closes/Fixes/Resolves` for issues this commit addresses
- Use `Refs` for related issues or documentation
- Place keywords in commit body, not title
- One keyword per line for clarity
```

#### 2.2 Update PR Comment Responder Agent Prompt

Modify `file:.claude/agents/pr-comment-responder.md`:

**Update Step 6.2: Batch Commit section** (lines 1082-1101):

Replace commit message example with:

```markdown
#### Step 6.2: Batch Commit

After implementing a logical group of changes (or single critical fix):

```bash
# Stage changes
git add [files]

# Commit with conventional message and issue reference
git commit -m "fix: [description]

Addresses PR review comment from @[reviewer]

- [Change 1]
- [Change 2]

Refs #[pr-number]
Comment-ID: [comment_id]"

# Push
git push origin [branch]
```

**Commit Message Etiquette:**
- Use conventional commit format: `type: description`
- Reference PR number with `Refs #[number]` in body
- Include `Comment-ID: [id]` for traceability
- Avoid `Closes/Fixes` in review response commits (reserve for main implementation)
```

**Update Step 6.3: Reply with Resolution section** (lines 1104-1126):

Add etiquette guidance after the code examples:

```markdown
**Response Format Best Practices:**

Follow the pattern: **Action + Location + Reference**

✅ **Good Examples:**
```text
Fixed in abc1234.

Updated validation logic to handle null values.
```

```text
Refactored in def5678.

Extracted method to reduce complexity from 15 to 8.
```

❌ **Avoid:**
```text
Done. (no context)
Fixed. (no commit reference)
I've updated the code. (vague)
```

**Force Push Communication:**

If force push is required (rebase, squash):
```text
Force pushed to update commit history.

Previous: abc1234
Current: def5678

Changes: [brief explanation]
```

**Thread Resolution Protocol:**
- Auto-resolve bot comments after fixing
- Let human reviewers resolve their own threads
- Resolve only after: fix committed + reply posted
```

#### 2.3 Update QA Agent Prompt

Modify `file:.claude/agents/qa.md`:

**Add PR Description Validation to Pre-PR Quality Gate** (after line 366, before "### Pre-PR Validation Report"):

```markdown
#### Step 5: PR Description Validation

Verify PR description meets GitHub standards and template compliance:

```powershell
# Run PR description validator
pwsh .claude/skills/github/scripts/pr/Test-PRDescription.ps1 `
  -Title "[PR title]" `
  -BodyFile "[path-to-pr-body.md]"
```

**Pass criteria:**

- Title follows conventional commit format
- At least one GitHub keyword present (Closes/Fixes/Resolves)
- PR template sections completed:
  - Summary populated
  - Specification References table has entries
  - Type of Change marked
  - Testing section completed
  - Security Review section addressed

**Evidence generation:**

```markdown
## PR Description Validation

| Check | Status | Details |
|-------|--------|---------|
| Conventional Commit Title | [PASS]/[FAIL] | [Title format] |
| Issue Keywords Present | [PASS]/[WARN] | [Keywords found: Closes #123] |
| Template Compliance | [PASS]/[WARN] | [Sections: 5/6 complete] |

**Missing Sections:**
- [Section name if incomplete]
```
```

**Update Validation Summary table** (line 380):

Add new row:
```text
| PR Description | [PASS]/[FAIL] | Yes |
```

**Update gate count** in text from "All 4 gates PASS" to "All 5 gates PASS" (line 418).

**Update Verdict Decision Logic table** (line 417):

```text
| Condition | Verdict |
|-----------|---------|
| All 5 gates PASS | APPROVED |
| Any gate FAIL | BLOCKED |
| PR description warnings only AND other gates PASS | CONDITIONAL (document gap, proceed with warning) |
```

### Phase 3: Command Enhancements (Optional - 30 minutes)

#### 3.1 Update Push-PR Command

Modify `file:.claude/commands/push-pr.md` (after line 30, before step 4):

Add reminder step:

```markdown
   - Title MUST follow conventional commit format (e.g., `feat: Add feature`, `fix(auth): Resolve bug`)
   - Body SHOULD include GitHub keywords to link issues:
     - `Closes #123` - Auto-closes issue when PR merges
     - `Fixes #456` - Auto-fixes issue when PR merges
     - `Resolves #789` - Auto-resolves issue when PR merges
   - Ensure PR template sections are completed
```

#### 3.2 Create Validate PR Description Command

Create `file:.claude/commands/validate-pr-description.md`:

```markdown
---
description: Validate PR description against GitHub standards
allowed-tools: [Bash(pwsh .claude/skills/github/scripts/pr/Test-PRDescription.ps1:*)]
---

# Validate PR Description Command

## Context

- PR title: [User provides]
- PR body file: [User provides path or content]

## Your task

Validate the PR description using the Test-PRDescription skill:

```bash
pwsh .claude/skills/github/scripts/pr/Test-PRDescription.ps1 \
  -Title "[title]" \
  -BodyFile "[path-to-body.md]"
```

Review the validation output and report:
1. Conventional commit title compliance
2. GitHub keyword presence (Closes/Fixes/Resolves)
3. PR template section completion
4. Any warnings or errors

Provide actionable recommendations for any validation failures.
```

### Verification & Testing

After implementation, validate with these test scenarios:

**Test 1: Valid PR Description**
- Title: `feat: Add user authentication`
- Body includes: `Closes #123`, all template sections filled
- Expected: All validations PASS

**Test 2: Missing Keywords**
- Title: `feat: Add feature`
- Body: No Closes/Fixes/Resolves keywords
- Expected: WARNING for missing keywords, validation continues

**Test 3: Invalid Title Format**
- Title: `Add new feature` (no type prefix)
- Expected: FAIL on conventional commit validation

**Test 4: Incomplete Template**
- Body missing Summary or Specification References
- Expected: WARNING for template compliance

**Test 5: Integration Test**
- Run `New-PR.ps1` with valid inputs
- Verify validator runs as 4th validation step
- Verify warnings displayed but PR creation proceeds

### Documentation Updates

Update the following documentation files:

1. **`file:.agents/AGENTS.md`** (if exists): Add note about GitHub keyword integration in agent prompts
2. **`file:.claude/skills/github/references/examples.md`** (if exists): Add examples using GitHub keywords
3. **`file:.claude/skills/github/references/patterns.md`** (if exists): Add PR description validation pattern

### Success Metrics Baseline

Establish baseline measurements before rollout:

| Metric | Measurement Method | Baseline Target |
|--------|-------------------|-----------------|
| PRs with issue keywords | GitHub API search `is:pr Closes OR Fixes OR Resolves` | Track current % |
| Template compliance | Manual review of last 10 PRs | Document current compliance rate |
| Validation script usage | Git log analysis of New-PR.ps1 calls | Track adoption after deployment |

### CI Integration (Future Enhancement)

For post-creation validation in CI pipeline:

1. Create GitHub Actions workflow: `file:.github/workflows/pr-description-validation.yml`
2. Trigger on PR open/edit events
3. Run `Test-PRDescription.ps1 -FailOnViolation`
4. Post validation report as PR comment
5. Set check status (pass/fail)

This is deferred to Phase 4 or future iteration based on Phase 1+2 results.

## Implementation Sequence

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant Cmd as push-pr command
    participant Skill as New-PR.ps1
    participant Val as Test-PRDescription.ps1
    participant GH as GitHub API

    Dev->>Cmd: Execute push-pr
    Cmd->>Skill: Call New-PR.ps1
    Skill->>Skill: Validate conventional commit (existing)
    Skill->>Val: Call Test-PRDescription.ps1
    Val->>Val: Check issue keywords
    Val->>Val: Check template compliance
    Val-->>Skill: Return validation results (warnings)
    Skill->>Skill: Run other validations
    Skill->>GH: Create PR (if validations pass)
    GH-->>Dev: PR created with URL
    
    Note over Val,Skill: Warning mode: continues even with warnings
    Note over Skill,GH: Future: Add -FailOnViolation for blocking mode
```

## Risk Mitigation

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| False positives in keyword detection | Medium | Low | Use regex patterns that match GitHub's exact keyword list; provide clear warning messages |
| Agent prompt changes require iteration | Medium | Medium | Test with 5 PRs before full rollout; gather feedback from team |
| Validation adds friction to PR creation | Low | Medium | Run in warning mode initially; only block on critical failures |
| Template compliance too strict | Low | Low | Use warnings for template sections; only fail on missing critical fields |

## Rollout Strategy

1. **Week 1**: Implement Phase 1 (validation script + integration)
2. **Week 2**: Test with 5 PRs, gather feedback, tune thresholds
3. **Week 3**: Implement Phase 2 (agent prompt updates)
4. **Week 4**: Monitor adoption, document patterns, measure success metrics
5. **Future**: Consider Phase 3 (command enhancements) and Phase 4 (dedicated skill) based on results

---

Execution Information

Branch: main
Commit: 9ee36e0

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.