Communication and Stakeholders

A filled example: a device web UI and API change

Here's the template filled in for a change typical of the role: the web UI and REST API of a video-conferencing room device. This is illustrative. The device, the endpoints and the numbers are made up to show how a doc reads; they are not Poly's API or any real product's internals.

# Settings v2: atomic, conflict-safe settings saves for the device web UI

Status: In review (comments close Thu 12 Nov)
Author: <web UI/API lead>    Approver: <client platform architect>
Reviewers: API dev lead (India), web UI dev lead (India), Android platform team, QA lead, security
Tickets: WEB-412, API-388

## 1. Summary
The device web UI saves each changed setting with its own request, so a save can half-apply and two
admins can silently overwrite each other. We propose one PATCH request per save that is validated as a
whole, applied atomically, rejected if someone else saved first, and tells the UI which changes need a
restart. The existing v1 endpoints keep working for partners and older firmware.

## 2. Context
- The settings page calls PUT /api/v1/settings/{key} once per changed field (the network page sends up to 9).
- If request 5 of 9 fails validation, requests 1–4 are already applied: the device is half-configured.
- There is no concurrency check: the last writer wins. Support traced 14 tickets in Q3 to this.
- Some settings only take effect after a restart; the UI can't tell which, so it says "some changes may
  need a restart" after every save.
- Partner integrations and the cloud management service use the v1 endpoints; firmware 4.x devices will
  stay in the field for years and never get v2.

## 3. Goals
- One save = one request, validated in full, applied all-or-nothing.
- A save based on stale data is rejected, and the UI shows what changed.
- The response lists exactly which saved settings need a restart.
- v1 behaviour is unchanged for existing callers.

## 4. Non-goals
- New settings, or changes to which settings exist.
- Telnet / SSH command changes (tracked separately in API-401).
- Cloud management changes; the cloud service keeps using v1 until it opts in.

## 5. Proposed design
### 5.1 Overview
Web UI → PATCH /api/v2/settings → validate all → apply in one config-store transaction → respond.

### 5.2 API
GET /api/v2/settings
  200, ETag: "cfg-1742", body: { "network": { "dhcp": true, ... }, "audio": { ... } }

PATCH /api/v2/settings
  Content-Type: application/merge-patch+json      (RFC 7396)
  If-Match: "cfg-1742"
  body: { "network": { "dhcp": false, "ipv4": "10.0.4.20" }, "audio": { "echoCancel": true } }

  200  ETag: "cfg-1743"
       { "applied": ["network.dhcp", "network.ipv4", "audio.echoCancel"],
         "restartRequired": ["network.dhcp", "network.ipv4"] }
  412  Precondition Failed: someone saved since "cfg-1742"; body says which keys differ
  422  Unprocessable Content, RFC 9457 problem details, one entry per invalid field; nothing applied
  428  Precondition Required: If-Match missing

POST /api/v2/settings/validation      same body; validates only, never applies (dry run for the UI)

### 5.3 Data and storage
Needs an all-or-nothing multi-key write in the device's config store. If the store can't do that
(open question Q1), write to a staging copy and swap it in one step.

### 5.4 UI changes
One Save button per page; a summary of pending changes before saving; on 412, show the other admin's
values next to yours and let the user choose; a persistent "Restart needed for: …" banner.

### 5.5 Compatibility
v1 endpoints stay, re-implemented on top of the v2 apply path, so both share validation. v2 is only
offered by firmware that advertises "settings.v2" in GET /api/capabilities; the UI falls back to v1.

## 6. Alternatives considered
A. Keep per-field PUTs and retry failures in the UI. Smallest change; still not atomic, still last-writer-wins.
B. PUT the whole settings document. Atomic and simple, but every save sends ~40 KB, and an older UI
   would reset settings it doesn't know about (newer firmware adds them).
C. JSON Patch (RFC 6902). More expressive (array operations, test ops), but harder for partners to
   produce by hand, and no setting today is an array that needs element edits. Merge Patch is enough.
   Known limitation: Merge Patch can't set a value to null (null means "remove"); no setting is nullable today.

## 7. Cross-cutting concerns
- Security: same roles as v1 (admin only); every save writes one audit entry with the diff and the user.
- Device performance: one transaction instead of up to 9 requests; to be measured on the lowest-spec model.
- Observability: count 412 and 422 responses; a rising 412 rate means admins are colliding.
- Accessibility: the conflict view must work with a keyboard and a screen reader.

