What is the difference between a stream-aligned team and a feature team?

The terms are often used interchangeably in practice, but the distinction matters for understanding why team topology decisions age poorly. A feature team is defined by what it builds: a team that builds features. The definition is output-oriented. A stream-aligned team, as defined in the Team Topologies framework, is defined by what it is aligned to: a continuous flow of work from a segment of the business domain, with the goal of being able to deliver end-to-end value to the user or customer with minimal coordination with other teams. The definition is responsibility-oriented. The practical difference is what happens at the edges. A feature team is defined by its current backlog; when the backlog crosses team boundaries, coordination is required and is treated as a normal cost of delivery. A stream-aligned team is designed to own a domain boundary so cleanly that cross-team coordination for routine delivery is unnecessary — when coordination is required, it is a signal that the domain boundary is wrong, not that the coordination is normal. The failure mode that produces the eleven-week onboarding change described in the first story is a feature team model that was never redesigned as a stream-aligned team model. The teams were defined by problem surfaces at a time when the codebase was small and team boundaries were nearly irrelevant; as the codebase grew, each team accumulated dependencies on code owned by other teams, and the coordination cost for any change that crossed multiple problem surfaces grew without a mechanism to notice or contain it. A stream-aligned team model makes the domain boundary explicit and uses that boundary as the primary signal for organizational health: when a team cannot deliver value end-to-end without extensive coordination, the team boundary is misaligned with the domain, and the misalignment is the problem to solve — not the coordination process to improve. The distinction is not merely semantic. The design of the coordination process is qualitatively different. Feature teams invest in coordination mechanisms (joint planning, shared sprint cadences, dependency tracking tools) that help them ship across team boundaries more efficiently. Stream-aligned teams invest in domain boundary redefinition and internal platform capability to eliminate the need for that coordination. The team topology decision record must specify which model the organization is using and why, because the organizational behaviors that flow from each model are fundamentally incompatible — a feature team that tries to eliminate coordination overhead will eliminate the signal that its domain boundaries are wrong.

When should an engineering organization form a platform team?

A platform team is warranted when stream-aligned teams are repeatedly solving the same infrastructure or tooling problem independently, and the cost of each team solving it independently exceeds the cost of a dedicated team providing it as a self-service capability. The key phrase is 'self-service capability' — a platform team that provides capabilities but requires other teams to submit requests and wait for delivery is not a platform team; it is a shared services team, and shared services teams create bottlenecks rather than reducing them. The formation criterion has two parts that must both be satisfied. First, the problem must be genuinely shared: three or more stream-aligned teams are spending meaningful engineering time on the same infrastructure or tooling concern, the solutions they build are functionally similar but not interoperable, and there is a credible unified abstraction that would reduce the total engineering investment while improving the outcome for each team. Second, the platform can actually be self-service: the unified abstraction can be built in a form that lets stream-aligned teams consume it without opening a ticket, waiting in a queue, or requiring platform team involvement to configure and deploy. If the second condition cannot be met — if the capability is inherently bespoke, requires expert involvement per instance, or has requirements that vary enough between teams that a unified abstraction cannot serve them — then a platform team is not the correct organizational response. The correct response may be an enabling team (a team that helps other teams build the capability themselves, then moves on) or a documented shared approach that each team implements independently. The timing is also important. A platform team formed before stream-aligned teams have accumulated enough experience building the capability independently will make assumptions about what 'self-service' means that are incorrect — the platform team's abstraction will be shaped by the founders' preferences rather than the actual patterns across teams. A platform team formed too late will find that each team has deeply embedded its own implementation and the migration cost is high. The right timing is when the repeated pattern is visible but the independent implementations are still recent enough that migration to a shared abstraction is feasible. In practice, this is usually between the team's third and fifth independent implementation of the same capability.

How do you measure cognitive load in a software team?

