tekBlueprint

Process Decision Record (PDR) – is a documented practice for recording decisions to change, introduce, or cancel processes within a team. While an ADR answers the question of which architecture to choose, a PDR defines how the team will work.

One of the most common problems on projects is processes that simply “evolved historically” or didn’t evolve at all. For example:

• We perform code reviews according to these rules because that’s how it’s been done, though it’s unclear by whom and when.
• We hold retrospectives because the methodology requires it.
• We conduct demos with unclear goals and subsequent steps because that’s how it was done before.
• Releases and application delivery are performed by one person, and the steps of this process are not formalized or are insufficiently formalized.

Someone might have an understanding of why all this is needed and what problem it solves. In other cases, there are effectively no processes, and everything is managed manually without any formalized logic. But as soon as that person leaves the project, the processes are left without an owner and without any understanding of how to maintain them or why they exist.

As a result, the team spends resources on process activities for which the cost is unclear, there are no review criteria, and it is not clear whether they solve the problem for which they were originally introduced. To mitigate such situations, PDR can be used.

Goals of Using PDR

PDRs record decisions regarding team workflows: ceremonies, work processes, policies, quality metrics (quality gates), and interaction rules. They do not replace architectural decisions but complement them. Even a perfect architecture won’t save you if the team doesn’t understand how to work with it.

Main goals:

• Traceability of decisions and the logic behind them.
• Transparency – new team members understand why a particular process exists.
• Knowledge preservation – not repeating mistakes that have already been made.
• Opportunity for constructive challenge of a process before its implementation.
• Assessment of the cost of process activities (time, resources, delay).
• Measurability – the ability to evaluate whether the change brought the expected effect.
• Ability to review and cancel processes when the context changes.
• Identification of risks and negative factors before they become a problem.
• Faster onboarding for newcomers.

Scope of Application

PDR covers changes in how the team organizes its work:

• Agile ceremonies (if work is organized according to such methodologies): daily calls, retrospectives, planning, and so on.
• Technical practices such as code review, pair programming, and evaluation of completion criteria (definition of done).
• An existing process is changed or adapted to a new reality (remote work, team change, project growth).
• Introduction or cancellation of systems for task tracking, notifications, and communication.
• Definition of roles and areas of responsibility, who does what, and how results are handed over.
• Definition of communication practices: internal and external.
• Adjustment of the context around a process – the team has tripled in size, the project has moved to support, or the client has changed.
• There is a reasonable suspicion that the process has stopped solving the problem for which it was created.

It is important not to confuse PDR with ADR. ADR records decisions about the system structure – choice of technologies, patterns, approaches to code organization. PDR records decisions about the workflow structure – how the team communicates, how it makes decisions, and how it evaluates quality.

The same project can contain both ADRs and PDRs. For example, an ADR may record the decision to use PostgreSQL, and a PDR may record the decision for mandatory code review before merging into the main branch.

Besides PDR and ADR, there is another variation – Product Decision Record, which records decisions about product behavior and its functional boundaries. For example: “AI-generated messages must remain in drafts until checked by a human”. But this is not part of this article.

PDR Structure

A PDR card should be short, maximum 1–2 pages. The more complex the process, the more important it is to be specific rather than using vague formulations like “we believe this will help”.

Minimum set of fields:

1. Identifier – a unique number (e.g., PDR-001).
2. Title – concise, covering the essence of the process.
3. Date – when the decision was recorded.
4. Review date – when to return to the process and evaluate its relevance.
5. Authors – who initiated it.
6. Status – proposed, accepted, rejected, superseded.
7. Context – current situation, problem, or opportunity that the process solves.
8. Decision – what exactly is being introduced or changed.
9. Process cost – team time, delay, financial costs. Optional, but highly desirable.
10. Considered alternatives – other options, their pros and cons. Even rejected options are useful.
11. Rationale – why this particular option was chosen.
12. Risks and negative factors – what could go wrong and what to expect.
13. Expected impact – consequences for the team, stakeholders, and product quality.
14. Success or failure indicators – how to measure whether the decision worked (metrics, observations, feedback from retros).
15. Further steps – what subsequent actions are planned, when the review is.

Below is a practical Markdown template, adapted from MADR with a focus on process decisions.

---
status: "{proposed | accepted | rejected | deprecated | superseded by PDR-XXX}"
date: {YYYY-MM-DD}
author: {who made the decision}
stakeholders: {who is involved in the process}
review-date: {YYYY-MM-DD -- next review date}
---

# {Short title of the process}

## Context and Problem Statement

{Describe the situation that required the introduction of the process. What task does it close? What was there before it? Why was it not enough to simply leave it as it was?}

## Decision Outcome

{Clearly formulate what is being introduced or changed.}

## Process Cost

{What is the cost of the process? Team time in hours or person-days, delay in Time to Market. Financial costs for tools or infrastructure.}

## Considered Alternatives

* {Alternative 1} -- {pros}, {cons}
* {Alternative 2} -- {pros}, {cons}
* ...

## Rationale

{Why this particular option was chosen. What criteria influenced the decision.}

## Consequences

* {Risk 1 and its possible consequence}
* {Risk 2}
* ...

## Review Criteria

{Based on what signs should this decision be revisited? For example: "If the team grows beyond Y people"; "If the time for the process exceeds Z hours per sprint".}

## Expected Impact

* {Impact on the team}
* {Impact on quality}
* {Impact on deadlines}
* ...

## Success or Failure Indicators

* {Quantitative: how much time the process saves, how many errors it catches, etc.}
* {Qualitative: team feedback, subjective observations}
* ...

## Further Steps

* {What to do after implementation and when to review}

## Links

{Links to discussions, tickets, notes from workshops.}

PDR Lifecycle

PDRs have a certain lifecycle:

1. Creation – any team member can initiate a PDR. Ideally, this happens before the change is implemented, not after the fact.
2. Discussion – the PDR is submitted for team review. The goal is to identify objections, clarifications, and missing aspects.
3. Publication – the accepted decision is placed in a common repository. All participants and stakeholders must have access to it.
4. Monitoring – the team tracks success indicators. If the decision works, the process remains. If not, the PDR is updated or replaced by a new one.
5. Archiving – rejected PDRs are not deleted. They are kept as a historical record so as not to analyze the same things again.

Tools

PDRs, like ADRs, are ordinary text files in Markdown. The same tools are suitable:

• Log4brains
• adr-viewer
• MADR.

The format is the same; the only difference is the content.

PDRs can be stored in a separate directory (docs/pdr/), next to docs/adr/. Or in a general decision registry by adding a type: process field for distinction. In small projects, a single docs/decisions/ folder is sufficient.

Limitations and Pitfalls

PDRs are useful but not universal. A couple of points to keep in mind:

• Writing them takes time, which is time taken away from development. But in the long run, the savings on re-discussing the same issues outweigh the costs.
• The most likely risk is excessive bureaucracy. PDRs should not turn into an administrative routine or become a barrier to change. Not every decision requires a full card.
• A PDR records a decision but does not guarantee that it is correct. Common sense is still needed.
• If the registry is available outside the team, it should be noted that some process decisions may be sensitive to publication for the team.

Conclusion

A Process Decision Record makes transparent what usually lives in people’s heads: why a particular process was introduced, how much it costs, and when it is time to review it. Without PDRs, processes are not tracked. Once an activity is started, it is never canceled, even when it stops solving the problem for which it was created.

PDRs are not static. They need to be reviewed regularly, no less frequently than the date specified in the card. And it is the success and failure indicators, not mood, that should dictate when a process is changed, improved, or removed.