## 8. Testing and rollout
- Contract tests generated from the OpenAPI spec; a concurrency test (two saves, one stale → 412).
- Lab: power-cut during save → device boots with either the old or the new settings, never a mix.
- Behind a feature flag on 5.x builds; lab devices → internal beta fleet → general release.
- Rollback: turn the flag off; the UI falls back to v1 automatically.

## 9. Risks and open questions
| #  | Question or risk                                              | Owner           | Needed by |
| Q1 | Does the config store support multi-key transactions?         | Android platform| 10 Nov    |
| Q2 | Authoritative list of restart-required settings               | Android platform| 13 Nov    |
| R1 | Cloud service sees ETag changes it didn't cause; may resync more | Cloud team    | before beta |

## 10. Decision log
| Date | Decision | Who | Why |
| 3 Nov | Merge Patch over JSON Patch | API lead + author | Partners write it by hand; no array edits needed |

## 11. Sign-off
| Role | Name | Status |
| Approver (client platform) | | pending |
| Security | | pending |

The meeting is the exception, not the default. When you do hold one, send the agenda as a list of unresolved comment threads, give everyone ten minutes at the start to reread them, and end with each thread marked resolved, accepted or turned into an open question with an owner. Record the outcome in the decision log the same day; the India-based team will read it in their morning and start work, so a decision that only lives in the meeting is a decision they don't have.

As the lead you'll review more design docs than you write, many of them from engineers on your India-based team who are writing their first. The review is both quality control and teaching, so it has two passes.

First pass: is it the right problem and the right shape? Read only the summary, context, goals and non-goals. Ask:

• Is the problem real and evidenced, or assumed?
• Would I know, from the goals, whether the finished work succeeded?
• Is anything missing from the non-goals that reviewers will otherwise demand?
• Does someone outside the team (partners, the platform team, the cloud service) depend on this? Are they reviewers?

If the first pass fails, stop and say so in one comment ("Before the details: I think the goal should be X, because Y. Can we agree that first?"). Line comments on a design that's solving the wrong problem waste both people's time.

Second pass: does the design hold up? Now read the design and alternatives:

• Contracts: are request and response examples given, including errors? What does an old client or old firmware see?
• Failure: what happens on a timeout, a reboot mid-operation, a power cut, two users at once?
• Device cost: memory, CPU, connections, flash writes on the lowest-spec model. Measured or guessed?
• Security: who can call it, what's logged, what's exposed on the network?
• Testing and rollout: can it be tested in CI, does it need the lab, how is it turned off?
• Alternatives: is the strongest alternative given a fair hearing?

Write comments the way you'd want them on your own doc: label the weight ("blocking:", "question:", "suggestion:", "nit:"), explain the reason, and propose something when you can. "Blocking: a 412 here means the UI loses the user's edits; could the response include the current values so the UI can show both?" teaches; "This won't work" doesn't.

Here's that template filled in for the same four items as the model, as the client's PM and sponsor would receive it. It's illustrative: names, dates and items are made up.

Subject: Web UI / API status, week of 2 Nov: RED (was AMBER)

**Bottom line:** Settings parity is on track for 20 Nov. The firmware upload page will miss 13 Nov:
it can ship 24 Nov if the platform team shares the signed-package format this week, later if not.
I need a decision from Sam by Fri 6 Nov (see Asks).

**Asks**
- Sam (client PM): choose by Fri 6 Nov between (1) platform shares the package format this week and
  the page ships 24 Nov, or (2) the page moves to the first 5.x update. Without either, 24 Nov slips further.
- Ana (platform): the Telnet command allow-list for 5.x, blocking since Mon 2 Nov; needed by Mon 9 Nov
  to keep 27 Nov.

**Milestones**
| Milestone             | Committed | Forecast | Status | Note                                   |
|-----------------------|-----------|----------|--------|----------------------------------------|
| Settings page parity  | 20 Nov    | 19 Nov   | GREEN  | 41 of 45 settings done                 |
| Settings PATCH API    | 13 Nov    | 17 Nov   | AMBER  | reviewer out 2 days; extra reviewer added |
| Telnet command parity | 27 Nov    | 27 Nov   | AMBER  | blocked on allow-list (Ask 2)          |
| Firmware upload page  | 13 Nov    | 24 Nov   | RED    | waiting for package format (Ask 1)     |

**Done this week**
- Network and audio settings pages merged behind the 5.x flag; contract tests green.
- Validation dry-run endpoint merged (design doc section 5.2).

**Next week**
- Remaining 4 settings; PATCH API review and merge.

**Risks and blockers**
| Risk / blocker            | Since | Impact               | Owner | Next step             |
|---------------------------|-------|----------------------|-------|-----------------------|
| Package format not shared | 28 Oct| firmware page date   | Sam   | decision by 6 Nov     |
| Telnet allow-list         | 2 Nov | Telnet parity date   | Ana   | answer by 9 Nov       |