Cognitive load in the context of team topology refers to the total quantity of domain knowledge a team must hold in working memory to successfully deliver changes to their area of responsibility end-to-end. It is not a subjective measure of how stressed engineers feel; it is an objective property of the team's domain boundary relative to the team's capacity. The most reliable proxy measurement is the onboarding time to productive contribution: how long does it take a new engineer joining the team to independently ship a change through to production? A team where new engineers are productive within two weeks has a manageable cognitive load. A team where new engineers take four months to be independently productive has a cognitive load problem — the domain is too large, the service boundary encompasses too many interacting systems, or the knowledge required to make safe changes is too distributed across undocumented history and tribal knowledge. The second measurement is the fraction of changes that require coordination with other teams. A stream-aligned team with a well-calibrated domain boundary should be able to ship more than 80% of its backlog end-to-end without coordinating with other teams. When the fraction falls below 60%, the domain boundary is likely misaligned. A useful heuristic from the Team Topologies framework is the Dunbar-inspired cognitive load limit: a team can realistically hold approximately five to eight independent services in active working memory — the size of a family plus one or two outside relationships, roughly the size of the group where everyone knows everyone else's work. Services beyond that limit are known to exist but not understood well enough to modify safely without significant ramp-up. The limit is not a precise number because team composition matters (specialists reduce the breadth but increase depth in their domain), codebase familiarity matters (a stable, well-documented service costs less cognitive load than a rapidly changing one with poor tests), and the type of change matters (a configuration change costs less cognitive load than a schema change with migration). The three-signal diagnostic — onboarding time, cross-team coordination fraction, and engineer-reported confidence in making changes across the team's full service surface — provides a practical estimate of whether a team's current cognitive load is within its ceiling.

What is the difference between a platform team and an enabling team?

A platform team and an enabling team are both support team types in the Team Topologies model, but they serve fundamentally different purposes and have fundamentally different interaction models with stream-aligned teams. A platform team builds and operates internal products — tools, services, and capabilities that stream-aligned teams consume as a service. The interaction model is X-as-a-service: the platform team defines an API, writes documentation, maintains the service, and stream-aligned teams consume it without needing to understand its implementation. The platform team's goal is to reduce cognitive load for stream-aligned teams by providing capabilities they would otherwise need to build and maintain themselves. The platform team is permanent: the capability it provides is genuinely ongoing, not something stream-aligned teams will eventually internalize. An enabling team is a temporary team of specialists whose goal is to help stream-aligned teams build a capability they do not currently have, and then step back once the capability is established. The interaction model is facilitating: the enabling team works alongside the stream-aligned team for a limited engagement, teaching the practice and leaving the ownership with the stream-aligned team. The enabling team's goal is not to own the capability on behalf of other teams but to raise the capability level of the stream-aligned teams so they can own it themselves. The enabling team is temporary: a successful enabling team engagement ends with the stream-aligned team no longer needing facilitation. The confusion between the two is one of the most common organizational errors in technical organizations. A team formed to help other teams adopt observability practices might be an enabling team (if the goal is for stream-aligned teams to internalize observability practices and run their own observability stacks) or a platform team (if the goal is for the observability team to operate a shared observability platform that stream-aligned teams instrument against but do not operate). The correct choice depends on whether the capability is genuinely more effective when centralized and operated as a shared service, or whether it should be distributed across stream-aligned teams with specialized expertise at each. Getting this wrong in either direction is expensive: an enabling team that permanently facilitates produces dependency; a platform team that tries to teach rather than provide produces neither internalization nor a reliable self-service capability.

The team topology decision record: why the organizational structure you chose determines your cognitive load ceiling and your autonomous delivery surface

Published 2026-07-12 · WhyChose

Team topology decisions are made in the founding sprint when the answer is obvious: there are eight engineers, they work on everything, and the notion of "team structure" is an abstraction that does not yet apply. The structure that emerges is not a design — it is a description of who worked on what last week. As the organization grows to twenty engineers, then forty, then sixty, the topology that made sense at eight people persists not because it is still optimal but because nobody has held the meeting to change it. The AI sessions from the founding sprint contain the reasoning behind every domain boundary, every ownership assignment, every decision about who would own infrastructure versus product. That reasoning was correct in context — the context of eight engineers building the first version of the product. It becomes incorrect in a different context, silently, without a triggering event that makes the incorrectness visible until a delivery failure traces back to a structural cause.

The team topology decision is not a single org chart choice. It is a set of structural decisions that determine how cognitive load is distributed across the organization, how teams interact when their work overlaps, how ownership gaps are identified and assigned, and what triggers a topology revision as the organization scales. A team that does not document these decisions does not avoid making them — it makes them by default, in hiring discussions where "we need another engineer on the payments team" is answered without asking whether the payments team's domain boundary is still the right one, in sprint planning sessions where cross-team dependencies are tracked and managed as an accepted friction rather than examined as a signal that the domain boundaries are misaligned, in retrospectives where "we had to wait for the platform team" appears as a recurring item and is addressed by improving the request process rather than asking whether the platform team's scope has outgrown its capacity to provide a self-service product. The decisions are made implicitly. The absence of documentation means they cannot be evaluated against current organizational scale, revised as the organization evolves, or surfaced to a new engineering leader who needs to understand why the team operates the way it does.

