Skip to content
Toprent.app Docs

1. Record team decisions

Date: 2025-10-01

Status

Accepted

Context

The team makes decisions about processes, workflows, and best practices that impact how we work together. These decisions are often made in meetings or discussions but are not always documented, leading to:

  • Loss of context when team members change
  • Repeated discussions about the same topics
  • Inconsistent application of agreed-upon processes
  • Difficulty onboarding new team members

We need a lightweight way to record these team-level decisions, separate from architectural decisions (which are captured in ADRs).

Decision

We will use Team Decision Records (TDRs), following a format similar to ADRs but focused on team processes and practices.

Each TDR will be:

  • Numbered sequentially (0001, 0002, etc.)
  • Stored in docs/tdr/
  • Written in Markdown
  • Follow the standard format described in the template below

TDR Format

# [NUMBER]. [SHORT TITLE]


Date: YYYY-MM-DD


## Status


[Proposed | Accepted | Deprecated | Superseded by TDR-XXXX]


## Context


What is the issue we're trying to address? What are the current challenges or pain points?
Describe the team, workflow, or process forces at play.


## Decision


What is the team decision? Use active voice.
Be specific about who does what, when, and how.


## Consequences


What are the positive, negative, and neutral impacts of this decision?
- How will this affect daily work?
- What new habits or processes need to be adopted?
- What existing practices will change?
- Are there any tradeoffs or risks?


## Review Schedule (Optional)


When should this decision be reviewed? Some processes may need periodic evaluation.


## Related Decisions (Optional)


List any TDRs that this decision builds upon or relates to. Link to older TDRs only.

Consequences

Positive

  • Team decisions are documented and accessible to all team members
  • New team members can understand why we work the way we do
  • Reduces repeated discussions about already-decided topics
  • Creates accountability for implementing agreed-upon processes
  • Provides a clear history of process evolution

Negative

  • Requires discipline to document decisions (not all discussions will be recorded)
  • Takes time to write TDRs (though they should be kept short)

Neutral

  • TDRs complement ADRs by focusing on team processes rather than technical architecture
  • Old TDRs will remain in the repository even when superseded, preserving historical context

Examples of TDR Topics

  • Sprint planning process
  • Ticket triaging workflow
  • PR review expectations and timelines
  • Definition of done
  • Meeting schedules and formats
  • Code review standards
  • Communication protocols
  • On-call rotation policies