ADR Template for Microsoft Teams — Loop, Planner, and Channel-Based Review

Teams Wiki is deprecated — what replaced it

Microsoft Teams Wiki Classic was officially deprecated in January 2024. Existing wiki content was migrated to OneNote pages (with Teams inserting a "View in OneNote" tab replacing each wiki tab). New wiki tabs can no longer be created in Teams channels. Teams engineering teams that had been using the Teams Wiki as an informal ADR store lost their primary documentation surface without a direct Teams-native replacement.

The current alternatives, in order of fit for ADR practice:

1. Microsoft Loop — the closest equivalent to the collaborative document experience of Teams Wiki. Loop pages support real-time co-editing, headings, tables, code blocks, and version history. ADR documents feel natural in Loop: one page per decision, structured sections (Context, Decision, Consequences, Alternatives Considered), shareable via link. Loop pages can be embedded in Teams channels as Loop components for inline visibility.
2. SharePoint document library (Teams Files tab) — for teams that want Markdown files with a version history closer to a git model. The Teams Files tab is backed by SharePoint. Store .md files per ADR in the channel's Files tab — SharePoint preserves version history and supports document-level sharing. Limitation: no syntax highlighting, no PR-based review, no CI validation.
3. OneNote (Teams tab) — suitable for teams that already use OneNote extensively and want meeting-style ADR drafts embedded alongside meeting notes. Limitation: OneNote's free-form structure makes consistent ADR formatting difficult to enforce.

For most engineering teams, Loop is the right default for Teams-native ADR practice. The rest of this page uses Loop as the primary ADR document surface.

The ADR template for a Microsoft Loop page

The standard Nygard ADR format translates directly to a Loop page. The following template includes two Teams-specific fields (Review channel and Review deadline) that support the announce-then-silence governance ceremony:

# ADR-0043 — [Decision title — name the decision, not the problem]

**Status:** Proposed
**Date:** 2026-06-04
**Deciders:** @alice, @bob, @carol
**Review channel:** #architecture-decisions · Thread: [link to Teams post]
**Review deadline:** 2026-06-11 17:00 UTC

---

## Context

[What is the situation? What constraints, requirements, or forces led to this decision
point? Write for an engineer who was not in any of the related meetings.]

## Decision

[One active-voice sentence: "We will use..." / "We chose..." / "We will not..."]

## Consequences

[What does this decision make easier? What does it make harder? Include at least
one honest downside — an ADR with only positive consequences is a press release.]

## Alternatives Considered

### Option A — [Name]
[What was it? Why was it rejected?]

### Option B — [Name]
[What was it? Why was it rejected?]

Teams-specific fields explained

Review channel: The Teams channel where the announcement post was made, with a link to the specific thread. This creates a permanent cross-reference between the ADR document (in Loop) and the review conversation (in Teams). When someone later asks "who reviewed this decision?", the thread link answers without needing to search the channel.

Review deadline: An explicit calendar date and UTC time. Vague deadlines ("this sprint", "end of week") create governance disputes in distributed teams across timezones. The deadline in the ADR document and in the announcement post should be identical.

Status lifecycle in a Loop page

Update the Status field when the decision state changes. The minimal viable lifecycle:

Governance via Teams channels — the announce-then-silence ceremony

Teams channels are the natural governance surface for the announce-then-silence pattern in a Microsoft 365 organization. The ceremony:

1. Create the ADR as a Loop page. Fill all fields including the review deadline. Leave Status as Proposed.
2. Post an announcement in the relevant Teams channel. Use a Markdown-formatted channel message. Include:
   • A one-line summary of the decision ("We're switching the payments service to an async message queue")
   • A link to the Loop page
   • @mentions for each stakeholder who should review (e.g., leads of dependent services, platform team, security if applicable)
   • The explicit deadline with UTC timezone ("Finalizing this decision by Thursday 2026-06-11 17:00 UTC — reply here with any blocking objection before then")
3. Do not follow up. No reminder messages, no synchronous meeting required. The announcement is the notification. The burden is on reviewers to raise a blocking objection, not on the author to chase approval.
4. At the deadline: if no blocking reply was posted in the thread, update the ADR Status to Active and reply to the announcement thread ("Finalized — no blocking objections received"). If a blocking reply was received, address it in a Loop page revision and announce a new deadline.

What counts as a blocking objection

Define this explicitly in your team's governance doc (a separate Loop page or Notion/SharePoint document) to avoid disputes. A blocking objection is:

• A factual error in the Alternatives Considered section that changes the Decision
• A missing stakeholder — the decision affects a team that wasn't notified
• A constraint violation — the decision conflicts with an existing Active ADR or a non-negotiable architectural constraint

What is NOT a blocking objection: a preference for a different choice, a minor wording disagreement, a request for additional sections, or a general expression of concern without a specific factual basis.

Teams vs GitHub PRs for review

Teams channel posts provide a less granular review surface than GitHub pull requests — you can't post an inline comment on a specific line of the ADR document. The tradeoff is accessibility: non-technical stakeholders (PMs, finance, legal) participate naturally in a Teams channel conversation; they are less likely to engage with a GitHub PR. For ADRs that require cross-functional review, Teams channels are the better announcement surface. For ADRs reviewed exclusively by engineers, GitHub PRs on committed Markdown files are strictly superior (inline comments, diff view, preserved review history in git).

Microsoft Planner as an ADR status board