**FYI**
- Demo of the new network page (6 min recording): <link>. Presented by Meera and Arjun (Pune).

Escalating well

When to escalate is a judgement, but these are the common triggers for a lead on a client engagement:

• A committed date or scope is at risk for a reason the team can't fix (a dependency, a decision nobody is making, a resource you don't control).
• A blocker on another team has aged past the agreed limit and a direct, polite chase hasn't moved it.
• Two stakeholders want incompatible things (the client PM wants the date, the platform architect wants the extra feature) and you're not the person who should choose.
• Anything about security, data loss or safety, immediately, regardless of the schedule.
• A person problem you can't solve at your level, raised privately with your own manager, never in a status email.

Subject: Decision needed by <date>: <the decision, in a few words>

<Name>, I need your help with a decision on <topic> by <date>.

**Situation:** <two or three sentences of fact: what's blocked, since when, what's been tried.>

**Impact if unresolved by <date>:** <the milestone, the date, the users or partners affected.>

**Options**
1. <option>: <consequence for date / scope / risk>. ← my recommendation, because <reason>
2. <option>: <consequence>
3. <do nothing>: <consequence>

**What I need from you:** <choose an option | unblock X | approve Y> by <date>.

<Name of the person whose area this touches> is aware and is copied. Happy to walk through it in <time slot>.

An incident (a release that breaks saving settings on some models, an API change that breaks a partner integration, a security report) changes the rules of status communication. People need updates on a clock, not when there's news, and they need to know what's known, what isn't, and when they'll hear next. The worst incident communication is silence while the team investigates; the second worst is a confident cause that turns out to be wrong.

Subject: [INCIDENT] <short description> — update <n>, <time + time zone>

**Status:** Investigating | Identified | Mitigated | Resolved
**Impact:** <who is affected, how many, since when> (e.g. "devices on build 5.0.2 can't save network settings from the web UI; REST v1 and Telnet unaffected")
**What we know:** <facts only>
**What we don't know yet:** <open questions>
**What we're doing:** <current action, owner>
**Workaround:** <if any, for support and partners>
**Next update:** <time + time zone>, or sooner if anything changes.

What to say, to whom, and when

Expectations are set by what you say and by what you don't contradict. A few habits that keep them realistic:

• One roadmap, owned by the client, with your workstream's items on it. Don't run a separate "real" plan in your own tool; two plans drift, and the client will believe theirs.
• Commit to dates only for work you understand; give ranges for the rest. "Settings parity by 20 Nov; the firmware upload page 2–4 weeks after the platform answers Q1" is honest and still useful. A single date for unknown work becomes a promise you didn't mean to make.
• Separate a forecast from a commitment out loud. "My forecast is the 13th; I'll commit once the spike is done on Friday." Clients hear a date as a promise unless you label it.
• Every new request costs something visible. When a stakeholder adds scope mid-sprint, answer with the trade-off rather than yes or no: "We can add the audit log export; it moves the firmware page by about a week, or we drop the bulk import from this release. Which do you prefer?" The decision stays with the owner of scope, and nobody is surprised later.
• Bring the India-based team into the relationship, not just into the work. Have their leads present demos to the client, put their names on the work, and route technical questions to them directly. A client who knows the people behind the work is more patient with it, and your engineers grow faster (see Delegation and trust without micromanaging).

Priorities will shift: a partner escalation, a trade show demo, a security fix. Shifting priorities are normal on a device platform; what you control is whether the change is explicit. When a client stakeholder asks your team to switch, say yes to the conversation and make the trade visible:

"Understood, the partner demo is the priority. If we move Meera and Arjun onto it now, the firmware upload page moves from the 24th to about the 2nd, and the settings work stays on track. Is that the trade you want? I'll update the roadmap and tell the team today."

Then do three things: confirm it in writing to the person who owns priorities (usually the client PM, even if a director asked), update the shared roadmap so nobody is surprised next week, and explain the why to your engineers, especially the ones being moved. A team that hears "drop that, do this" without a reason twice a month stops caring about the plan; a team that hears why stays engaged. If changes become constant, raise it in a retrospective with the client: maybe the sprint is too long, or the work needs a reserved capacity for interrupts (see Kanban and when it fits better).

You'll disagree with the client's engineers: about an API shape, a security trade-off, a timeline. Disagreeing is part of the job; you were brought in for judgement, and silence when you see a problem is a failure of that job. The skill is disagreeing in a way that improves the decision and leaves the relationship stronger.

