Skip to main content

ADR-003: Design docs stay in-repo markdown; the PR is the conversation surface

Accepted2026-06-08

Context​

A reviewer's feedback ("I wasn't part of the planning") raised a question about where a design conversation should live. The design doc as it stands is a plain markdown file at docs/designs/<slug>-<cu-id>.md, with no threaded discussion mechanism β€” comments happen ad hoc on whatever PR or chat is nearby. The question: should design docs move to GitHub Discussions, which are markdown-bodied but add threading, replies, reactions, and mark-as-answer β€” the conversation affordances a static file lacks?

Forces at play:

  • A design doc is not just prose β€” it is a pipeline node. gatekeeper reads its status: frontmatter; /breakdown reads its task section; /plan-feature writes its skeleton; the draft β†’ approved lifecycle is frontmatter-driven; cross-refs use relative .md paths.
  • The Docusaurus site renders and navigates design docs β€” verified: autogenerated sidebars, the "Plan" navbar dropdown, local full-text search, and the DocExplorer index. GitHub Discussions live on a separate github.com surface, not in the site's sidebar or search.
  • The platform's stated bias (deterministic-ai principle 1) is version-controlled, agent-consumable artifacts over thread-based state.
  • The design-doc corpus is empty today (one PRD, zero design docs), so the decision is cheap to make now and carries no migration cost.
  • The genuine win Discussions offer β€” a threaded conversation β€” is already available on the PR that introduces or edits the doc: line-level comments on the doc itself, request-changes/approve, references, notifications, git-native.

Decision​

We will keep design docs as in-repo markdown (the source of truth), make the PR that introduces or edits a design doc the default conversation surface, and reserve GitHub Discussions for RFC-shaped, cross-team, or durable debates that link back to the markdown doc.

We will not migrate design-doc storage to GitHub Discussions.

Rationale​

OptionProsCons
βœ… Markdown SoT + PR-as-conversationKeeps Docusaurus site nav/search, git history/blame, the frontmatter-driven gatekeeper/breakdown pipeline, and deterministic AI file-reads. Threaded discussion comes free from the PR (line-level, referenceable, git-native). No migration.The PR thread dies on merge β€” a durable cross-feature debate needs somewhere else to live (handled by the Discussions escalation below).
❌ Migrate design docs to GitHub DiscussionsNative threading, replies, reactions, mark-as-answer; markdown body can hold the same sections.Loses site navigation (Discussions are not in the Docusaurus sidebar/search); loses git history/blame and PR-review-on-the-doc; the frontmatter-driven pipeline must be re-plumbed against the GraphQL API + labels; AI access becomes a non-deterministic API call instead of a file read. Runs against the platform's version-controlled-over-thread-based bias.
❌ Status quo (markdown, no defined conversation surface)Simplest.The "I wasn't part of the planning" gap persists β€” no defined place for the approach debate before code.

GitHub Discussions add value over "markdown + PR" only when the conversation should outlive the PR, spans more than one feature/team, or has no natural PR to attach to. For a feature-scoped design doc, the PR is the better fit.

Consequences​

Positive:

  • Design docs keep first-class site navigation, search, and version history.
  • The approach debate has a defined home (the PR on the doc) that the feature-needs-design policy can point a reviewer to before code exists.
  • No new infrastructure; the conversation surface already exists.

Negative / trade-offs:

  • A durable, cross-feature design debate must be deliberately escalated to a GitHub Discussion (which links back to the markdown doc); this convention has to be remembered, not enforced by tooling.
  • PR threads are not a long-term knowledge base β€” once merged, the rationale must be captured in the doc itself or an ADR, not left only in the thread.

Neutral:

  • GitHub Discussions remain unused for now; the door is left open for RFC-shaped debates without committing to them as the design-doc store.

Revisit trigger​

Revisit if (a) the design-doc corpus grows large enough that cross-feature debates routinely need a durable home the PR cannot provide, or (b) GitHub ships Discussions↔repo-file sync that would let a Discussion render in the Docusaurus site nav without bespoke tooling.

Decided by @relbns on 2026-06-08, from the human-review-in-AI-workflows initiative.