Planner provides a Kanban-style view across all ADRs in a domain or team. Add a Planner tab to the relevant Teams channel:

1. In the Teams channel, click + → Planner (or "Tasks" in older Teams versions) → create a new plan.
2. Create buckets for ADR domains: Infrastructure, Security, Data, API contracts, or whatever domains match your architecture.
3. Create custom labels (up to 25 labels in Planner): set at least four for ADR status — Proposed (yellow), Active (green), Deprecated (gray), Superseded (blue).
4. For each ADR, create a Planner task: title = ADR number + decision title. In the task description, paste the link to the Loop page. Set the appropriate status label.
5. Update the label whenever the ADR status changes in the Loop page.

Limitations of Planner for ADR tracking

Planner does not enforce the ADR status lifecycle — it's a visualization tool, not a state machine. Common failure modes:

• An ADR marked Proposed never gets updated to Active after the review deadline passes (the author moves on without closing the loop)
• An ADR is marked Superseded without adding the Superseded-by reference in the Loop page document itself
• Labels fall out of sync with the actual document status as the Loop page is updated but Planner is not

The fix for all three is a brief governance norm: the author is responsible for keeping the Planner task label in sync with the Loop page status. A quarterly "ADR health review" (30 minutes) where the team scans the Planner board for stale Proposed tasks and loops that never closed is the practical remedy — this is the Teams equivalent of the ADR retirement review described in the lifecycle guide.

SharePoint Markdown as an ADR repository

Some Teams orgs store ADRs as Markdown files in a SharePoint document library connected as a Teams Files tab. This approach is closer to the git-based ADR model: each ADR is a .md file, SharePoint preserves a version history, and the files are accessible outside Teams via SharePoint Online.

When SharePoint Markdown makes sense

• Your organization uses Teams as the primary collaboration platform but also uses Azure DevOps or GitHub for code — and you want the ADR repository to feel similar to a code repository without requiring every reviewer to have git access
• Non-technical stakeholders need to read (but not necessarily edit) ADRs in a browser without learning GitHub or a git client
• Your ADR practice is in an early stage and you want a low-friction start without setting up a dedicated git repository for decisions

Limitations of SharePoint Markdown ADRs

• No syntax highlighting: SharePoint renders Markdown as plain text in the browser — no formatting, no code block highlighting
• No PR-based review: SharePoint has no branch or pull-request model; governance requires the Teams channel ceremony rather than a formal PR workflow
• No CI validation: automated format checks (required frontmatter fields, status vocabulary enforcement, superseded-by resolution) are not available without a pipeline that connects SharePoint to a CI system — a non-trivial integration
• Export gap: SharePoint Markdown files are not a structured export — migrating to a git repository requires copying files manually (or via Graph API), which loses the SharePoint version history

For most engineering organizations past the early ADR adoption phase, the SharePoint Markdown path is a stepping stone rather than a permanent solution. The graduation path: use SharePoint Markdown to lower the adoption barrier, then graduate to a committed Azure DevOps Repos or GitHub repository once the team's ADR practice is established and CI enforcement becomes desirable.

Teams vs git — when to choose each for ADR storage

The practical guidance: use Teams (Loop + Planner + channel governance) for organizations where ADRs span engineering and non-engineering stakeholders, or where ADR practice is in its first six months and adoption barriers need to be low. Use git for ADRs that document code-adjacent decisions reviewed exclusively by engineers, especially when CI validation or a formal PR review workflow adds value.

Integration with Azure DevOps

Teams and Azure DevOps are both Microsoft platforms and integrate natively. For Teams orgs that also use ADO:

• ADO Work Items in Teams: Pin the ADO Boards tab to a Teams channel to track ADR Work Items alongside engineering tasks. Each ADR can be a Work Item with custom fields for Status, Deciders, and a link to the Loop page or ADO Repos Markdown file.
• ADO Repos Markdown (the graduated target): When an ADR graduates from a Loop draft to a committed Markdown file, the target is the docs/decisions/ directory in the relevant ADO Repos repository. From there, the ADO Pipelines CI validation described in the Azure DevOps ADR template guide can enforce format and lifecycle rules.
• ADO Wiki vs Teams Loop: Azure DevOps has its own Wiki (a git-backed repository separate from the main code repo). For teams where engineers already use ADO Wiki for documentation, storing ADRs as ADO Wiki pages is a reasonable alternative to Loop — but ADO Wiki is less accessible to non-technical reviewers who aren't already ADO users.

WhyChose and Teams ADR practice

The most common source of missing content in Teams-native ADRs is the Alternatives Considered section. Engineers who used Microsoft Teams' own Copilot, or used ChatGPT and Claude in separate browser tabs while drafting architecture decisions in Teams channels, have the reasoning recorded in those AI sessions — but it's not accessible from the Teams context where the ADR lives.

The WhyChose extractor processes your ChatGPT or Claude conversations.json export and surfaces the sessions where architecture alternatives were deliberated. The output — structured decision records with Alternatives Considered and Context sections filled from the AI conversation — can be copied directly into a Loop page or a SharePoint Markdown file to complete the ADR sections that would otherwise be left thin.

The workflow that works well in Teams orgs: deliberate in Claude or ChatGPT (the tools with exportable conversation history), run the extractor to surface the decision sessions, create the Loop page with the extractor output as the raw material, announce in the Teams channel for review. The extractor fills the parts engineers find hardest to write from memory; Teams provides the collaborative surface for co-authoring and governance.