Amazon's Leadership Principles name this precisely: "Have Backbone; Disagree and Commit" asks leaders to challenge decisions respectfully when they disagree, and, once a decision is made, to "commit wholly" (amazon.jobs, Leadership Principles, checked October 2026). Jeff Bezos's 2016 letter to shareholders describes using the phrase himself when he disagreed with a team but trusted them to own the outcome. The point isn't Amazon; it's that disagreement and commitment are two phases of the same behaviour, and interviewers for lead roles ask for both.

A sequence that works:

1. Understand their reasons first. Ask what constraints you might not see (support cost, a partner contract, the release train). Restate their position until they agree you've got it right.
2. Raise it privately with the owner before any audience. Nobody changes their mind well in front of their team or their manager.
3. Bring evidence and a proposal, not just a concern. Data, a failing test, a small prototype, an option that addresses their constraint.
4. Propose a cheap way to find out if it's uncertain: a spike, a lab test, a time-boxed trial with a review date.
5. Let the owner decide, and say clearly that you'll support whatever they choose.
6. Commit visibly: build it properly, defend it to your team, don't relitigate in code review or say "I told you so".
7. Write it down with a revisit trigger: what would make you both look at it again.

Here's that sequence written up after a disagreement about the design-doc example above. It's illustrative: the people and the situation are invented to show the shape.

Subject: Settings save for the 5.x launch: decision and follow-up

Ana, thanks for walking me through the release constraints today. Summary so we have it in writing:

**What we discussed:** I proposed shipping the atomic PATCH (settings v2 doc) with the 5.x launch.
Your concern: the config-store transaction support (Q1) won't be verified on all models before the
release branch is cut on 20 Nov, and a late storage change is riskier than the current behaviour.

**My concern, for the record:** per-field saves can half-apply (14 support tickets in Q3), and
partners will start building on 5.x from day one.

**Decision (yours, as API contract owner):** 5.x launches with the existing v1 per-field saves.
v2 ships in the first 5.x update, behind the "settings.v2" capability flag.

**What we'll do now:**
- Web UI: add the validation dry-run before saving, so most invalid saves are caught before any
  request is applied (us, by 18 Nov).