Two ways team topology decisions produce the wrong outcome

The onboarding flow coordination story

A B2B project management SaaS company starts with twelve engineers organized into three squads by problem surface: acquisition (landing page, trial signup, marketing integrations), activation (onboarding, first-project creation, initial team invites), and retention (email digests, in-app notifications, usage analytics). At twelve engineers, this structure is correct. Each squad has four people, owns a surface area small enough that any engineer can hold it entirely in working memory, and delivers value end-to-end without meaningful coordination with the other squads. The organizational structure is not documented anywhere. There is no team topology ADR that says "three stream-aligned squads aligned to the acquisition/activation/retention funnel stages; domain boundaries defined by the customer journey phase; interaction model is collaboration for shared concerns (auth, user profile) with a plan to move to x-as-a-service once those concerns stabilize." The structure exists as institutional knowledge in the CTO's head and in the informal norms of the founding team.

Twenty-six months later, the organization has grown to sixty-five engineers. The three founding squads have each grown to fifteen to twenty engineers through hiring, without any restructuring of the domain boundaries. The activation squad still owns the onboarding flow — but the onboarding flow now depends on the user profile service (owned by the acquisition squad), the billing initialization service that provisions the trial tier (owned by a monetization squad that was split off from retention fourteen months ago, but which inherited no formal documentation of its domain boundary), the notification service that sends the welcome email and the day-3 activation nudge (owned by the retention squad), and a feature flag service (owned by a fifth team, the platform squad, that formed informally nine months ago when two infrastructure engineers started building shared tooling). An enterprise prospect asks for a custom onboarding flow — a whitelabeled welcome email, a custom first-project template, and a suppressed trial-expiry countdown for the first sixty days. The activation squad scopes the work at two weeks. The final delivery takes eleven weeks.

The eleven-week duration is not explained by the complexity of the feature. The whitelabeling requires three configuration fields in the notification service, one template variable in the welcome email, one condition flag in the billing initialization service, and two front-end components in the first-project creation flow. None of the individual pieces are technically complex. The eleven weeks decompose as follows: three weeks of alignment time across four squads with misaligned sprint cadences — the acquisition squad's sprint starts Monday, the activation squad's starts Wednesday, the monetization squad's starts Monday but they are in a planning quarter freeze, and the retention squad uses two-week sprints while the others use one-week sprints, so there is no single sync point where all four squads have work in the same sprint. Two weeks of API negotiation: the notification service's template API does not expose a per-customer template override — it was designed for a single template across all customers — and the retention squad needs time to design and ship the override capability before the activation squad can integrate against it. The design discussion involves the CTO and takes one of those two weeks because the template API's current design reflects an architectural choice ("notifications are a platform concern; individual squads should not customize notification content") that nobody documented and that the retention squad engineers who designed the API have since left the company. Three weeks of integration work that was scoped at one week because the feature flag service's SDK does not support the entitlement-based flag model the activation squad needs for enterprise customers, and the platform squad is three sprints backlogged. One week of QA across four squad environments that do not share a staging configuration. Two weeks of waiting for a monthly release window that the monetization squad requires for billing-adjacent changes due to an undocumented risk policy introduced after a billing incident six months earlier.

The original team structure decision — three squads aligned to acquisition, activation, and retention — was correct at twelve engineers. The original domain boundaries were reasonable. What was not documented was the condition under which those boundaries should be revisited: the expected organizational scale at which a stream-aligned squad would no longer be able to deliver end-to-end value without sustained cross-squad coordination. There is no document that says "the activation squad's domain boundary should be evaluated when the team needs more than two weeks of cross-squad coordination per quarter; at that point, either the boundary should be redrawn or the services that create cross-squad dependencies should be moved into a shared platform capability." That statement, or something equivalent, would have triggered a domain boundary review at around the time the organization passed thirty engineers. Instead, the boundary persisted, the coordination cost accumulated, and the first visible signal was an eleven-week delivery for a two-week feature — by which time the domain boundaries were embedded in the team identities, the squad-specific tooling, the sprint ceremonies, and the on-call rotations of sixty-five engineers.

The platform team bottleneck story

