Topic: ADR tooling
GitHub Discussions as an RFC Surface — Proposal-to-ADR Workflow
GitHub Discussions is a pre-decision consultation layer that fits naturally in front of the ADR merge step. A Discussion thread stays open for questions and alternatives without implying a merge decision the way a pull request does. It supports long-running consultations, non-engineer participants, and a visible "answered" state that marks when a decision has been made. This page covers how to configure Discussions as an RFC surface, the proposal lifecycle from idea to closed Decision, and how the Discussion thread maps section-by-section to the ADR that closes it.
TL;DR
Create a Proposals Discussion category in your repository. Use a Discussion template with sections for Problem, Proposed Approach, and Alternatives. When the consultation closes, post a decision comment, mark it as the Answer, and open a PR that adds the ADR file to /decisions/. The Discussion body maps to the ADR Context section; the Discussion replies map to Alternatives Considered; the decision comment becomes the ADR Decision. Link the ADR back to the Discussion number so the two records are discoverable from either direction.
Why Discussions instead of a pull request for pre-decision consultation
The standard ADR workflow uses a pull request: an engineer writes the ADR, opens a PR, gets one or two approvals, and merges. This works well when the decision is already made and the PR is the review step for the written record. The problem arises when the decision is not yet made — when the engineer wants to consult stakeholders, surface alternatives, and gather objections before committing to a direction. A PR in that state carries the wrong semantic: it implies the author wants a merge decision, and reviewers naturally focus on whether to approve the implementation rather than whether the proposed direction is correct.
GitHub Discussions avoids that friction. A Discussion does not have an approved/rejected outcome at the code level — it has a conversation with an optional Answer marker. Stakeholders can reply without feeling they're either approving or blocking a merge. The thread stays open without implying stasis; it's explicitly a conversation, not a code review.
Three specific cases where Discussions is better than a PR for the RFC stage:
- Non-engineer stakeholders. Product managers, security engineers, and designers are comfortable with Discussions (which feel like comments on a doc) and uncomfortable with pull requests (which feel like code review). If the architecture decision requires non-engineer input — pricing model, data retention policy, external API design — a Discussion gets better participation from that audience.
- Long consultation windows. A PR open for three weeks with no activity looks stalled; reviewers don't revisit open PRs. A Discussion open for three weeks looks like an ongoing conversation. The social dynamic is different: Discussion participants subscribe to the thread and get notified when new comments arrive; PR reviewers are assigned once and often don't re-engage.
- Proposals that need to evolve. A Discussion body can be edited throughout the consultation without creating PR revision history noise. If new information changes the preferred approach halfway through the consultation period, you can update the Discussion body to reflect the current state of the proposal without a wall of commits.
Configuring a Proposals category in GitHub Discussions
GitHub Discussions supports custom categories. The default categories (Announcements, General, Ideas, Q&A, Show and tell) don't clearly signal "this is a formal architectural proposal with a decision pending." Create an explicit Proposals category:
- Go to Settings → Discussions → Categories → New category.
- Name: Proposals. Description: "Pre-decision architecture proposals. Each proposal closes with a Decision comment and produces an ADR."
- Format: Open-ended discussion (not Q&A). The Q&A format requires an accepted answer to close, which forces a binary close; the open-ended format gives you more control over the closing ceremony.
- Create a Discussion template for the Proposals category. GitHub Discussions templates (stored in
.github/DISCUSSION_TEMPLATE/proposals.yml) pre-fill the body with the sections every proposal must have.
Example .github/DISCUSSION_TEMPLATE/proposals.yml:
title: "[Proposal] "
labels: ["proposed"]
body:
- type: markdown
attributes:
value: "## Problem\n*What is the specific problem or constraint driving this proposal?*\n\n## Proposed Approach\n*One or two sentences: what we will do and why.*\n\n## Alternatives Considered\n*At minimum two alternatives with honest trade-offs for each.*\n\n## Drawbacks\n*What are the risks or downsides of the proposed approach?*\n\n## Decision target\n*When does this Discussion need to close? Who is the decision-maker?*\n\n---\n*When this Discussion closes, post a Decision comment, mark it as the answer, and open a PR adding the ADR to /decisions/.*"The template enforces the minimum RFC structure without a heavyweight document format. Engineers who would refuse to write a full Rust-style RFC will fill in a Discussion template in ten minutes.
Proposal lifecycle: from Discussion to closed ADR
Stage 1 — Open the Discussion
The proposer opens a Discussion in the Proposals category using the template. The Discussion title should follow the ADR title convention: a noun phrase that names the decision, not the problem. "Proposal: Use PostgreSQL instead of DynamoDB for the decision-records store" is better than "Should we use DynamoDB?". The noun-phrase title becomes the ADR title verbatim when the Decision is made.
Notify relevant stakeholders directly after opening — a Discussion notification is easy to miss. A Slack message to the affected team channels with the Discussion link is the minimum notification for a proposal that crosses team boundaries. Set the review-by date in the Discussion body: "Decision target: 2026-06-17 (EOD). Decision-maker: @principal-engineer." Without a named closer and a deadline, the Discussion will not close.
Stage 2 — Collect alternatives and concerns
During the open window, stakeholders comment with questions, alternative approaches, and concerns. The proposer should update the Discussion body — not just the comment thread — when new alternatives emerge from the comments. This keeps the Discussion body as the current state of the proposal; late readers can read the body to get the latest thinking rather than scrolling through the full thread.
Avoid resolving legitimate objections with "we'll address that in a follow-up." If a concern is serious enough to raise, it is serious enough to address before the decision. A decision made by tabling legitimate objections will produce an ADR with a thin Consequences section and a follow-up crisis in 6 months.
Stage 3 — Decision comment
When the decision-maker judges the consultation has run long enough, they post a closing comment in this exact structure:
**Decision: We will use PostgreSQL for the decision-records store.**
Decision-maker: @principal-engineer
Date: 2026-06-14
**Rationale:** DynamoDB's query model requires knowing access patterns at schema design time; our access patterns are exploratory and not yet stable. PostgreSQL's flexible indexing and full-text search support the query shapes we anticipate evolving into.
**Accepted trade-off:** PostgreSQL requires more operational knowledge than DynamoDB and introduces a relational paradigm in a codebase otherwise using key-value stores. This risk is accepted.
**Dissent on record:** @senior-engineer flagged that PostgreSQL's connection pooling overhead at high concurrency is a risk we're accepting without a load test. The team agrees to run a load test within 30 days of shipping the integration.
**Next step:** @author-name will open a PR adding ADR-0042 to /decisions/. Closes this Discussion.After posting the decision comment, mark it as the Discussion answer (if the category is configured as Q&A format) or pin it to the top of the thread. Change the Discussion label from proposed to decided and close the Discussion. Do not delete it.
Stage 4 — Write the ADR from the Discussion
Open a new PR that adds the ADR file to /decisions/. In the PR description, link the Discussion: "Closes #42 (architecture Discussion)." The ADR should be created with adr new "Use PostgreSQL for the decision-records store" if the team uses adr-tools; fill the body from the Discussion sections as described below. The PR should be reviewed and merged within 24 hours of the Discussion closing — delay beyond 48 hours means the context that was live in the room fades and the ADR prose starts reading as post-hoc rationalization.
Mapping Discussion sections to ADR sections
The Discussion template and the ADR format are deliberately aligned so that the transformation is a compression, not a rewrite.
| Discussion section | Maps to ADR section | Transformation note |
|---|---|---|
| Problem | Context | Condense to the specific forces that made the decision necessary. 2–4 sentences. Cut the narrative framing; keep the constraints and triggering conditions. |
| Proposed Approach | Decision | Reduce to one active-voice sentence: "We chose X because Y." The Discussion's full rationale belongs in the ADR Consequences section, not the Decision line. |
| Alternatives Considered (Discussion body + comment thread) | Alternatives Considered | Include alternatives raised in the comment thread, not just the ones the proposer pre-considered. These are the most valuable rows in the ADR for future readers who face the same decision. |
| Drawbacks | Consequences (negative) | Direct copy. These are the risks the proposer acknowledged before the decision was made — they're the honest negative consequences. Add any drawbacks raised in comments that the proposer accepted. |
| Decision comment: Rationale | Consequences (positive) | What the team expects to gain from this decision. Don't oversell — match the scope of the commitment to what was actually discussed. |
| Decision comment: Dissent on record | Consequences (negative) | The most commonly omitted ADR source. Voices that objected in the Discussion but didn't block the decision represent accepted risks. Record them in the Consequences section so the next engineer understands which risks were known at decision time. |
| Discussion metadata: decision-maker, date, closer | ADR frontmatter: decider, date | The ADR date is the Discussion close date, not the ADR commit date. The decider field records who posted the Decision comment. Reference the Discussion number in a see-also frontmatter field. |
GitHub Discussions vs pull request as RFC surface — comparison
| GitHub Discussion | Pull request (draft spec) | |
|---|---|---|
| Best for | Pre-code proposals, long consultations, non-engineer stakeholders | Proposals with a concrete implementation draft or spec document already written |
| Participant experience | Comment-thread style; familiar to non-engineers; no diff-view complexity | Code-review style; best for engineers; implies approval/rejection of specific text |
| Evolution during consultation | Discussion body editable without commit noise | New commits create diff history; edits look like implementation changes |
| Decision signal | Closing comment + Answer marker + label change + Discussion close | PR merge (Accepted) or PR close (Rejected) |
| Audit trail | Full comment thread preserved in closed Discussion; searchable by label | PR comment thread preserved; referenced in ADR PR description |
| ADR creation | Separate PR that adds ADR file, opened after Discussion closes | Can be the ADR PR itself if the PR adds the ADR file directly |
| GitHub notification model | Subscribers notified on new comments; re-engagement natural | Assigned reviewers notified once; re-engagement requires @mention |
The two approaches are not mutually exclusive. Some teams use a Discussion for the proposal stage and a PR for the ADR submission stage — the Discussion closes the consultation, the PR closes the documentation. This two-PR model gives the cleanest audit trail: the Discussion thread is the full consultation record; the ADR PR is the narrow, reviewable change that adds the decision to the repository.
Label system for Discussion lifecycle management
GitHub labels on Discussions let you query across all proposals in a repository. A minimal label set for the Proposals category:
- proposed — Discussion open, consultation underway. Default label applied by the Discussion template.
- decided — Decision comment posted, Discussion closed, ADR PR opened or merged. Applied by the decision-maker when closing.
- deferred — Consultation paused with no decision. Apply when the Discussion is tabled for a specific reason (blocked on external dependency, awaiting data). Include the reason and a reopen trigger in a pinned comment.
- withdrawn — Proposer withdrew the proposal before a decision. No ADR needed. Apply and close.
A GitHub Discussions search for is:closed label:decided in your repository produces a complete log of all decided proposals — a second, richer source alongside the /decisions/ ADR directory. The Discussion log captures proposals that were rejected or withdrawn, which the ADR directory does not (unless you write ADRs for rejected proposals, which is optional and recommended only when the team expects to revisit the same question).
The Discussion as AI-deliberation supplement
Many teams run an informal RFC-equivalent in Claude.ai or ChatGPT before opening the GitHub Discussion — an engineer thinks through the problem, stress-tests alternatives, and drafts the initial Alternatives Considered section using an AI conversation. The AI session serves as a pre-Discussion warm-up: it produces a richer initial proposal than an engineer writing from scratch, and it surfaces alternatives the proposer can include in the Discussion body rather than waiting for reviewers to raise them.
The problem is that the AI reasoning lives only in the chat history. If the engineer closes the tab without saving, the deliberation that produced the Discussion body is lost — and the Discussion body is already a compression of the full reasoning. When the Discussion closes with a decision and the ADR is written, the AI conversation is now two levels removed from the record.
The WhyChose extractor closes this loop. It reads your Claude.ai or ChatGPT conversations.json export and surfaces the architecture decisions inside — the alternatives that were raised and rejected in the AI session, the trade-offs identified, the constraints the conversation uncovered. Running the extractor before writing the Discussion gives you a richer Alternatives Considered section than most engineers produce from memory. The extraction also serves as an audit trail for the pre-Discussion deliberation that otherwise vanishes.
Related questions
Should I use a GitHub Discussion or a pull request for an RFC?
Use a Discussion when the proposal is pre-code and the consultation will benefit from a non-intimidating thread format. Use a PR when you have a concrete spec document or draft implementation and want reviewers to comment on specific text. The Discussion is a better surface for early-stage proposals that need to evolve; the PR is better once the direction is clear and the work is to refine the written record. Many teams use both in sequence: Discussion for the consultation, PR for the ADR commit.
How do I close a GitHub Discussion with a formal decision?
Post a decision comment with the decision (one active-voice sentence), the decision-maker's name, the date, the rationale, and any dissents that were heard but didn't change the outcome. Mark that comment as the Answer or pin it. Change the label to 'decided' and close the Discussion. Open a PR adding the ADR file. Link the ADR PR back to the Discussion number in the PR description. Don't delete the Discussion — it's the long-form audit trail for the ADR.
Can GitHub Discussions replace adr-tools?
No — they serve different functions. GitHub Discussions is a consultation surface for the pre-decision stage. adr-tools is a file-creation tool for the post-decision stage. The correct workflow is: Discussion (consultation) → adr new <title> (file creation) → PR with the ADR file (record). The Discussion helps produce richer ADR content; adr-tools handles the file management. They're complementary, not competing.
What happens to the Discussion after the ADR is merged?
Keep it closed and labeled 'decided'. Link it from the ADR's see-also section. The Discussion thread preserves the back-and-forth, the alternatives that were proposed and rejected, and the concerns that were heard but not decisive — information the ADR intentionally omits to stay concise. Future engineers who want to understand why the rejected alternatives were rejected will find the Discussion thread invaluable. GitHub's search indexes closed Discussions, so they remain discoverable via label or keyword search.
Further reading
- ADR template for GitHub repos — folder layout, PR workflow, and filename conventions — the canonical guide for storing ADR Markdown files in a GitHub repository. This covers the
/decisions/directory structure, the PR-based review workflow, and filename conventions. The Discussion RFC workflow described on this page feeds into the ADR PR workflow described there — use both in sequence. - ADR vs RFC — what's the difference and when should you use each? — the conceptual distinction between RFC (pre-decision, open, seeking input) and ADR (post-decision, closed, preserving rationale). The GitHub Discussions workflow described on this page is one implementation of the RFC stage; this page covers why the two formats are sequential rather than competing.
- The RFC-to-ADR process — lifecycle stages, review ceremony, and section mapping — the full RFC ceremony: five lifecycle stages (Draft → Under Review → FCP → Decision → ADR Written), review norms by decision scope, and the section-by-section mapping from RFC to ADR. The Discussion workflow on this page is a lighter-weight implementation of the same process using GitHub's native tooling rather than a separate RFC document.
- The ADR review checklist — 12-item PR quality gate — once the Discussion closes and the ADR PR is opened, use this checklist before merging. It verifies that the Decision section is a single active-voice sentence, that the Consequences section names at least one negative, and that the ADR references the Discussion thread (via see-also or PR description link).
- The ADR GitHub Action — CI pipeline for architecture decision records — the CI validation layer that runs on every PR touching
/decisions/. It verifies that new ADRs are well-formed, that Superseded-by pointers resolve to existing files, and that the Status field uses a recognized value. Pair this with the Discussion RFC workflow: the Discussion produces richer ADRs; the GitHub Action verifies they're structurally sound before merge. - The open-source extractor — reads your Claude.ai or ChatGPT conversations.json export and surfaces architecture decisions as structured ADR records. For teams that use AI chat sessions as the pre-Discussion deliberation layer, the extractor turns those sessions into the Alternatives Considered and Context material for the Discussion body — and, after the Discussion closes, for the ADR itself.