dss/.knowledge/adrs/archived/operational/PR_TEMPLATE_UPDATE.md

PR Template Update: DSS Principles Check

This document shows how to integrate the Architecture Decision Records (ADRs) into your existing pull request workflow.

Effort: 2 minutes to add to existing PR template
Impact: Connects code changes to architectural decisions and principles

---

Current PR Template (Example)

If your project doesn't have a PR template, start with this structure:

## Description
Brief summary of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Closes #[issue number]

## Testing
How to verify this works.

## Screenshots (if applicable)
Helpful for UI changes.

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-reviewed my own code
- [ ] Tests pass locally

---

Where to Add the DSS Principles Check

Add this section just before the Checklist (at the end, right before closing the template):

## DSS Principles Check

- **ADR Link**: If this PR implements a decision from `.knowledge/adrs/`, link it here.  
  Example: `Implements ADR-003: Use SQLite for Local Caching`

- **Principle Alignment**: Which DSS principles does this work advance? Explain briefly.  
  Example: `Supports Single Source of Truth by centralizing token storage; supports Knowledge Persistence by documenting the caching strategy in ADR-003`

---

Complete Updated Template (Full Example)

## Description
Brief summary of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Closes #[issue number]

## Testing
How to verify this works.

## Screenshots (if applicable)
Helpful for UI changes.

## DSS Principles Check

- **ADR Link**: If this PR implements a decision from `.knowledge/adrs/`, link it here.  
  Example: `Implements ADR-003: Use SQLite for Local Caching`

- **Principle Alignment**: Which DSS principles does this work advance? Explain briefly.  
  Example: `Supports Single Source of Truth by centralizing token storage; supports Knowledge Persistence by documenting the caching strategy in ADR-003`

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-reviewed my own code
- [ ] Tests pass locally

---

How to Update Your PR Template

Option 1: GitHub PR Template File

If you're using GitHub, your PR template is usually at one of these locations:

.github/pull_request_template.md
docs/pull_request_template.md
pull_request_template.md

To update:

1. Open the file
2. Add the "DSS Principles Check" section before the "Checklist"
3. Commit the change
4. All future PRs will automatically include the new section

Option 2: GitLab, Gitea, or Other Platforms

Check your platform's documentation for PR template location, but the process is the same: add the section to your template file.

Option 3: If You Don't Have a Template Yet

Create a new file at .github/pull_request_template.md (for GitHub) with the complete template above.

---

Good Examples vs. Anti-Patterns

✅ Good: Clear ADR Reference + Principle Alignment

## DSS Principles Check

- **ADR Link**: Implements ADR-005: Use async/await for Figma API calls
- **Principle Alignment**: Supports MCP First by using async-native patterns; 
  supports Foundational Contracts by documenting API call assumptions in the ADR

Why this works: Clear reference to a specific ADR; explicit connection to principles with reasoning.

---

✅ Good: No ADR (Because This PR Doesn't Implement a Significant Decision)

## DSS Principles Check

- **ADR Link**: N/A (refactor of existing pattern)
- **Principle Alignment**: No principle alignment—this is a straightforward refactor. 
  See code comments for details.

Why this works: Honest acknowledgment that not every PR needs an ADR. That's fine.

---

⚠️ Anti-Pattern: Vague Principle Claims

## DSS Principles Check

- **ADR Link**: ADR-001
- **Principle Alignment**: Supports all principles

Problem: Generic claim without explanation. Forces reviewer to guess what you mean.
Better: Be specific. Name 1-2 principles and explain the connection.

---

⚠️ Anti-Pattern: ADR Reference That Doesn't Exist

## DSS Principles Check

- **ADR Link**: Implements ADR-042 (which doesn't actually exist)
- **Principle Alignment**: Aligns with Principle X

Problem: Creates confusion and breaks traceability.
Better: Only reference ADRs that actually exist. If you're creating a new ADR, reference it after it's created and merged.

---

For Code Reviewers

When reviewing a PR with the DSS Principles Check section:

1. Verify the ADR exists: If an ADR is referenced, confirm it's in .knowledge/adrs/ and is relevant to the PR
2. Check principle alignment: Does the PR actually support the principles claimed? If vague, ask for clarification
3. Allow flexibility: Not every PR needs an ADR. Small bug fixes and refactors don't require principle alignment statements
4. Encourage good ADRs: If a PR involves a significant decision but no ADR exists, ask: "Should we create an ADR for this decision?"

---

Implementation Timeline

Week 1 (Kickoff Week):

• Update your PR template file with the "DSS Principles Check" section
• Commit the change to git
• Mention the update in the kickoff meeting

Weeks 2-3 (Pilot Phase):

• Pilot team creates 1-3 ADRs
• PRs implementing those decisions link the ADR in this section
• Reviewers validate the connections

Week 4 (Retrospective):

• Gather feedback: Was the PR template addition helpful or burdensome?
• Adjust if needed (e.g., move section, simplify language, add more examples)

---

FAQ

Q: Do I have to fill in the DSS Principles Check for every PR?
A: No. Only PRs that implement a significant decision (with an ADR) need the ADR Link. The Principle Alignment field is optional for small PRs.

Q: What if I'm not sure if my PR needs an ADR?
A: Ask yourself: "Will someone in 6 months ask, 'Why did we make this choice?'" If yes, it probably warrants an ADR. When in doubt, ask during code review.

Q: Can I reference an ADR that's still in "Proposed" status?
A: Yes. "Proposed" means it's being considered but not yet finalized. Once there's consensus, it moves to "Accepted." Referencing a "Proposed" ADR is fine; it just means the decision isn't final yet.

Q: What if someone disagrees with the ADR I'm implementing?
A: That's what code review is for. If there's a concern about the decision itself (not just the implementation), the ADR should be revisited. This is healthy.

Q: Should the ADR be created before the PR, or as part of it?
A: Ideally, before the PR. The ADR documents the decision, and the PR implements it. But if you're still finalizing the decision during the PR, you can create the ADR in the PR and reference it. Flexibility is fine during the pilot.

---

Template Customization Checklist

Before finalizing your PR template:

• Check your current PR template location (.github/pull_request_template.md or equivalent)
• Copy the "DSS Principles Check" section from above
• Insert it before the "Checklist" section (or at the end if no checklist)
• Test it by opening a draft PR and confirming the section appears
• Mention the change during the kickoff meeting so the team knows what to expect

---

Connection to Other Documents

• ADR Template: .knowledge/adrs/000-template.md
• ADR README: .knowledge/adrs/README.md
• PRINCIPLES.md: /docs/01_core/PRINCIPLES.md (reference for principle names)
• Kickoff Agenda: .knowledge/adrs/KICKOFF_AGENDA.md (mentions PR integration during demo)

---

Status: Ready to customize and commit
Pilot Project: dss_sync_figma
Created: 2025-12-08
Next Action: Add to your platform's PR template and commit