A thirty-person developer tools startup forms a platform team at twenty-two engineers. The motivation is clear and correct: three of the four product squads have independently built CI pipeline wrappers, and the three implementations have diverged to the point of incompatibility; the infrastructure squad is spending forty percent of its time answering questions from product squads about deployment configuration; and the fourth product squad has given up on standardizing its local development environment and is spending three hours per new-engineer-onboarding on ad-hoc setup support. The CTO forms a four-engineer platform team from the two most senior infrastructure engineers and two engineers from product squads who had been doing the most cross-squad infrastructure work. The team's mandate is to build a unified CI pipeline, a standardized deployment configuration system, and a shared local development environment. All four product squads will migrate to the platform's abstractions.

Eighteen months later, the platform team has grown from four to six engineers. The organization has grown from thirty to fifty-eight engineers, with eight product squads. The platform team has shipped a highly-regarded internal developer platform: a declarative service manifest format, a CI pipeline that runs in thirty percent less time than the independent implementations it replaced, and a local development environment that reduces new-engineer setup from three hours to twenty minutes. Ninety-four tickets are open in the platform team's backlog. Engineers from the product squads describe the platform team in retrospectives using the same phrase across teams: "we're waiting on platform." The platform team lead reports that the team is spending sixty percent of its capacity on requests from product squads and forty percent on platform roadmap work. The platform team discusses adding a fifth engineer and is told there is no headcount.

The platform team has become the primary bottleneck in the organization's delivery system. Product squads cannot deploy a new service without the platform team creating a service manifest template. Product squads cannot modify their CI pipeline behavior without the platform team reviewing and approving the change — an approval gate introduced after a product squad's CI modification caused a cross-service dependency resolution failure in a shared artifact cache. Product squads cannot add a new infrastructure dependency without the platform team evaluating the dependency against the platform's standard dependency catalog. None of these gates were in the original platform team mandate. Each was added incrementally in response to a specific failure, with a reasonable rationale at the time of addition. The aggregate of seven incrementally-added gates has produced a governance model where the platform team is a required participant in a substantial fraction of every product squad's delivery decisions — exactly the opposite of the X-as-a-service interaction model that justifies a platform team's existence.

The founding decision — to form a platform team at twenty-two engineers — was correct. The problem is not the team's existence but its evolution. What was not documented was the self-service threshold: the specific definition of "self-service" that the platform team's capabilities were required to meet, the measure by which self-service success would be evaluated, and the governance model for capability additions that would prevent the gradual accumulation of approval gates. There is no document that says "the platform team's capabilities are self-service when product squads can use them without opening a ticket; any new capability that requires a ticket or review workflow is not yet self-service and must be kept out of the platform's mandatory adoption scope until it is; governance gates added to platform capabilities must be reviewed quarterly against the criterion that the gate is necessary to protect a shared resource that cannot otherwise be protected, and removed if that criterion is not met." That statement, or something equivalent, would have blocked several of the approval gates before they were added, and triggered a quarterly review that removed others after their protective value had been superseded by improved tooling. Instead, the platform team drifted from an X-as-a-service model toward a shared services model — a model that concentrates coordination cost in a central team, reduces autonomous delivery for all teams that depend on the central team, and scales linearly with the number of requests rather than quadratically with the quality of the self-service product.

Three structural properties that team topology decisions determine

The cognitive load ceiling and the service ownership surface

Every team has a cognitive load ceiling — the total quantity of domain knowledge, service context, and organizational process that the team can hold in working memory and apply effectively to its delivery work. The ceiling is not a fixed number; it is a function of the team's size, the experience distribution of its engineers, the quality of the codebase documentation, and the volatility of the domain. But the ceiling is real, and when the domain a team is asked to own exceeds the ceiling, the team's delivery output changes in predictable ways: onboarding time to productive contribution increases, the fraction of changes that require careful coordination within the team (not just with other teams) increases, the error rate on changes in areas of the codebase that are less frequently touched increases, and engineers report low confidence in making changes to parts of the team's domain that they do not personally own. The cognitive load ceiling is the most direct mechanism through which team topology decisions determine delivery performance — a team with a domain that fits inside its cognitive load ceiling can operate with minimal coordination overhead and high confidence; a team with a domain that exceeds its cognitive load ceiling is perpetually catching up, always slightly uncertain about the implications of any given change, and dependent on the two or three engineers who carry the most institutional knowledge about the domain's most complex areas.

