Skip to content

Phase B (fleet-wide): decompose the three product architecture.md artifacts into per-repo ADRs #1637

Open

Description

@don-petry

Follow-up carved from Discussion #1360 Phase B (fleet-wide half), raised by a source-material audit run on 2026-09-01 while planning epic #1627. Recorded now so the finding is not lost; not ready to plan until #1628 lands (see Dependency).

The finding

Three product repos already carry substantial Winston (BMAD Solution Architect) architecture output. It is real, detailed, and currently unreachable by any agent — because it is not in a form anything can cite.

Repo Artifact Size Last touched Age
TalkTerm _bmad-output/planning-artifacts/architecture.md 48 KB 2026-03-24 160d
markets _bmad-output/planning-artifacts/architecture.md 54 KB 2026-03-28 156d
broodly _bmad-output/planning-artifacts/architecture.md 38 KB 2026-03-21 163d

Plus a fourth, in better shape and not BMAD-generated — see "Correction to #1360" below.

Why these are not ADRs today

Each is a single monolithic "Architecture Decision Document". Against the #1360 decision model (ADRs are normative, append-only, immutable once accepted), they fail three of four properties:

Why it is worth doing anyway — the material is good

broodly §"Architectural Boundaries" is already in the checkable-invariant form the ADR convention wants:

  • apps/api is the only client-facing GraphQL API surface.
  • Mobile and web clients never access DB directly.
  • Domain modules communicate via explicit interfaces/events only.

markets goes further — its boundaries are tables with an Enforced By column (Client → API / GraphQL over HTTPS / Cloud Run ingress, TLS). That column is precisely what a later Phase D/F check would assert against. This is ADR-ready content trapped in a non-ADR container.

Sizing — and the reason it is not mechanical

All three share the same BMAD skeleton (## Core Architectural Decisions → ### Decision Priority Analysis + ### Decision Impact Analysis; ## Project Structure & Boundaries → ### Architectural Boundaries). That invites the assumption that extraction is a deterministic parse. It is not, and this is the main sizing risk to flag:

Repo Decisions Encoded as Boundaries Encoded as
TalkTerm 13 numbered lists 13 bullets
markets 14 bullets 7+ tables
broodly 18 bullets 4 bullets

~45 candidate decisions total, in three different markup shapes under identical headings. A single regex/parser will be brittle; this needs a structure-aware pass per repo. Deterministic-first is still right for locating candidates (#1360's Phase B correction), but the split-and-rewrite is editorial and needs review per ADR.

Correction to #1360

The body of #1360 §3 states "google-app-scripts has a PRD and no architecture." That is wrong. petry-projects/google-app-scripts/docs/architecture.md exists (14 KB, 2026-03-28) — and it is the best-shaped architecture doc in the org:

  • It is already at docs/architecture.md, i.e. already on the Q0-decided path prefix.
  • Its §"Key Architecture Decisions" entries already use Decision / Rationale / Trade-off — Nygard's Decision / Context / Consequences under different names.
  • Each entry names a real trade-off, not only an upside (e.g. the dual-file pattern's "logic must be kept in sync between code.gs and src/index.js").

It is the closest to passable in the org and should be the first repo converted, not the last — it is the cheapest proof that the convention works, and it doubles as the in-org style exemplar. (It was also not generated by Winston, which is itself worth noting: the hand-written doc is in better ADR shape than the agent-generated ones.)

Proposed scope (when planned)

  1. Convert google-app-scripts first — smallest, best-shaped, proves the convention end to end.
  2. Then broodly, markets, TalkTerm — one repo per story; each emits docs/architecture/adr/NNNN-*.md using the convention established by [Phase 1] Seed the architecture-of-record (ADR convention + 4–6 lifted ADRs) for .github-private #1628, with status: accepted and a provenance line citing the source section of the original architecture.md.
  3. Leave the original architecture.md in place, marked as superseded-by-the-ADR-tree rather than deleted — it holds narrative context (cost analysis, starter-template evaluation) that is not decision-shaped and does not belong in ADRs.
  4. Do not attempt to make the ADRs current. They record what was decided in March 2026. If a decision has since drifted, that is a finding for the solution-architect persona to surface — not something to silently rewrite. Backfilling an ADR to match today's code is the exact ratchet Architectural integrity in the agentic delivery model — what enforces our standards, and where does the Solution Architect fit? #1360 §2 describes.

Dependency

Blocked by #1628 (the repo-local ADR convention, docs/architecture/adr/0000-adr-process.md). This work must reuse that convention rather than invent a second one — otherwise the fleet ends up with two ADR dialects, which is the drift the persona manifest pattern exists to prevent.

Explicitly not in scope

docs/architecture/views/ and deterministic view generation (the other half of Phase B), the org-level architecture standard (Phase A), and anything in Phases C/F/G. Those stay in #1360.


Parent: Discussion #1360 (Phase B, fleet-wide half) · Sibling cut: epic #1627 (Phase E, repo-local) · Source audit: 2026-09-01

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions