ALD Pull Request Template

This PR template is designed for Architect-Led Development (ALD). It separates contract changes from implementation changes, emphasizes role-based interfaces, and uses tests as behavioral proof.

View the template Download (.md) How to use
Key properties
Contracts first Role-based Test-defined AI-friendly SOLID-grounded Boundary-aware

How to use (ALD workflow)

What this enforces

  • Contracts (interfaces/DTOs) are reviewed explicitly
  • Behavior changes are expressed as test changes
  • Adapters stay at the edges (ports & translation)
  • Observability and rollback are treated as first-class
  • AI usage is declared and bounded

Best review order

  1. Contract tests: do they define intent?
  2. Role interfaces: SRP/ISP intact?
  3. DTOs: language + invariants correct?
  4. Boundaries: adapters/ACL at edges?
  5. Implementation: readable and compliant?

Template (Markdown)

Copy/paste the Markdown below into your repo's PR/MR template location. 

# Summary
<!-- 2–6 sentences. What changed and why? Link to work item(s) if applicable. -->

## Type of change (check all that apply)
- [ ] Contract change (interfaces / DTOs / public API surface)
- [ ] Contract tests change (behavior/policy change)
- [ ] Implementation only (no contract surface changes)
- [ ] Adapter / integration change (vendor/infra boundary)
- [ ] Observability / operational change
- [ ] Refactor (no behavior change)
- [ ] Bug fix
- [ ] Security change

---

# ALD Contract Surface

## Roles / Interfaces touched
<!-- List role-based interfaces (not layers). -->
- Role(s):
  - `...`
  - `...`

### Role responsibility check
- [ ] Role names are responsibility-based (not layer-based)
- [ ] Each role remains single-responsibility (SRP)
- [ ] No "kitchen sink" interface expansion (ISP)

## DTOs / Domain Types touched
<!-- List DTOs/types and what meaning/invariants changed. -->
- DTOs / Types:
  - `...` — change:
  - `...` — change:

### DTO guardrails
- [ ] Names reflect ubiquitous language
- [ ] Invariants are enforced (invalid states are hard to represent)
- [ ] Cross-context leakage avoided (no shared domain model)

## Error model / reason codes
<!-- What are the error outcomes? Are reason codes/audit fields impacted? -->
- Errors/Reason Codes:
  - `...`

- [ ] Error model is explicit and tested
- [ ] Any new reason codes are documented in tests

---

# Tests (Behavior Proof)

## Contract tests
<!-- What contract tests define/changed behavior? Link to files or describe scenarios. -->
- Added/updated contract tests:
  - `...`

- [ ] Contract tests read like business rules
- [ ] Negative/edge cases included (limits, invalid inputs, auth failures, etc.)
- [ ] Tests are deterministic (no time/randomness/external flakiness)

## Implementation unit tests
- Added/updated unit tests:
  - `...`

## Test results
<!-- Paste CI summary or key outputs; links are fine -->
- [ ] All tests pass locally or in CI
- Evidence:
  - CI link:
  - Notes:

---

# Dependencies & Boundaries (Ports/Adapters)

## External dependencies touched
<!-- DBs, queues, 3rd party APIs, frameworks, SDKs -->
- `...`

- [ ] External systems accessed only through ports/adapters
- [ ] No vendor/framework types leaked into core/domain logic
- [ ] Mapping/translation exists at the boundary (ACL where appropriate)

## Resilience / Idempotency (if applicable)
- [ ] Retries/timeouts/circuit breaking follow standard approach
- [ ] Idempotency considered (especially for event/message handlers)

---

# Observability & Ops

## Telemetry added/updated
- [ ] Logs
- [ ] Metrics
- [ ] Traces
- [ ] Correlation IDs propagated

Details:
- `...`

## Failure modes / rollback
- Expected failure modes and behavior:
  - `...`
- Rollback strategy:
  - [ ] Safe rollback available (feature flag / strategy selection / revert)
  - Notes:

---

# Security / Governance

- [ ] Authorization handled via explicit policy/role where needed
- [ ] Least privilege considered (access scope & credentials)
- [ ] Data classification/handling requirements met (if relevant)
- [ ] Audit evidence preserved (reason codes / decision metadata)

---

# Backwards compatibility / Risk

## Compatibility
- [ ] Backwards compatible
- [ ] Breaking change (explain and provide migration path)

Migration notes:
- `...`

## Risk assessment
- Risk level:
  - [ ] Low (implementation-only behind stable contracts)
  - [ ] Medium (behavior change but contract shape stable)
  - [ ] High (contract surface change / cross-cutting impact)

Mitigations:
- `...`

---

# AI Usage (if applicable)
- [ ] AI-assisted implementation was used
- Scope:
  - [ ] Interface/DTO design (usually should be human-owned)
  - [ ] Contract tests (human-reviewed)
  - [ ] Implementations (common/expected)
  - [ ] Unit tests (common/expected)

Notes:
- What did you verify manually?
- Anything you changed after AI generation?

---

# Reviewer Checklist (quick)
- [ ] Contracts match intent; names are role-based
- [ ] Contract tests clearly define behavior; edge cases covered
- [ ] Boundaries are clean; adapters at the edges
- [ ] Observability and failure modes are acceptable
- [ ] Change risk classification makes sense

Notes and recommended repo placement

GitHub

  • Default template location: .github/pull_request_template.md
  • Multiple templates: .github/PULL_REQUEST_TEMPLATE/*.md

GitLab

  • MR templates are typically stored in .gitlab/merge_request_templates/
  • Set a default MR template in project settings (or via conventions)