The service ownership surface — the set of services, libraries, databases, and external integrations that the team is responsible for — is the primary driver of cognitive load. A team that owns twelve services with a combined forty thousand lines of code in three languages, each with its own deployment pipeline, database schema, and external dependency set, is carrying more cognitive load than can be effectively distributed across a six-engineer team. The warning signs are not necessarily in the team's velocity metrics, which measure output rather than cognitive strain; they appear in the onboarding time, the error rate on infrequently-touched services, and the team's reliance on one or two engineers who serve as the human indexes for areas of the codebase that nobody else feels confident modifying. The team topology decision record must specify the cognitive load ceiling for each stream-aligned team explicitly — not as a subjective estimate but as a measurable proxy: the maximum time-to-productive-contribution for a new engineer (typically two to four weeks for a well-bounded domain), the maximum fraction of changes requiring cross-service coordination within the team (typically less than thirty percent), and the maximum number of services with active development work in any single sprint (typically four to six, depending on team size). When any of these thresholds is exceeded, the domain boundary should be examined before additional services are added to the team's ownership surface.

The on-call rotation decision record is directly downstream of the cognitive load assessment. A team's on-call engineers must be capable of triaging and resolving incidents across the team's full ownership surface; when the ownership surface exceeds the cognitive load ceiling, on-call engineers face incidents in services they do not know well enough to resolve confidently, which increases mean time to resolution and increases on-call toil. The team topology decision record must specify how the on-call rotation scope is derived from the team's ownership surface — the scope cannot be larger than the cognitive load ceiling, which means that ownership surface decisions and on-call scope decisions must be made together, not independently.

The team interaction mode and the collaboration overhead accumulation rate

Teams interact with each other in one of three modes: collaboration (working closely together on shared problems, with high communication bandwidth and shared decision-making), X-as-a-service (one team provides a capability that another team consumes; communication is minimal and mediated through the service API and documentation), and facilitating (one team helps another team develop a capability it does not yet have, with the intent of stepping back once the capability is established). Each mode has a different overhead profile. Collaboration is high-bandwidth: it requires frequent synchronization, shared context, and coordinated decision-making. It is the correct mode for solving genuinely shared problems that neither team can solve independently, or for exploratory work where the right approach is not yet known. It is the wrong mode for routine delivery: a team in permanent collaboration mode with another team is accumulating coordination overhead at every sprint, every planning session, and every architectural decision that touches the shared domain. X-as-a-service is low-bandwidth: it requires only that the service exists, is documented, and is reliable. It is the correct mode for capabilities that one team needs from another team but that are sufficiently stable and well-understood to be encapsulated in an API. It is the wrong mode for capabilities that are not yet stable, not yet self-service, or that require bespoke configuration that the consuming team cannot perform independently. Facilitating is temporary by design: it is the correct mode when one team needs to develop a capability but lacks the expertise to do so safely without guidance, and it is explicitly wrong when used as a permanent mode, because permanent facilitation produces dependency rather than capability development.

The interaction mode accumulation problem is one of the least visible organizational failure modes. Teams that begin in collaboration mode for a good reason — a critical cross-team project, an architectural migration, a shared dependency with complex implications — often remain in collaboration mode after the original justification has passed, because collaboration has produced working relationships, shared Slack channels, joint sprint ceremonies, and informal norms that are valuable and that nobody wants to discard. The collaboration overhead persists. Over time, multiple pairs of teams accumulate persistent collaboration relationships, each individually justified by history but collectively consuming a significant fraction of each team's attention on coordination rather than delivery. The total coordination overhead across the organization grows with the square of the number of persistent collaboration relationships, not linearly with team count — which is why organizations often feel a sudden delivery slowdown at a particular scale, even though the slowdown has been accumulating gradually from the moment the first unnecessary collaboration relationship persisted beyond its useful life. The team topology decision record must specify the interaction mode for each team pair explicitly — not just "these teams collaborate" but "these teams are in collaboration mode for this purpose, with a planned transition to X-as-a-service by this date, or a reassessment if the transition conditions are not met by then." Interaction modes that are not explicitly assigned are assigned by default to whatever emerges from the teams' communication patterns, which is typically collaboration — the highest-overhead mode — because collaboration is the natural default when the right boundary is not defined.

The technical debt decision record's ownership model is the complement to the interaction mode decision. When a team's ownership boundary is unclear — when a service or library is nominally owned by one team but frequently modified by engineers from other teams without a defined interaction protocol — the result is either informal collaboration (high overhead, unacknowledged) or ownership debt (a service with no team capable of triaging an incident because the nominal owner has lost context and the actual contributors have no on-call responsibility). Both outcomes are determined by the combination of the ownership boundary and the interaction mode; when neither is documented, both accumulate by default.

The organizational boundary and the ownership gap rate

Every software system has more components than its team structure was designed to accommodate. Services are created during incidents to isolate a misbehaving subsystem. Libraries are extracted to share logic between two services and then forgotten when both services are migrated. Infrastructure components are provisioned for a project and inherited by whichever team is most closely adjacent when the project ends. The ownership gap rate — the rate at which components enter the system without a documented owner — is a function of the team structure's ability to assign ownership proactively. An organization with an explicit ownership assignment process for every new component creation has a low ownership gap rate. An organization where components are created by whoever needs them and ownership is informally understood has an ownership gap rate that grows with organizational complexity.

Ownership gaps are the most reliable leading indicator of future incident response failures. A service with an unclear owner is a service where the on-call escalation path is ambiguous, where maintenance (dependency updates, configuration reviews, access audits) is performed late or not at all, where technical debt accumulates without a registry entry because there is no team responsible for logging it, and where the architectural constraints the service relies on are undocumented because there is no team with enough incentive to document them. The service exists in the system's dependency graph and produces failures that trace to it — but the failures are initially attributed to the teams that depend on the service rather than to the ownerless service itself, which delays both the identification of the root cause and the assignment of responsibility for the fix. The ownership gap is discovered during an incident, when the incident commander asks "who owns this service?" and the answer is silence followed by "I think it was the team that built it, but that team was restructured." The new CTO onboarding problem is partially a team topology problem: an incoming engineering leader who needs to understand the delivery system's failure modes will find ownerless services, informal ownership conventions that exist only in tribal knowledge, and team boundaries that bear no resemblance to the system's actual dependency graph.

The ownership gap rate is controlled at the point of component creation, not retrospectively. The team topology decision record must specify a service creation protocol: the conditions under which a new service, library, or infrastructure component can be created, the team that will own it (required at creation time, not assigned later), the review process for cross-team dependency introductions, and the process for assigning ownership when a component is inherited from a disbanded team or a completed project. Without the service creation protocol, every new component is a candidate for an ownership gap from the moment it is created. The cumulative effect across an organization that creates dozens of components per month is a system whose actual complexity exceeds the documented complexity by a growing margin — one that only becomes visible during incidents, security audits, or topology reviews.

Three AI session types that embed topology decisions without documenting them

The founding org design session is where the team topology baseline is set. The founding team is planning how to divide the engineering work across a small group of engineers. The AI session helps structure the squads, assign ownership surfaces, and define the initial interaction model. The session is focused on the immediate question — how do we organize now — rather than the structural question — what are the criteria under which this organization should evolve? The result is a structure that is correct for the current scale, embedded in the AI conversation log as rationale for domain boundary choices, and never written as a team topology ADR with an explicit review cadence. Twelve or eighteen months later, when the organization has doubled and the original domain boundaries have become constraints on delivery speed, the founding session's reasoning is accessible only to the engineers who were present — if they are still at the company. The open-source extractor is designed to surface exactly these founding org design sessions as structured decision records, before the structural constraints they created become visible as delivery failures.

The growth-phase headcount planning session is where the topology evolves without a redesign. The organization needs more engineers, the obvious answer is to add engineers to the teams that are most backlogged, and the AI session helps scope the hiring plan by team. The session does not ask: "should we redesign the team boundaries before we add headcount?" because the pressure to hire is immediate and the topology redesign is a three-month process that would delay the solution to the current capacity problem. The result is larger teams with the same domain boundaries, which means larger cognitive load than the original team was designed to carry, which means the delivery problems associated with exceeding the cognitive load ceiling — longer onboarding, more coordination overhead, higher error rate on infrequently-touched services — manifest at the new larger team size rather than being prevented by a domain boundary redesign. This is the mechanism that produced the sixty-five-engineer organization in the first story: each growth phase added engineers to existing teams rather than redesigning the teams to match the current domain complexity. The AI sessions from each growth phase contain the reasoning behind the headcount decisions. None of them contain the question of whether the existing team topology was still appropriate at the new scale, because that question was not part of the headcount planning agenda. WhyChose's extractor surfaces these sessions, which contain the implicit answer to that question: the domain surfaces and ownership assignments that the hiring plans assumed were still appropriate, without anyone having explicitly verified that they were.