- Platform: verify Q1 on all models by 4 Dec (Ana's team).
- Docs: mark v1 per-field saves as "may partially apply" in the API reference (us).

**Revisit if:** support tickets about partial saves exceed 5 in the first month after launch, or Q1
is verified before 20 Nov.

I'm fully on board with this plan and will brief our team today.

A legacy device platform usually has less written down than you need: the 4.x web UI may be the only specification of how a setting behaves, and the person who knows why a Telnet command answers the way it does may be on the client's platform team. You'll ask the client's engineers a lot of questions, and how you ask decides whether they're glad to help.

**Context:** <what I'm building, one line> (ticket <link>)
**Question:** <one specific question>
**What I've checked:** <docs, code, tests, devices tried, with what result>
**My current assumption:** <what I'll build if I don't hear otherwise>
**Needed by:** <date>, because <what it blocks>

When your team commits to the client's repositories, follow their conventions before you suggest changing them: their branch naming, commit message style, PR template, CODEOWNERS and CI checks. Suggest improvements through their process (a proposal in their engineering forum or a design doc), not by doing it your way in your PRs. Reviews from their engineers on your team's code are a gift: they carry the context about the platform you lack, so make it easy for them (small PRs, clear descriptions, links to the ticket and the design doc) and respond quickly. And review their PRs when asked, with the same care and tone as your own team's: being a good reviewer on their code is one of the fastest ways to earn trust on a client engagement.

The same trade-off, said out loud in a minute

Often you won't have a one-pager; you'll have a minute in a meeting with the client's director. The spoken version keeps the same skeleton (decision, options, recommendation, ask) but cuts to one consequence per option and says the recommendation twice, because listeners lose things that readers can scroll back to.

"We need a decision by Friday on the settings page for launch. We've rebuilt the 45 settings admins use most; there are about 75 rarely used ones left. We can rebuild them all and slip about three weeks, or launch on time with the rare ones on the old-style page, and finish them in the first update. I recommend launching on time with the old-style page for the rare settings. The cost is a mixed look for a few weeks. Are you comfortable with that, or is a consistent look worth the three weeks?"

That's about 95 words, well under a minute at a calm pace. It ends with a question that has two possible answers, both of which you can act on.

Non-engineers hear "risk" as "maybe bad". Make it concrete with two dimensions and a plan: how likely, how bad if it happens, and what you're doing about it.

Three or four rows is enough; a risk register with thirty rows says "we haven't prioritised". Say which one you'd lose sleep over, and why.

For a web UI, the clearest explanation of a trade-off is often a two-minute demo. Showing the old-style page next to the new one answers "is a mixed look acceptable?" better than any paragraph. Keep demos for non-engineers short and outcome-shaped:

1. Say what the viewer is about to see and what you want from them ("whether the old-style page is acceptable for rare settings").
2. Show the user's task, not the code: an admin changing the network settings, saving, seeing the restart banner.
3. Show the failure path too (a conflict, an offline device): that's where trust in the work comes from.
4. End with the decision or feedback you need, and the date.

Record it (a few minutes of screen recording with narration) so the other time zone and the stakeholder who missed the call see the same thing. A recorded demo presented by the India-based engineer who built it does more for that engineer's visibility than any status line.

Analogies help when they carry the one property that matters and nothing else. Technical debt as a loan is the classic: you borrow time now (ship faster), and you pay interest (every change in that area is slower) until you pay it back (refactor). It works because the interest is the point: debt isn't bad, unpaid debt that keeps growing is. A firmware fleet as cars on the road helps explain why an API can't just change: you can update the dealer's showroom (the cloud), but cars already sold (devices in the field) keep their old parts for years.

Analogies mislead when the listener extends them. "The API is like a contract" invites "so the lawyers can sort it out". Use one, say where it stops ("unlike a loan, nobody sends a bill; the interest shows up as slower releases and more bugs"), and move on to the real consequence.

Much of trade-off communication is saying no to something reasonable. Turn a no into a choice: "Yes, if we move the firmware page to the next release; or not this release, and it's first in the next one." If something is genuinely unsafe (shipping Telnet enabled by default on a new device, skipping a security fix to hit a date), say that plainly, separately from the menu: some items aren't options. Tie it to something they already care about ("this is the kind of issue that ends up in a security bulletin with our name on it") rather than to principle.

• Send a pre-read 24 hours ahead (a working day earlier across time zones), with the question, the options and the constraints. Start the meeting with five or ten minutes of silent reading and commenting; people who'd never interrupt will write.
• State the decision rule at the start: "We're aiming for agreement; if we don't have it by the end, Ana decides as API owner." People argue differently when they know how it ends.
• Ask the quietest and most junior people first, by name, before the senior people anchor the room. On a mixed US–India call this matters doubly: the hierarchy and the accent of the most fluent speaker both pull the discussion.
• Separate generating options from judging them. List options without criticism first; evaluate after. Early criticism kills the third option that might have been the best.
• Keep a visible "parking lot" for good points that aren't this decision, with an owner each.
• Summarise the decision, the reasons, the dissent and the actions out loud before ending, then write it within the day.

## <Decision>: <what was decided, in one line>       Date: <date>     Approver: <name>

**Question:** <what we were deciding>
**Options considered:** <A, B, C, one line each>
**Decision:** <option>, because <the deciding reasons>.
**Dissent recorded:** <who disagreed and why, in their words, if they want it recorded>
**Revisit if:** <measurable trigger>
**Actions:** <owner: action by date>
**Not decided (parking lot):** <item: owner>

Many decisions don't need a call at all, which matters when the overlap is an hour a day. Two written patterns work well:

• A decision request with a deadline ("lazy consensus"). Post the question, the options and your proposal in the team's channel or doc, and say "If there are no objections by 10:00 IST Thursday, we'll go with option B." Silence becomes agreement, objections surface in writing, and nobody waits for a meeting. Use it for two-way doors; for contracts, still get the owner's explicit approval.
• A written decision by the approver. The driver collects comments on the doc, summarises the positions fairly (and checks the summary with the people who hold them), and the approver decides in a comment. Everyone in both time zones sees the same reasoning at the same time.

**Decision needed by Thu 12 Nov, 10:00 IST / Wed 11 Nov, 23:30 ET:** which charting library for the diagnostics page.

Options: (A) the library the cloud portal already uses; (B) a lighter one, about a third of the bundle size.
Proposal: **B**, because the device serves the web UI from limited storage and the page only needs line charts.
Details and bundle numbers: <link to ADR draft>

👍 if you agree. Objections in this thread before the deadline; otherwise we go with B and I'll merge the ADR.

A shape that works when a decision really does need a call, held in the overlap window (for example 08:00–08:45 US Eastern, which is 18:30–19:15 IST in winter but 17:30–18:15 IST while the US is on daylight saving time; India doesn't change its clocks, so the overlap moves twice a year):

If the meeting can't decide, that's an acceptable outcome only if it ends with the specific missing input, an owner and a date. "Let's take it offline" without those is how a decision drifts for a month.