The platform team initiation session is where the platform team's scope and interaction model are set. The AI session helps design the platform team's mandate — what it will own, what it will build, how product squads will interact with it. The session focuses on the platform team's initial deliverables and the migration plan for the independent implementations it will replace. It typically does not produce the self-service threshold — the specific criterion that distinguishes "self-service capability" from "shared services team" — because the team is being formed to solve an immediate coordination problem, and the conversation is about how to solve that problem rather than about the organizational failure modes of the solution being designed. The result is a platform team with a clear initial mandate and no documented boundary conditions for its evolution. The approval gates, the request queues, and the governance processes that convert a platform team into a bottleneck are added later, each individually justified, collectively undocumented in terms of their effect on the original X-as-a-service model. The platform engineering decision record — the external platform choice (Backstage, Railway, custom internal tools) — and the team topology decision record for the platform team are complementary documents: the platform engineering decision record covers what is built and why; the team topology decision record covers how the team that builds and operates it is designed to interact with the rest of the organization.

The five sections of a team topology decision record

The first section documents the team topology model selection and organizational stage rationale. This section names the topology model in use — stream-aligned teams, with or without platform, enabling, or complicated-subsystem teams — and explains why this model is appropriate for the current organizational stage. The organizational stage matters because different topology models have different minimum viable team sizes. A platform team is not viable below approximately fifteen to twenty total engineers: below that threshold, the overhead of the platform team itself exceeds the coordination overhead it is designed to reduce. An enabling team is most effective when the organization has identified a capability gap that affects multiple stream-aligned teams and where the capability can be internalized within a bounded engagement. A complicated-subsystem team — a team that owns a specific component with high intellectual complexity requiring specialist knowledge — is justified only when that complexity genuinely exceeds what can be maintained by a stream-aligned team with the current generalist skill distribution. This section also documents the explicit organizational triggers that would prompt a topology review: the headcount threshold at which the current topology will be reassessed ("evaluate at fifty engineers or when any stream-aligned team exceeds fifteen members"), the delivery signal that indicates the current topology is no longer appropriate ("evaluate when cross-team coordination is required for more than forty percent of any squad's backlog items in two consecutive sprints"), and the ownership signal that indicates domain boundaries need redrawing ("evaluate when a new engineer takes more than six weeks to ship independently"). These triggers are the operational definition of "when to revisit this decision" — without them, topology decisions are revisited only in response to crisis, which is the most expensive possible trigger.

The second section documents the domain boundary definition and cognitive load assessment per team. For each stream-aligned team, this section enumerates the services, libraries, databases, and external integrations the team owns, and provides an explicit cognitive load assessment against three proxies: current time-to-productive-contribution for new engineers, current fraction of backlog items requiring cross-team coordination, and engineer-reported confidence in making changes across the team's full ownership surface. The domain boundary for each team must be drawn along natural seams in the system — user journey stages, business capability boundaries, data domain boundaries — rather than along lines of organizational convenience. The section must also document the expansion criteria: the conditions under which a new service or component can be added to the team's ownership surface without triggering a domain boundary review. If a team's ownership surface is already at the cognitive load ceiling, adding new components requires either a domain boundary redistribution or an explicit acknowledgment that the ceiling is being exceeded temporarily, with a scheduled review date. The SLO and error budget decision record is the upstream document for each stream-aligned team's reliability commitments: the team's on-call scope, its incident response model, and its error budget all derive from the SLOs on the services in its ownership surface, which means the cognitive load assessment and the SLO model must be evaluated together to understand the full operational burden the team is carrying.

The third section documents the platform team scope and self-service threshold. This section defines what capabilities the platform team provides, the specific definition of "self-service" for each capability, and the criteria that distinguish capabilities that belong in the platform from capabilities that should remain within stream-aligned teams. The self-service definition is the most important content of this section. A capability is self-service when: a product squad engineer can discover it through documented channels without asking a platform engineer, can configure and deploy it independently using the provided tools and documentation, can get questions answered through asynchronous channels (documentation, runbooks, recorded sessions) for at least eighty percent of common use cases, and can troubleshoot common failure modes independently using the platform's observability tooling. Any capability that fails any of these criteria is not yet self-service and should not be in the mandatory adoption scope until it is. This section also documents the governance model for capability additions — the process by which new capabilities are proposed, evaluated for self-service readiness, and added to the platform's scope — and the governance model for review gates: any gate that requires platform team involvement in a product squad's delivery workflow must be reviewed quarterly against the criterion that the gate is protecting a shared resource that cannot be protected through any less intrusive mechanism. Gates that fail this review are removed from the mandatory scope. Without an explicit removal mechanism, gates accumulate indefinitely, and the platform team's interaction mode drifts from X-as-a-service toward shared services without anyone having made a deliberate decision to change it.

The fourth section documents the team interaction mode and collaboration protocol for each team pair with a non-trivial interaction pattern. Not every team pair requires explicit documentation: teams with no shared dependencies and no planned collaboration can be left undocumented. But every team pair with a current or anticipated collaboration relationship needs an explicit interaction mode assignment, a reason for that mode, and a transition plan if the mode is not the long-term intended mode. For collaboration mode, the section specifies the collaboration scope (what the teams are collaborating on), the planned duration or the condition that would trigger a transition to X-as-a-service, and the communication protocols (joint sprint planning, dedicated Slack channels, shared retros) that the collaboration requires. For X-as-a-service mode, the section specifies the service API and documentation standards the providing team must maintain, the SLA for the service (response time, availability, support turnaround for non-self-service questions), and the process for service evolution (deprecation notice, migration support, backward compatibility window). For facilitating mode, the section specifies the capability being developed, the planned end date for the facilitation engagement, and the success criteria that define "internalized" — the measurable state at which the stream-aligned team can operate the capability independently and the enabling team can step back. The ADR lifecycle decision covers how interaction mode changes are recorded: when a team pair transitions from collaboration to X-as-a-service, the old interaction mode specification should be explicitly superseded in the team topology decision record, with a reference to the transition event and its rationale, so that future engineers reading the record can trace the evolution of the relationship rather than encountering a document that describes a mode that no longer exists.

The fifth section documents the topology review cadence and restructuring criteria. Topology reviews are periodic, structured examinations of the current team structure against the current organizational scale and delivery patterns. The review cadence must be specified alongside the review scope, the review owner, and the output format. The cadence is typically biannual for stable organizations and quarterly for organizations in rapid growth phases where headcount changes may trigger topology misalignments faster than biannual reviews can catch. The review scope must include the organizational triggers from the first section (cognitive load proxies, coordination fraction, onboarding time, ownership gap count), the platform team's self-service metrics (ticket queue length, fraction of requests served self-service, quarterly gate removal decisions), and the interaction mode inventory (which team pairs are in collaboration mode and whether each collaboration has a current justification or is a historical artifact). The restructuring criteria must be explicit: what level of cognitive load excess, coordination overhead, or platform team bottleneck constitutes a mandatory topology redesign versus a domain boundary adjustment within the existing topology. Topology redesigns are expensive — they require engineering leadership time, team identity changes, potential headcount redistribution, and communication to the full organization — and should not be triggered by minor misalignments. But the restructuring criteria must also include a maximum threshold: a topology that exceeds any of the cognitive load proxies by more than fifty percent for two consecutive review cycles is a mandatory restructuring case, regardless of the organizational cost, because the alternative is a delivery system that progressively degrades as the organization continues to scale into a misaligned structure. The review output should produce either a confirmation that the current topology is appropriate for the current scale, a domain boundary adjustment with a named team and implementation timeline, or a topology redesign proposal with a review process for the broader engineering leadership. The decisions never written down post covers why topology decisions are particularly prone to silent staleness: the decision is correct when made, becomes incorrect as the organization scales, and produces no obvious error signal until a delivery failure makes the structural cause visible — at which point the retrospective investigation asks why the topology was not reviewed before the failure rather than after it.

The founding org design session, the growth-phase headcount planning session, and the platform team initiation session each produce team topology decisions whose eventual cost — paid during an eleven-week delivery for a two-week feature, or a platform team that has become the primary blocker for six product squads — exceeds what a documented review cadence would have cost. The decisions are in the AI chat history: the rationale for every domain boundary, the criteria for the platform team mandate, the interaction mode choices made when the teams were forming. WhyChose's open-source extractor surfaces these sessions as structured decision records before the structural constraints they created become visible as delivery failures. The new CTO onboarding problem describes what it costs an incoming engineering leader to reconstruct the reasoning behind a team structure they inherited; the decisions never written down post identifies team topology as one of the most common categories of founding decisions that accumulate invisible organizational interest because no document ever recorded the condition under which the decision should be revisited.