Review Questions

Bugs are part of it, but most of review's value is knowledge sharing, consistent norms and a safety check on risky changes. "Google's 2018 case study of about nine million reviewed changes describes four expectations: education, maintaining norms, gatekeeping and accident prevention. Microsoft found only about 15% of review comments point at a possible defect, and at least half are about maintainability. So I treat a review as the moment two people come to understand a change instead of one, and the code keeps the team's conventions. It isn't where design gets decided, and it isn't a substitute for tests: if a review finds a bug, I ask for the test that would have caught it."

Learn more: What code review is for.

From big to small: context, design, correctness, tests, security, compatibility, and only then readability. "I read the description and ticket first, so I know why it exists and how urgent it is. I look at the shape of the diff; if it's too big to review well I say so first. I read the tests before the code, because they show what the author thinks it does. Then design, correctness on empty, huge, malformed and retried inputs and the error paths, whether the tests would fail if the code were wrong, authorisation and anything reaching SQL, HTML or logs, API and migration compatibility, and last of all names. Before I call something a bug I check it, and I put the repro in the comment. Every comment says whether it blocks, and the summary gives the verdict."

Learn more: What to look for in a review.

Four real findings: SQL injection through the search text, page 1 skipping the first 50 rows, unstable ordering with no size cap, and a test that would pass with every bug. "The design is fine: right module, right size. But search goes straight into the SQL, so x' OR '1'='1 changes the query; that blocks, and the fix is parameters, not escaping. Page defaults to 1 and the offset is page * size, so page 1 starts at row 50. ORDER BY name isn't unique, so rows can move between pages, and size has no cap. And the only test checks that the string contains site_id = 7, so I'd ask for three tests that would have caught all of it."

Learn more: What to look for in a review.

Each comment says what I'm asking, why it matters, and whether it blocks, with evidence attached. "I use labels such as Conventional Comments: issue (blocking), suggestion (non-blocking), nitpick, question, praise. I comment on the code, not the person, attach a repro or a link to our standard, and point at a direction rather than rewriting their code. Written comments lose tone and cross a time zone, so I avoid sarcasm, idioms and one-word comments. If I see the same issue across several PRs, I stop commenting on each one and talk to the person, then fix the root cause with a guideline, a lint rule or a pairing session."

Learn more: Giving and receiving feedback.

State the consequence, the label and a direction, and leave the choice of fix to the author. "Something like: issue (blocking): this catch swallows the error, so the API returns 200 with an empty list when the database is down, and nothing is logged. Could we let it propagate to the error middleware, which logs it and returns a 503 problem body, or rethrow after logging? That says what goes wrong, that it must be fixed before merge, and offers two ways forward."

Learn more: Giving and receiving feedback.

Block only the first; suggest the second at most; and the third should never reach a human. "A function called getData that deletes data is a correctness and readability problem: the next caller will be misled, so I block and suggest deleteStaleRecords. The loop is my preference, so it's a labelled nit the author can decline. And formatting is the formatter's job: if CI runs prettier --check it can't merge unformatted; if it doesn't, the fix is adding that check, not leaving a comment."

Learn more: Setting coding standards a team will follow and Giving and receiving feedback.

Treat it as a symptom: fix the causes (oversized PRs, overloaded reviewers, a culture where requesting changes feels rude) rather than adding a second required approver. "A 40-second LGTM on 600 lines is worse than no review, because everyone now believes it was checked. I'd talk to the reviewer privately, not in the PR, and then look at why it happened: was the PR too big to review properly, was review time missing from the plan, is blocking a colleague's PR seen as rude? Smaller PRs, protected review time and labels that make blocking normal fix it. A second approver tends to make each one assume the other read it."

Learn more: What code review is for and What to look for in a review.

Small enough to review properly in one sitting: around 100 lines is reasonable, a few hundred is the upper end, 1,000 is too large. "Size changes everything else: small changes are reviewed faster and more thoroughly, introduce fewer bugs, waste less work if the approach is wrong and are easier to roll back. Google's guide says 100 lines is usually reasonable and 1,000 usually too large, and a reviewer can reject a change for size alone. In Google's own data the median change was 24 lines. On a distributed team it matters even more, because the cost of a review is counted in round trips, and each round trip can cost a day."

Learn more: Small pull requests and fast reviews.

Split it, usually as a stack: refactor first, then schema, then API, then UI, each branch built on the one below and each PR reviewed against its parent. "I keep working on the next layer while the bottom one is in review. When feedback lands on the bottom PR, I fix it there and rebase the stack with git rebase --update-refs, which moves every branch label along. Alternatives are vertical slices behind a feature flag, or splitting by reviewer so the DBA only sees the migration. What doesn't count is one PR with fourteen commits: the reviewer still gets one big diff."

Learn more: Small pull requests and fast reviews.

Remove round trips first, then time the reviews well; asking anyone to work faster doesn't help. "Each review round trip across a 10.5- to 11.5-hour gap costs about a day, so the levers are fewer rounds and better timing. I'd keep PRs small and clear enough to pass in one round, label what blocks, approve with comments when only nits are left, and review first thing in my morning, which is the end of their day, so feedback is waiting when they start. I'd also make sure each area has a second reviewer who can approve, ideally in India. A second required reviewer in the US would make it worse."

Learn more: Small pull requests and fast reviews and Working across US and India time zones.

Anything deterministic goes to tools that run before a human looks; people get design, correctness, test quality, security judgement and readability. "Prettier for formatting, ESLint and typescript-eslint for code-quality rules, tsc --noEmit for types, the test suite, dependency and secret scanning, and a size warning on big PRs, all as required status checks in GitHub Actions on every push and in the merge queue. CODEOWNERS routes risky paths, like migrations, auth and the CI config, to the right people. Pre-commit hooks give fast local feedback, but they can be skipped, so CI is the gate. When the same comment comes up in reviews three times, I look for a rule that makes it automatic."

Learn more: Automating the boring parts and Enforcing standards with tooling, not meetings.

No. A hook is a convenience for the author; the guarantee is the same check as a required CI status check. "git commit --no-verify skips a hook entirely, and a hook only runs on machines where someone installed it. So I keep the hook fast, staged files only with lint-staged, and fixing what it can, so nobody wants to skip it, and I run the same commands in CI in check mode, required to merge. The hook catches mistakes seconds after they're made; CI makes sure nothing reaches main without passing."

Learn more: Enforcing standards with tooling, not meetings and Automating the boring parts.

The docs team only, because in CODEOWNERS the last matching pattern wins. "Order in CODEOWNERS is meaning: the catch-all * goes first and the specific rules after it, because a later match overrides an earlier one. GitHub reads the file from the PR's base branch, and one approval from any listed owner of a file satisfies the code-owner requirement for it. I'd also make the tech leads own .github/ itself, so nobody can remove themselves from review by editing the file in their own PR."

// Last match wins: a simplified matcher for the pattern shapes used here (GitHub follows .gitignore rules).
const rules = [
  ["*", "@acme/web-leads"],
  ["/src/api/", "@acme/api-team"],
  ["*.md", "@acme/docs"],
  ["/db/migrations/", "@acme/api-team @acme/dba"],
];
const matches = (pattern, file) =>
  pattern === "*" ? true
  : pattern.startsWith("*.") ? file.endsWith(pattern.slice(1))
  : pattern.endsWith("/") ? `/${file}`.startsWith(pattern)
  : `/${file}` === pattern;

for (const file of ["src/api/devices.js", "src/api/README.md", "db/migrations/0042.sql", "ui/App.jsx"]) {
  const hits = rules.filter(([pattern]) => matches(pattern, file));
  console.log(`${file.padEnd(24)} matched ${hits.map(([p]) => p).join(", ").padEnd(20)} → ${hits.at(-1)[1]}`);
}

src/api/devices.js       matched *, /src/api/         → @acme/api-team
src/api/README.md        matched *, /src/api/, *.md   → @acme/docs
db/migrations/0042.sql   matched *, /db/migrations/   → @acme/api-team @acme/dba
ui/App.jsx               matched *                    → @acme/web-leads

Learn more: Automating the boring parts and Enforcing standards with tooling, not meetings.

The person who opens the PR owns every line, whoever typed it; the review standard doesn't change, but a few things get more attention. "They must have run it and be able to explain it, and the description says what was generated and what they verified. I look harder at whether the tests check the requirement or just the generated behaviour, whether APIs and packages really exist, input reaching SQL, HTML or logs, secrets in logs, and retries and error handling, where generated code is often plausible but wrong. Size limits still apply, because AI makes big diffs effortless, and DORA's 2024 report itself suspects growing changelists behind the estimated drop in delivery stability it associates with AI adoption. And Copilot code review is a useful first pass, not an approval."

Learn more: Reviewing AI-generated code.

Not on your approval alone (on a branch that requires an approval): another reviewer has to approve, and by default its workflows don't even run until someone approves them. "GitHub's docs say that for a PR created by Copilot cloud agent, an approval from the person who asked for it doesn't count toward required approvals. So someone who isn't the requester reviews it. By default GitHub Actions don't run on Copilot's pushes until someone clicks Approve and run workflows. A 2026 setting can skip that step; for a team like ours I'd leave the human step on."

Learn more: Reviewing AI-generated code.

Start with tools, not a document: adopt a formatter and a mainstream lint preset, enforce them everywhere, then write a short page for the judgement calls. "I'd agree Prettier and ESLint with typescript-eslint's recommended configs, wire them into the editor, a pre-commit hook and a required CI check, and reformat the codebase in one dedicated commit so the style argument ends on day one. Then a one-page standard for what tools can't check, such as error handling, input validation, API conventions and PR expectations, each rule with its reason. Anyone can change a standard by a PR that also updates the tooling. For old code, new and touched code first, with a ratchet. And I'd involve the whole team, offshore engineers included, in choosing the deviations."

Learn more: Setting coding standards a team will follow.

Ratchet it: record today's violations as a baseline, fail only on new ones, and let the count only go down. "Fixing them all first blocks the rule forever, and turning it on as a warning means it's ignored. ESLint 10 has this built in as bulk suppressions: eslint --suppress-all writes the current errors to eslint-suppressions.json, which is committed as a visible list of debt. New violations fail CI; when old ones are fixed, --prune-suppressions removes them from the allowance, so the ratchet only tightens."

Learn more: Enforcing standards with tooling, not meetings.

A short, numbered Markdown file in the repository that records one significant decision: its context, the decision, its status and its consequences, good and bad. "That's Michael Nygard's 2011 format; MADR adds the options considered and decision drivers. I write one when a decision is hard to reverse or will puzzle people later: a new database or framework, SSE versus WebSockets, an API versioning policy, a cross-team convention. It's proposed as a pull request, so the PR is the discussion and merging means accepted. On a distributed team it means the reasoning is written down for everyone, not living in one meeting in one time zone."

Learn more: Architecture decision records.

Write a new ADR with the next free number that supersedes ADR 7, and change only ADR 7's status line. "An accepted ADR is a historical record: it explains why that decision was right a year ago. Rewriting it erases the reasoning, and every old PR or incident that cites 'ADR 7' would now point at a different decision. So ADR 12 gets its own context, what changed, its decision and its consequences, with 'Supersedes ADR 7', and ADR 7 becomes 'Superseded by ADR 12', both in the same PR."

Learn more: Architecture decision records.

Tests, review, docs and a demo against the acceptance criteria, with every automatable line enforced as a required check. "For a web UI and API team: reviewed by a code owner; format, lint and types clean; unit and integration tests passing, with coverage on the changed lines; no new high-severity vulnerabilities; API changes in the OpenAPI document; docs and runbooks updated; accessibility checked; and demoed to the product owner on staging. Each automated line is a required status check, so a PR can't merge while it's red, and the human items are checkboxes in the PR template. On a distributed team, a shared written DoD is what keeps quality the same in both locations."

Learn more: Definition of done and quality gates.

No. It passes the acceptance criteria but not the definition of done, so it isn't done, whatever the demo showed. "Acceptance criteria and the DoD are two separate tests. Merging isn't the same as done: the missing tests become a small follow-up before we call it complete, and under the Scrum Guide it can't be presented as done at the review. Then I'd look at the bypass, not the person: who can bypass, when it's acceptable (a recorded production incident, say), and why a deadline was the reason. Repeated bypasses mean the gate or the planning needs to change."

Learn more: Definition of done and quality gates and Enforcing standards with tooling, not meetings.

Acceptance criteria are per item, the definition of done is for every item, and the definition of ready is a team practice for items entering a sprint. "Acceptance criteria say what this story must do, like 'offline devices show in grey with when they were last seen', written by the product owner with the team. The definition of done says how well everything is finished: tests, review, docs, staging. A definition of ready says an item has criteria, designs and known dependencies before we plan it. It isn't in the Scrum Guide, and I'd use it lightly, because a strict one becomes a wall between product and engineering."

Learn more: Definition of done and quality gates.

Adopt a published guide, add a short house style, make the OpenAPI document the source of truth, and lint it in CI. "I'd base it on Google's AIPs, Microsoft's or Zalando's guidelines, and write down only our rules on naming, versioning, pagination, idempotency keys and one error format, RFC 9457 problem details. We work API first: the spec changes in the same PR as the code, so the contract is reviewed as a contract. CI lints it with Redocly or Spectral using our rules, checks for breaking changes against main and generates the docs, so they can't drift. Reviews are then about design and compatibility, not naming."

Learn more: API and documentation standards.

The rename definitely, the enum value very likely, and the optional field normally not. "Renaming a response field breaks every client that reads jobId, so it needs a new version or a transition where both are returned and the old one is deprecated. A new enum value looks additive, but clients switch over the documented values; a generated TypeScript type won't include it, and a loop waiting for 'succeeded or failed' may wait forever. Treat it as breaking unless the API said from the start that clients must tolerate unknown values. A new optional response field is normally safe, because well-behaved clients ignore what they don't know."

Learn more: API and documentation standards and What to look for in a review.

A README that's a hub, a runbook entry per alert, generated reference docs and dated ADRs, all in the repository and reviewed in the same PR as the change. "The README says in one sentence what the service is and links the ADR that explains why it exists, then copy-pasteable run and test commands, a config table, and owners and links. Each alert has a runbook entry for someone who's just been woken up: what it means, impact, what to check, how to fix, when to escalate. The API reference is generated from OpenAPI. Docs live next to the code, so a reviewer can ask 'behaviour changed but no doc did: why?'"

Learn more: API and documentation standards.

Trunk-based for a web UI and API that we deploy continuously; and for device software with several supported lines, still one trunk plus a release branch per line. "Short-lived branches merged to main through pull requests at least daily, unfinished work behind feature flags, and main always releasable because CI runs on every PR. DORA lists trunk-based development as a capability linked to better delivery performance, and it removes the merge week before a release. GitFlow's machinery, develop plus release and hotfix branches with double merges, is for parallel versions, and a cloud service has exactly one version in production. The deciding question is how many versions we support at once and how they ship, not how big the team is."

Learn more: Trunk-based development vs GitFlow and Release branches, tags and hotfixes.

Merge it in small, flagged slices instead. "A three-week branch doesn't just risk conflicts: it hides integration problems until the end, two changes that each pass their own tests but break together, it arrives as one enormous PR nobody can review properly, and it blocks refactoring on main because 'it'll conflict with Sam's branch'. So we merge a slice every day or two behind a feature flag that's off in production, CI tests both paths, and when it's ready we turn it on for internal users, then a percentage, then everyone. Then we delete the flag and the old path."

Learn more: Trunk-based development vs GitFlow and What CI and CD actually mean.

All three give the same files; they differ in history. On a trunk-based team with small PRs I default to squash. "A merge commit keeps the branch's real commits with their hashes and shows where it joined, at the cost of a busier graph. Squash turns the PR into one new commit on main: history reads one line per PR, reverting a PR is one git revert, and people can commit freely on their branch, but the individual commits are gone. Rebase keeps each commit and a straight line, but rewrites every hash, so it needs a clean, deliberate commit series and must never be done to commits others have built on. With squash, I lint the PR title in CI, because it becomes the commit message."

Learn more: Merge, squash and rebase.

No. Git checks whether the branch's commits are reachable from main, and after a squash they aren't: one new commit with the combined change landed instead. "The files are identical, but Git's 'merged' means 'these commits are ancestors of here'. So after a squash or a rebase-and-merge, git branch --merged doesn't list the branch and -d refuses. Once I've checked the PR really merged, I use -D, and let GitHub delete the remote head branch automatically when the PR merges. It's also why a stacked branch built on top of a squashed one needs git rebase --onto."

// After a squash merge, is the branch "merged"? A throwaway repository with fixed names and dates.
import { execFileSync } from "node:child_process";
import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "rq-squash-"));
let minute = 0;
const git = (...args) => {
  const when = `2026-10-20T09:${String(minute++).padStart(2, "0")}:00Z`;
  return execFileSync("git", args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
    env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1", LC_ALL: "C",
      GIT_AUTHOR_NAME: "Meera", GIT_AUTHOR_EMAIL: "meera@example.com", GIT_AUTHOR_DATE: when,
      GIT_COMMITTER_NAME: "Meera", GIT_COMMITTER_EMAIL: "meera@example.com", GIT_COMMITTER_DATE: when } }).trim();
};
const commit = (file, text, msg) => { writeFileSync(join(dir, file), text); git("add", file); git("commit", "-q", "-m", msg); };

git("init", "-q", "-b", "main");
commit("app.js", "export const app = 1;\n", "Initial commit");
git("switch", "-q", "-c", "feature");
commit("login.js", "export const login = () => {};\n", "Add login form");
commit("login.js", "export const login = (u) => u.trim();\n", "Trim the user name");
git("switch", "-q", "main");
git("merge", "-q", "--squash", "feature");
git("commit", "-q", "-m", "Add login form (#12)");

console.log(git("log", "--oneline", "--graph", "--all"));
console.log("\nsame files on main and feature?", git("diff", "main", "feature") === "" ? "yes" : "no");
console.log("git branch --merged main:", git("branch", "--merged", "main").replace(/\s+/g, " "));
try { git("branch", "-d", "feature"); } catch (e) { console.log("git branch -d feature:", e.stderr.split("\n")[0]); }
console.log("git branch -D feature:", git("branch", "-D", "feature"));
rmSync(dir, { recursive: true, force: true });

* f7ebb91 Add login form (#12)
| * c49455d Trim the user name
| * ed29775 Add login form
|/  
* 7b4949c Initial commit

same files on main and feature? yes
git branch --merged main: * main
git branch -d feature: error: the branch 'feature' is not fully merged
git branch -D feature: Deleted branch feature (was c49455d).

Learn more: Merge, squash and rebase.

git push --force-with-lease --force-if-includes, only ever on my own PR branch, and main and release branches protected from force pushes entirely. "A plain --force overwrites whatever is on the remote, including a commit a colleague pushed to my branch that I never fetched. --force-with-lease only overwrites if the remote still points where my remote-tracking ref says, so it's rejected as stale. But after a background fetch that ref is up to date even if I never looked at their commit, so --force-if-includes also checks that my branch has actually contained the remote tip. The golden rule underneath: never rebase commits other people have built on."

Learn more: Merge, squash and rebase.

One logical change that builds and passes tests on its own, with a short imperative subject and a body that explains why. "Each commit should be something you can review, revert or bisect to cleanly. The subject says what, in the imperative, and on our team in Conventional Commits form, fix(api): …, which also drives the version number and the changelog. The body says why: the problem, the cause, the decision, anything surprising, because the diff already shows what changed. I don't police it by hand: a hook or a CI check enforces the format. And with squash merging, the PR title and description become the commit on main, so that's where the effort goes."

Learn more: Commit hygiene and good commit messages.

v4.0.0, because the ! marks a breaking change and breaking changes win. "Under Conventional Commits and Semantic Versioning, I look for breaking changes first: one ! or BREAKING CHANGE: footer means a MAJOR bump, whatever the type. MAJOR goes from 3 to 4 and resets the rest, so 4.0.0. The feature and the fix ship in it but don't add anything on top. Without the breaking commit it would be 3.3.0; with only the fix and the docs, 3.2.2; with only docs, no release at all."

Learn more: Commit hygiene and good commit messages and Release branches, tags and hotfixes.

Fix it on main first with a regression test, then cherry-pick it with -x to the release branch and tag the patch. "The fix goes through a normal, expedited PR on main, so it can never be lost from future releases. If production runs what's on main, that's it: deploy. If we support a released version separately, like software on devices that can't take every build, I cherry-pick the fix onto that version's release branch with -x, run its CI, tag v2.3.1 and ship. Only fixes go to release branches, never features, and release branches are never merged back."

Learn more: Release branches, tags and hotfixes.

Only the time-zone fix. "A release branch only gets fixes for bugs that exist in that release. Device groups is a feature, so it waits for 4.2.0. The empty-group crash only exists in code that came with device groups, so 4.1 doesn't have that bug, and cherry-picking it would probably conflict or drag in half a feature. The time-zone bug is in 4.1.0, so that fix is cherry-picked with -x, the branch's CI runs, and it's tagged v4.1.1."

Learn more: Release branches, tags and hotfixes.

git revert -m 1 <the PR's merge commit>, through a normal PR, never git reset on main. "Revert adds a new commit that applies the inverse change, so everyone's history stays valid and the undo is itself reviewed, tested and deployed. Reset can only cut history at a point, so going back past the bad merge would also remove the three good PRs, and it rewrites main for everyone. -m 1 tells Git the first parent is the mainline, so it undoes what the branch brought in. With squash merging it's a plain revert of the squash commit. Reset is only for my own local or private work."

Learn more: Resolving conflicts and recovering mistakes.

Because Git already considers the original commits merged: re-merging the branch brings in only the new commits, so the revert stays in effect. Revert the revert. "The first merge made the feature's commits ancestors of main. The revert undid their changes but didn't un-merge them, so the second merge only applied the fix commit. The fix is git revert of the revert commit, which Git 2.54 titles 'Reapply …'. Alternatively, reapply the change on a fresh branch so the commits get new hashes. With squash merging this trap doesn't arise, because no branch commits were ever on main."

Learn more: Resolving conflicts and recovering mistakes.

Read what each side changed against the common ancestor, combine both intents, ask the author when it's a product decision, then run the tests. "I turn on merge.conflictStyle=zdiff3, so the conflict shows the original lines as well as ours and theirs. With the ancestor I can see that, say, main changed the timeout and the retries while the branch changed only the timeout, so I keep main's retries change and decide the timeout with the author. Picking 'ours' or 'theirs' wholesale silently drops someone's work. A resolution is new code nobody reviewed, so the tests run before I push. To get fewer: integrate daily, one formatter everywhere, split hot files, and regenerate lockfiles rather than hand-merging them."

Learn more: Resolving conflicts and recovering mistakes.

git bisect run with an automated check: about 10 test runs, because each one halves the range. "First I write the smallest script that exits 0 for good and 1 for bad, ideally the failing unit test or a request to the endpoint. Then git bisect start <bad> <good> and git bisect run <script>, and Git binary-searches on its own. If some commits don't build, the script exits 125 so they're skipped instead of blamed. This is also why I care about small commits that each build: bisect lands on one small, explainable commit instead of a 2,000-line squash or a broken intermediate state."

Learn more: Finding the commit that broke it with git bisect.

Integration is a habit, delivery is "main is always deployable", deployment is "every green commit ships automatically"; each needs the one before. "Continuous integration is everyone merging to main at least daily, every merge verified by an automated build and tests, and a broken build fixed in minutes. Continuous delivery means any commit that passes the pipeline could go to production with one click, and when is a business decision. Continuous deployment removes the decision. For the web UI and API I'd aim for continuous deployment with feature flags, so deploying and releasing are separate; for software installed on devices I'd stop at continuous delivery with staged rollouts, because a bad release is much harder to undo there."

Learn more: What CI and CD actually mean.

No. They're doing automated testing on branches, which is useful, but work only integrates every six to nine days. "Humble's first question is whether everyone pushes to the shared mainline at least daily, and here they don't. Each PR is tested against main as it was when the branch last synced, so two PRs that each pass can still break each other once both merge. To make it CI: smaller PRs that merge within a day, unfinished features behind flags, and a merge queue so each PR is tested with what's ahead of it."

Learn more: What CI and CD actually mean and Quality gates in the pipeline.

One workflow on PRs, pushes to main and the merge queue, cheapest checks first, the build tested as an artefact, and one aggregator job as the required check. "With a read-only token: lint and type-check first; in parallel, unit tests as a matrix over the packages and Node versions we support, and API integration tests against a real Postgres in a service container. The web build waits for lint, uploads the bundle as an artefact, and the end-to-end jobs download that exact artefact and run Playwright in shards, so we test what we'd deploy. npm ci with the npm cache, never a cached node_modules. Short timeouts, superseded PR runs cancelled, and a final 'CI OK' job with if: always() as the single required check. It should take under ten minutes, or people stop waiting for it."

Learn more: A GitHub Actions pipeline for a web UI and API.

A cache is a speed-up that may be missing; an artefact is a product a later job depends on. And caching node_modules ties the cache to one OS and Node version and skips npm ci's lockfile check. "I cache inputs: npm's download cache through setup-node, and incremental lint and TypeScript caches with the commit SHA in the key and restore-keys for the latest earlier entry. I use artefacts for outputs: the built bundle, coverage and test reports. If a cache is missing the job must still be correct, just slower; if an artefact is missing, the job that needs it fails."

Learn more: A GitHub Actions pipeline for a web UI and API.

It's script injection: the PR title is attacker-controlled text pasted into a shell script before the shell runs. "A title like "; curl … | sh; echo " becomes part of the command. The fix is to pass it through an environment variable, env: TITLE: ${{ github.event.pull_request.title }}, and use "$TITLE" in the script, so the shell receives it as data. Branch names and PR bodies are the same. actionlint flags this as 'potentially untrusted', which is one reason we run it on every workflow change."

Learn more: A GitHub Actions pipeline for a web UI and API and Keeping pipelines fast and reliable.

e2e needs the unit tests, so when they failed it was skipped, and GitHub counts a skipped job's check as passing. "That's documented behaviour: a job skipped by an if: or because a job it needs failed reports success, and dependent jobs skipped after a failure may not block merging. The fix is one aggregator job, 'CI OK', that needs every gate, runs with if: always() and fails if any result is failure or cancelled, and make that the only required check from the workflow. It also means renaming matrix jobs never breaks branch protection."

Learn more: Quality gates in the pipeline.

The required workflow has a paths-ignore (or paths/branches) filter on its trigger, so it never started, and a check that never reports stays pending forever. "GitHub's troubleshooting docs say not to put path or branch filters on a required workflow. Instead the workflow always starts, and the jobs decide inside, for example a small 'detect changes' job followed by jobs with if: conditions. A job skipped by if: reports success, so the docs-only PR merges, and code PRs still get the full checks."

Learn more: Quality gates in the pipeline and Automating the boring parts.

Build once, promote the same artefact: staging deploys automatically with a smoke test, production waits for a required reviewer on a protected environment. "Every merge to main builds one artefact named after the commit. Staging deploys it and runs a smoke test against its real URL. Production is a GitHub environment with two or three reviewers across time zones, self-review prevented, deployments only from main, and the production credentials as environment secrets, so the job can't read them until someone approves. Each environment has a concurrency group with cancel-in-progress off, so deploys never overlap or stop halfway. The steps live in a reusable workflow, the cloud login uses OIDC, and schema changes are expand-and-contract so rollback is one command."

Learn more: Environments, approvals and deployment strategies.

Canary to limit blast radius for risky backend changes, blue-green for a fast switch back, flags to separate release from deploy, and staged rings for software on devices; and every one of them depends on schema changes that old and new versions can both run against. "A canary sends 1–5% of traffic to the new version and compares its error rate and latency with the baseline over the same windows before widening. Blue-green runs a full new environment and switches traffic, so rollback is seconds but capacity doubles. Flags ship code switched off. Devices get rings: internal, a small customer group, then everyone. The database is what makes rollback hard: if version 2 renamed a column, version 1 can't run, so we expand and contract: add and write both, move readers, drop the old one later."

Learn more: Environments, approvals and deployment strategies.

Measure the critical path first, then cache dependencies, parallelise, remove false needs, and shard the end-to-end suite, while fixing flakiness at the same time. "With jobs in parallel, the pipeline takes as long as its longest chain of needs, not the sum of its jobs, so speeding up a job off that chain saves money but no waiting. The usual wins: the npm cache so jobs don't spend minutes installing, splitting one big job into parallel lint, unit, integration and E2E jobs, removing dependencies that aren't real, and sharding E2E, which is almost always the long pole. Cancel superseded runs, aim for under ten minutes on PRs, run the full browser matrix nightly. A fast pipeline nobody trusts is still useless."

Learn more: Keeping pipelines fast and reliable and Flaky tests.

Five delivery metrics in two groups, throughput and instability, read together as trends for one service, never as targets or for individuals. "Throughput is change lead time, from commit to running in production, deployment frequency, and failed deployment recovery time. Instability is change fail rate, the share of deployments that need immediate intervention, and since 2024 deployment rework rate, the share of deployments that only happened because of an incident. DORA's key finding is that the best teams are fast and stable at the same time, because small, frequent changes are safer. I'd collect them automatically from the deploy pipeline and the incident tracker and use them to choose what to improve, like a long lead time pointing at slow reviews."

Learn more: DORA metrics.

Probably not: the team most likely split releases into more deploys without changing how fast work flows, and the same failures are spread over a bigger denominator. "If changes really got smaller and moved faster, lead time would fall too, and it didn't. Change fail rate is failed deploys over all deploys, so four times the deploys with the same 20 incidents gives a quarter of the rate. Rework rate fell by exactly the same factor, which is the tell: I'd check the counts behind the ratios, and if the tracker still shows 20 deploy-caused incidents and 5 hotfix or rollback deploys, nothing got safer. That's what happens when one metric becomes a target. The useful question is what stops a commit reaching production faster: reviews, the pipeline, a manual release step."

Learn more: DORA metrics.

I ask what could break and which is the cheapest test that would catch it. "Logic with lots of cases, like validation, formatting or permission rules, gets unit tests, because I can cover every edge in milliseconds. Wiring, the SQL, status codes, the JSON shape and middleware get integration tests against the real HTTP layer and a real database in a container, because that's where most API bugs live. Where two things deploy separately, the web UI and the API, or the API and devices in the field, I add contract tests so a breaking change fails in the provider's pipeline. Then a small set of end-to-end tests for the journeys that would page someone. Each level answers a different question."

Learn more: Unit, integration, contract and end-to-end tests.

(a) unit, (b) contract, (c) integration, (d) end-to-end or a post-deploy smoke test. "The clamp is pure logic at a boundary, so a unit test with (95, 10) catches it in microseconds. The field-name mismatch passes both sides' own tests, because each is self-consistent; a consumer contract verified against the provider catches it in the API's pipeline. The missing migration passes with a mocked repository and fails against PostgreSQL. And the wrong URL is configuration of the deployed artefact, which no test inside the codebase sees."

Learn more: Unit, integration, contract and end-to-end tests.

A stub returns canned answers, a spy is a stub that also records how it was called, a fake is a working simplified implementation, and a mock is pre-programmed with the calls it expects and verifies them itself. Mock the edges you don't own; use fakes or the real thing for what you do own. "The vocabulary is Meszaros's, from xUnit Test Patterns. I'd use a fake device store that really stores things in a Map, a stub for 'latest firmware version', and a spy on the push channel to check it was called once, for the right device. What I avoid is mocking the database, the HTTP layer and the validation library in one test: then it only proves my code calls the mocks the way the test says, passes with wrong SQL and breaks on every refactor."

Learn more: Unit, integration, contract and end-to-end tests.

When the consumer and the provider deploy separately: the web UI and the API, or the API and software on thousands of devices. "Each side's own tests pass, because each is self-consistent, so a breaking change only shows up when both are deployed together. A contract records what each consumer actually reads; the provider verifies its responses against every consumer's contract in its own pipeline. Then 'flatten firmware.version' or 'add status updating' is blocked before it ships, and the report names exactly who would break. Pact is the best-known tool, and it's consumer-driven: contracts come from the consumers' own tests."

Learn more: Unit, integration, contract and end-to-end tests and API and documentation standards.

Both are ways to spend a testing budget, and they agree on what matters: few end-to-end tests, and most of the suite fast and reliable. "The pyramid, from Mike Cohn and Martin Fowler, puts most tests at the unit level because UI tests are slow and brittle. Kent C. Dodds's trophy adds static analysis at the base and puts most tests at the integration level, because in a JavaScript UI many units are thin glue and the bugs are in how pieces fit. Fowler's point is that the disagreement is largely about what we call a unit test. For a web UI I lean towards the trophy, with component tests that render real children; for the API, lots of fast tests against real routes and a real database. I'd choose by where our bugs actually come from."

Learn more: Test pyramid vs testing trophy.

Red builds with no bug go from about one run in 39 to about one in 10, and the run gets four times longer. "A run is green only if no test flakes, so the chance compounds with every flaky-ish test, and E2E tests are both the slowest and the flakiest. Eighty more takes the suite from 2.6% to about 10% of runs red for nothing, and from 1.5 to 6.5 minutes on four workers. Covering the same behaviour with 800 integration tests instead would cost 2.3 minutes and 4.1%. So I'd ask what those E2E tests were meant to protect, cover most of it at the integration or contract level, and keep only the ones that guard a critical journey."

// Red builds with no bug: a run is green only if no test flakes. Per-test numbers are illustrative assumptions.
const kinds = { unit: { secs: 0.005, flake: 1e-6 }, integration: { secs: 0.25, flake: 1 / 50_000 }, e2e: { secs: 15, flake: 1 / 1_000 } };
const WORKERS = 4;

function suite(label, counts) {
  let green = 1, secs = 0;
  for (const [kind, n] of Object.entries(counts)) {
    green *= (1 - kinds[kind].flake) ** n;
    secs += kinds[kind].secs * n;
  }
  const red = (1 - green) * 100;
  console.log(`${label.padEnd(29)} ${(secs / 60 / WORKERS).toFixed(1).padStart(4)} min  red with no bug ${red.toFixed(1).padStart(4)}%  (1 run in ${Math.round(100 / red)})`);
}

suite("2,000 unit, 200 int, 20 E2E", { unit: 2000, integration: 200, e2e: 20 });
suite("... plus 80 more E2E", { unit: 2000, integration: 200, e2e: 100 });
suite("... or 800 more integration", { unit: 2000, integration: 1000, e2e: 20 });

2,000 unit, 200 int, 20 E2E    1.5 min  red with no bug  2.6%  (1 run in 39)
... plus 80 more E2E           6.5 min  red with no bug 10.1%  (1 run in 10)
... or 800 more integration    2.3 min  red with no bug  4.1%  (1 run in 24)

Learn more: Test pyramid vs testing trophy and Flaky tests.

I'd use coverage to find untested code, not as a target: a floor a little below where we are, and in review, coverage of the changed lines. "Coverage says which code ran, not whether anything was checked; a test with no assertions can reach 100%. So a floor stops decay without inviting games, and an untested new branch in a PR is the useful signal. I'd count branches, not just lines. Google's guidance is roughly 60% acceptable, 75% commendable and 90% exemplary, with per-commit coverage more useful than the project figure, and Fowler is suspicious of 100%. Critical code like auth or the device command path gets a higher bar, and occasionally mutation testing, which shows whether the tests actually check anything."

Learn more: Coverage: useful signal or vanity metric and Quality gates in the pipeline.

The code includes 5 a.m., and a mid-window test can't see it; boundary tests at 1, 2, 4 and 5 would. "Coverage is 100% because the only line ran, and both sides of the && were evaluated, so branch coverage doesn't help either. At hour = 5, 5 <= 5 is true, so devices could reboot at 5 a.m. A test for 5 → false fails against this code and passes once it's < 5. That's the mutation-testing lesson in one function: a mutant that turns < into <= survives a mid-range test and dies to a boundary test."

Learn more: Coverage: useful signal or vanity metric.

Make them visible from CI data, quarantine them quickly with an owner, fix the cause, and never retry silently. "A test that passed and failed on the same commit is flaky by definition; a test that fails on every run since a commit is broken, and needs bisecting, not retrying. Flaky tests get tagged out of the blocking suite but run every night, each with an owner and a ticket, so they stop teaching people to ignore red. Then we fix the cause: usually shared state between tests, sleeping instead of waiting for an event, real time instead of a fake clock, or a real network call. Retries are allowed only if retried passes are reported as flaky. Google found that most of their pass-to-fail transitions involved a flaky test, so this is a real cost."

Learn more: Flaky tests.

Broken since c3, so bisect between c2 and c3; the flake on c2 is a separate, smaller problem. "On c2 it failed and passed with the same code, so it's flaky there. But from c3 onwards it never passes again, which means a change in c3 broke it. Re-running would just burn CI minutes. I'd find the change with git bisect between the last pass and c3, fix or revert, and then look at the c2 flake on its own, with repeats or randomised order."

Learn more: Flaky tests and Finding the commit that broke it with git bisect.

Not with a big testing project: make what exists run in CI, then test where the next changes are, starting with characterisation tests. "Before touching a piece of code I'd pin what it does today, quirks included, so any behaviour change becomes a visible decision. Every bug fix starts with a failing test that reproduces it. To get code under test I'd make small, safe seams, like passing the clock or the HTTP client in as a parameter with the old default. Beyond that I'd prioritise hotspots, files that are both complicated and frequently changed, from the Git history. For an API with poor documentation I'd record real request and response pairs as golden-master tests; they double as documentation."

Learn more: Adding tests to a legacy codebase.

Make seams for the clock and the pricing call, pin the current outputs with characterisation tests, and only then change the rounding. "The smallest safe edit is a parameter with defaults, { now = () => new Date(), getPrice = realPricingCall } = {}, so production callers are unaffected and tests can pass a fixed clock and a fake price. Then I'd run it over a spread of real, anonymised inputs: month ends, leap days, every price tier, odd cases from the logs. I'd pin what it returns today, change the rounding, and the tests that fail are exactly the prices that change, which I'd check with whoever owns pricing before updating those pinned values in the same PR."

Learn more: Adding tests to a legacy codebase.

A lightweight framework for complex work based on empiricism: three accountabilities, five events and three artifacts, each with a commitment. "The Product Owner maximises value and orders the Product Backlog; the Scrum Master is accountable for the team's effectiveness and for Scrum being understood; the Developers build a usable, Done Increment each Sprint. Inside Sprints of one month or less, Sprint Planning sets a Sprint Goal and a plan, the Daily Scrum is a 15-minute check on progress toward that goal, the Sprint Review inspects the outcome with stakeholders, and the Retrospective improves how we work. The artifacts are the Product Backlog with the Product Goal, the Sprint Backlog with the Sprint Goal, and the Increment with the Definition of Done. Story points, user stories and velocity are optional practices, not Scrum. That's the 2020 Guide, still the current edition."

Learn more: Scrum in one page.

The Guide doesn't define one: a tech lead is one of the Developers, and the team is self-managing, so I don't assign the work. "What I bring is technical direction and quality. I help the Product Owner understand the cost and risk of items, make sure refinement produces items the team can actually build, keep the Definition of Done meaningful, unblock people, especially across the time zone, and review and pair a lot. I influence what the team decides through clarity and coaching, not by deciding for them. On a team split between the US and India, a big part of the job is making sure decisions and context reach everyone the same day, in writing."

Learn more: Scrum in one page and What a senior or lead engineer is expected to do.

Route it to the Product Owner, the same day, with the trade-off made visible; don't start it quietly in parallel. "The Guide says no changes that would endanger the Sprint Goal, and only the Product Owner can cancel a Sprint or renegotiate scope with the Developers. So I'd say: 'If we start this now, the firmware-scheduling goal won't be met; here's what's done and what the integration would take', and get the Product Owner and the engineering manager into one conversation. Either the goal is obsolete and the PO cancels the Sprint and we replan, or the integration goes to the top of the backlog for the next Sprint. Then it's written down so the India developers see the decision and the reason at the start of their day."

Learn more: Scrum in one page and Shifting priorities and incomplete documentation.

Three different questions, three levels of precision: rough sizes to order the backlog, capacity-based ranges for the Sprint, and probabilistic forecasts for dates. "The Developers size items themselves, usually in points with planning poker. For the Sprint I plan from capacity, who's actually here, with holidays on both the US and India sides, leave, and a new joiner who'll take time from a buddy, times the usual velocity, as a range, and the Sprint Goal comes first. For dates I don't divide by average velocity; I forecast from throughput with a range, like '80% likely by mid-March', and re-forecast every Sprint. Unknowns become timeboxed spikes. And I never use velocity to compare people or teams."

Learn more: Estimation and planning.

Plan for less than 25 for the first Sprint or two, not 40, and say why with numbers. "New joiners spend their first Sprint mostly learning: environment, codebase, domain, our review standards. And their onboarding takes time from the experienced people who produce most of the 25: buddying, reviewing first PRs, pairing, answering questions across the time zone. So I'd say 'about 20 next Sprint, back to 25 in two, and then we'll see the new baseline from real data'. It's Brooks's law in small: adding people to a late project makes it later, at least at first."

Learn more: Estimation and planning and Onboarding and mentoring offshore engineers.

A range with probabilities, from the team's real throughput, not one date from an average. "From the last eight Sprints a Monte Carlo forecast says: 8 Sprints is likely, about 80%; 9 is almost certain; 7 is roughly a one-in-three bet. If you need 7, the conversation is which items can wait, not working harder. And I'll re-forecast every Sprint, because a forecast is a living number."

Learn more: Estimation and planning.

When work arrives unpredictably and the job is to respond quickly: a support or bug queue, ops work, a platform team serving others. "There a two-week commitment would be broken by the first urgent issue. Kanban makes the flow visible, limits work in progress, and manages it with four measures: WIP, throughput, Work Item Age and cycle time. With a service level expectation like '85% of issues resolved within 5 days' the client gets a promise we can keep. For feature work with a client who wants a regular review I'd use Scrum, often with Kanban practices inside it. And the reason WIP limits matter is Little's Law: cycle time is WIP divided by throughput."

Learn more: Kanban and when it fits better.

Limit WIP to about 6: by Little's Law, cycle time is WIP divided by throughput, so 12 ÷ 3 = 4 weeks and 6 ÷ 3 = 2 weeks. "Throughput is set by the team's capacity and item sizes, so starting more work doesn't finish more. The lever left is WIP: stop starting, start finishing. When a column is at its limit, the next useful thing is to help finish or unblock something. It will feel slower to individuals at first and faster for the work, and I'd measure for a few weeks rather than expect it overnight."

Learn more: Kanban and when it fits better.

Treat both as normal and make them explicit: an assumption log for what we don't know, and every priority change decided by the Product Owner with its cost visible. "For missing docs, I keep an assumption log next to the code, each assumption with its evidence, the risk if wrong, an owner and a date to confirm it. Easy-to-reverse decisions I make quickly on an assumption; hard-to-reverse ones, like a public API's shape, I confirm first, often with a timeboxed spike against a real device or simulator, and I pin what we learn with contract tests. For priority changes I don't refuse and I don't silently absorb them: I show the impact on the Sprint Goal, give two options with dates and a recommendation, and get the decision in writing so the India team sees it at the start of their day."

Learn more: Shifting priorities and incomplete documentation.

Do the arithmetic before replying: the bug fits by moving one non-goal item out; the demo feature doesn't fit without dropping goal work, so that's the Product Owner's decision. "With 14 points of capacity left and the Sprint exactly full, taking the login bug means moving UI-9, which isn't part of the Sprint Goal, to next Sprint, so I can say yes and say what was traded. The demo feature would leave us at 16 of 14 even after removing every non-goal item, so the reply is two options for the PO: keep the goal and do the demo next Sprint, or change the goal."

Learn more: Shifting priorities and incomplete documentation and Working with a client's engineering team.

Go back to what the Daily Scrum is for: the Developers inspecting progress toward the Sprint Goal and planning the next day, in 15 minutes. "Status moves into short written updates posted before the call. The call starts by reading the Sprint Goal, then walks the board from right to left, closest to Done first, asking what each item needs to move one column today. Blocked and aged items get an owner on the spot, and anything longer than a minute leaves the call with the two people who need it. If a manager wants status, they get it from the board and a written summary. A 40-minute call starting at 19:30 IST ends after the India working day, so this is also about respect for their time."

Learn more: Running useful standups, refinement and retrospectives.

Fewer, smaller actions, each with one named owner and an observable change, put into the next Sprint Backlog, and start every retro by reviewing last time's. "'Improve communication', owned by 'the team', never happens. 'An end-of-day handoff note in the channel by 19:00 IST, owned by Dev 3' does. An action that keeps reappearing never got time in a Sprint, and the Guide explicitly allows improvements to go into the Sprint Backlog. For a distributed team I'd collect retro input in writing for two days first, so quieter people and people working in a second language contribute equally, and I'd keep managers and the client out of the room, because honest data needs psychological safety."

Learn more: Running useful standups, refinement and retrospectives.

A tech lead is responsible for the team delivering good software, not just for their own code, across four areas: technical direction, delivery, quality and people. "Direction is the design and standards, and making and recording the key decisions. Delivery is breaking work down, sequencing it, tracking risks and keeping stakeholders honestly informed. Quality is review standards, tests, CI gates and managing technical debt deliberately. People is onboarding, mentoring, delegating real ownership and feedback. I stay hands-on, usually on the riskiest or most cross-cutting pieces, but I measure myself by what the team ships and how well it works without me. In a new role I'd agree in writing what I own and what I escalate, because those boundaries differ a lot between companies."

Learn more: What a senior or lead engineer is expected to do.

The tech lead owns how the team builds; the engineering manager owns the people system. "The lead owns technical direction, design and review standards, the breakdown and sequencing of work, and technical risks. The manager owns hiring, performance, careers and team health. They overlap day to day: a lead often mentors and gives technical feedback, but usually doesn't decide promotions or ratings. I'd partner closely: I tell the manager what I see about each engineer's technical growth; they tell me about priorities and staffing. On US teams leading offshore or contract engineers, the lead often does part of the manager's job day to day, so I'd write the line down early."

Learn more: What a senior or lead engineer is expected to do.

I can answer at any moment what we're building and why, the plan and how we're tracking, the main risks, what's decided and what's open, and who's doing what, and those answers are written down where anyone can find them. "In practice: a one-page brief with an explicit out-of-scope list and dated milestones, a risk register I review weekly with an owner for every high risk, and a decision log. I don't do all the work; I make sure it's broken down, sequenced and unblocked, and I raise bad news early with a proposal. I also try not to be a single point of failure: answers in public channels, a second person per area who can decide while I'm asleep, and recurring questions turned into documentation."

Learn more: Owning a workstream.

Nearly everything a reader needs is missing: a status against the plan, dates, the specific risk, and what you need from whom. "I'd lead with a fixed status word against the milestone, 'AT RISK for 15 December', then what's done and what's next with dates and names, then the risk named with its consequence, 'without the firmware team's bulk-command API, bulk update slips to January', and exactly what would remove it: a 30-minute call with their lead by Friday. And end with the decision I need and my recommendation."

Learn more: Owning a workstream and Status updates and escalation.

Learn, then contribute, then lead, with the plan written down and shared in week one. "In the first month I'd mostly listen and learn: one-to-ones with every engineer, here and in India, the PM and the client's engineering contact, asking everyone the same questions, including what's working that I shouldn't break. I'd get the system running, deploy it myself, read the incident history and the busiest code, review PRs daily and ship a few small fixes. In the second month I'd own a real feature, fix one pain point the team named, and start a risk register and a weekly status. By the third month I'd set direction with the team: a roadmap, standards and growth conversations. And I'd adjust the pace to the situation: a team in trouble needs changes sooner."

Learn more: The first 30, 60 and 90 days on a new team or contract.

The CI pain: it's the team's own diagnosis, it helps everyone every day, it speeds up the client's feature, and it's a prerequisite for trunk-based development anyway. "I'd say: 'I'd like to start with CI. The team named it, it'll speed up the feature work, and it's what we need before moving to trunk-based development. I'll have a plan in two weeks.' That lines up the team's pain, the client's date and my manager's goal in one sentence."

Learn more: The first 30, 60 and 90 days on a new team or contract and Keeping pipelines fast and reliable.

I stay hands-on, but I'm deliberate about which code is mine: the work where my experience changes the outcome or that unblocks everyone, and nothing on the critical path while my days are full of interruptions. "I usually take the spikes that decide a design, the first instance of a new pattern so it becomes the template, and cross-cutting changes that need context from several teams. Each sprint I check my hands-on work against a time budget, often around a third of my week, and when it's over I hand something off with support rather than working evenings. I watch for knowledge concentrating in me or anyone else, and my own PRs are the example: small, tested, well described, and reviewed like everyone's."

Learn more: Leading by example in code.

Treat debt like a loan: deliberate, recorded debt with a payback plan is a business decision; reckless debt isn't. Describe it as interest, and pay it down with a steady share of every sprint. "What I avoid is skipping tests to save two days in an area that keeps breaking. To make it a real decision I describe the interest a product owner can weigh: how much longer changes take in that area, which bugs came from it. I prefer a fixed budget, often 10 to 20% of each sprint agreed with the PO and spent mostly on code we're about to change anyway, over a refactoring sprint that never gets approved. Some things aren't negotiable at all: security basics, data integrity, legal requirements and a releasable main. And if a date needs repeated overtime, the plan is wrong."

Learn more: Balancing delivery, quality and people.

Make the numbers concrete, then design around them: the overlap is for what needs a conversation, and everything else is written so it can be picked up without one. "India is UTC+5:30 with no daylight saving; Austin is UTC−5 in summer and UTC−6 in winter, so India is 10.5 or 11.5 hours ahead, and with a shifted India day we share 90 minutes in summer and 30 in winter. The overlap is for the Daily Scrum, decisions, unblocking and live reviews. Everything else is async: tickets that stand on their own, handoff notes with a decision request, a default and a deadline, decisions written in the repository. I give each site whole pieces of work so handoffs happen at boundaries, start my day with the India questions, and rotate who takes the inconvenient slots."

// Austin 08:00–17:00 and India 11:00–20:00 (IST): the shared window either side of the US clock change
// on 1 November 2026, computed from the time-zone database rather than a hard-coded offset.
const offsetMin = (zone, instant) => {
  const name = new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: "longOffset" })
    .formatToParts(instant).find((p) => p.type === "timeZoneName").value; // e.g. "GMT-05:00"
  const [, sign, h, m] = name.match(/GMT([+-])(\d\d):(\d\d)/);
  return (sign === "-" ? -1 : 1) * (Number(h) * 60 + Number(m));
};
const hhmm = (min) => `${String(Math.floor(min / 60)).padStart(2, "0")}:${String(min % 60).padStart(2, "0")}`;

for (const day of ["2026-10-30", "2026-11-02"]) {
  const noon = new Date(`${day}T12:00:00Z`);
  const austin = offsetMin("America/Chicago", noon), india = offsetMin("Asia/Kolkata", noon);
  // Both working days in UTC minutes after midnight.
  const aStart = 8 * 60 - austin, aEnd = 17 * 60 - austin;
  const iStart = 11 * 60 - india, iEnd = 20 * 60 - india;
  const start = Math.max(aStart, iStart), end = Math.min(aEnd, iEnd);
  console.log(`${day}  India ${hhmm(india - austin)} ahead  overlap ${hhmm(start + austin)}–${hhmm(end + austin)} Austin` +
    ` = ${hhmm(start + india)}–${hhmm(end + india)} IST  (${end - start} min)`);
}

2026-10-30  India 10:30 ahead  overlap 08:00–09:30 Austin = 18:30–20:00 IST  (90 min)
2026-11-02  India 11:30 ahead  overlap 08:00–08:30 Austin = 19:30–20:00 IST  (30 min)

Learn more: Working across US and India time zones.

Because in development every handoff costs context, and the research found distributed work takes longer, not shorter. "Herbsleb and Mockus's 2003 study found distributed work items appeared to take about two and a half times as long as similar single-site items, and tied the delay to more people being involved. So for a product team I'd do the opposite: give each site whole pieces it can finish, a feature, a component or an API end to end, and hand over at boundaries like contracts and PRs, not mid-task. Follow-the-sun does work for queue-shaped work in small self-contained units: support tickets, incident response with a good runbook, monitoring."

Learn more: Working across US and India time zones.

Treat writing as the interface between the sites and hold it to the standard of an API: complete enough that the reader can act without calling the author. "Tickets have context, checklist acceptance criteria, out of scope, how to test, and a questions section naming who answers in the overlap and a default assumption if they're blocked, so a question costs minutes instead of a day. Anything bigger gets a one-page spec reviewed in writing by both sites. Decisions made in calls aren't decisions until they're in the decision log. Short recorded demos replace live walkthroughs. And I watch for the side effect the research describes, groups becoming siloed, by deliberately pairing people across sites."

Learn more: Async communication that works.

It carries no information and wastes their whole morning: they read it at 11:00 IST, can't act on it, and nobody in Austin is awake until the overlap. Send the content, not a meeting request. "Something like: 'Thanks for this. One change before merge: please move the range check into the API handler, because the API is the source of truth (ADR-014); the UI may also check but mustn't be the only check. The rest looks good. If you'd rather keep it in the UI for a reason I'm missing, say so in the PR and we'll talk at 08:00 CT / 19:30 IST.' They can do the work in their morning and have it ready when Austin wakes up."

Learn more: Async communication that works.

Design onboarding instead of letting it happen, because the default outcome for a remote joiner is isolation. "Before day one, access is requested and a small, real first ticket is chosen. In week one the joiner gets the system running from the README, fixing any gaps, merges a first PR, and learns our working agreement: the overlap hours, how to ask a blocking question, and the default-if-blocked rule. They get a local buddy in India and short pairing sessions with me in the overlap. Over 30 days they own one area and review others' PRs; by 60 they own a feature from spec to release and demo it themselves; by 90 they lead a design discussion and we agree a growth plan. Check-ins at 30 and 90 days are booked on day one."

Learn more: Onboarding and mentoring offshore engineers.

Treat the silence as a signal, not as "fine": make asking cheap and explicit, look for blockers you can't see, and add scaffolding for a while, without making it feel like a performance problem. "I'd have a one-to-one in the overlap with specific questions: 'what's the slowest part of your day?', 'what did you try on the simulator setup?', 'what would you need from me to finish UI-207 this week?'. Specific questions get specific answers; 'any problems?' gets 'no'. I'd check for missing access, a simulator that won't run on their machine, a ticket waiting on a client answer. Then a smaller next ticket, a daily 15-minute slot with the buddy, a rule that a blocker unresolved after an hour goes in the channel with its default, and a look again in two weeks."

Learn more: Onboarding and mentoring offshore engineers and Cultural awareness and giving feedback across cultures.

Delegate outcomes and decisions, not just tasks, and make the level of delegation explicit per decision. "Across eleven hours, every decision that waits for me costs the India team a day. So on a delegation board, how to implement a ticket is fully the developer's call within our standards; a new dependency is 'you decide after asking my view'; a public API change needs agreement; a production hotfix outside Austin hours is 'follow the runbook and tell me'. For bigger pieces I write a short brief: outcome, why, constraints, decision rights, resources, scheduled check-ins and when to escalate. The guardrails are the standards and CI, not me approving every approach, and as people show judgement, decisions move up a level."

Learn more: Delegation and trust without micromanaging.

The same structure everywhere, situation, behaviour, impact, then ask for their view and agree one concrete change, delivered privately and live for anything corrective. "SBI is specific about the work and respectful of the person, which lands well whether someone's used to direct or indirect feedback. Corrective feedback is one-to-one, on video, in the overlap, then summarised in writing so nothing is ambiguous; praise can be public. I know frameworks like Erin Meyer's Culture Map, where the US is very low-context and India high-context, but I use them to check my own assumptions, not to predict individuals. In practice I don't treat silence as agreement, I ask for options or a playback, I collect views in writing before meetings, and I write requirements literally: 'please change', not 'maybe consider'."

Learn more: Cultural awareness and giving feedback across cultures.

"Yes" may have meant "I understand and I'll try my best", and the question gave no safe way to say "it's at risk". Next time, ask questions that produce information, and make the work visible so you don't depend on the answer. "A closed question from a senior person invites 'yes' anywhere, more so where contradicting the lead is uncomfortable. I'd ask 'what's left to do, and what could stop it being ready by Thursday?' or 'how confident are you, one to five?', look at the board and the draft PR myself, and agree up front what happens if it's at risk: 'tell me by Wednesday 19:00 IST and we'll demo the UI against the mock'. And I wouldn't conclude they're unreliable; the process failed to surface the risk."

Learn more: Cultural awareness and giving feedback across cultures.

Don't add a site-based gate; investigate the area, not the site, and fix the cause with shared mechanisms. "A site gate would slow every India PR by up to a day, signal distrust, and miss the cause if it's something else. I'd check the area's tests (does device-settings have contract tests against each firmware version?), its inputs (is the device's settings API documented, or are people building on assumptions?), and its review flow (who reviews it, with what expertise?). Then: contract tests in that area's definition of done as a required check, an owner with device expertise on each site in CODEOWNERS, and written device-API notes, and measure escaped defects again in two months."

Learn more: Keeping quality consistent across locations.

When it changes a contract others rely on, needs more than one team, has at least two credible designs with real consequences, touches security, migration or firmware compatibility, or spans several people or sprints. "The doc has the problem with evidence, goals and non-goals, the proposed API with request and response examples including errors, two or three real alternatives and why they lose, compatibility for old clients and firmware, testing and rollout, and open questions with owners and dates. I share it with a comment deadline so people in India and the US review in their own hours, there's one named approver, and decisions go into a log in the doc. For small, reversible changes a good PR description is enough."

Learn more: Writing a design document.

Understand it, then tell the people who committed to the date the same day, before it shows up in a group update, with options and a recommendation. "First: how much, why, and what options we have, cutting scope, adding a person, moving a dependency. Then my manager and the client's PM hear it directly, with my recommendation. In the written update the item goes amber or red by the rules we agreed at the start, with the new forecast next to the original date. What I don't do is keep it green while hoping we'll catch up: a two-day slip reported early is a planning detail, a two-week slip reported late is a trust problem."

Learn more: Status updates and escalation.

Red, and you escalate today. "Thursday, Friday, Monday, Tuesday: four working days blocked on someone outside the team. The forecast date hasn't moved, but a four-day external blocker makes that forecast a hope; the rule makes the colour follow the cause, not the optimism. I've already chased the engineer once, so the next step is their lead, with the question, since when, the impact on the date and the options, such as building against the commands both OS versions support. I'd tell the engineer I'm raising it and why, then report it red in the weekly update with the ask."

Learn more: Status updates and escalation.

Understand their reasons privately first, bring evidence and an option that addresses their constraint, let the owner decide, then commit fully. "There's usually a constraint I can't see: a release date, a partner contract, a support cost. I'd restate their position until they agree I've got it, then bring data, a failing test or a small prototype, and propose a cheap way to find out if it's uncertain. If they still choose their way and they own that part of the platform, it's their call: I'd build it properly, back it to my team, write down the decision with what would make us revisit it, and look for ways to reduce the risk I was worried about inside their decision. What I wouldn't do is go around them or reargue it in code review."

Learn more: Working with a client's engineering team.

Say yes to the conversation and make the trade visible, confirm the change in writing with whoever owns priorities, and give your engineers a simple rule for direct requests. "To the director: 'Understood, the demo is the priority. If we move two people 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?' Then I confirm it with the client PM, update the shared roadmap, and explain the why to the engineers being moved. For direct requests, direct contact is good, but anything that changes what's being built goes through the ticket and the person who owns priorities, and my engineers can always say 'happy to; can you add it to the board?', knowing I'll back them."

Learn more: Working with a client's engineering team and Shifting priorities and incomplete documentation.

Ask one specific question at a time, in writing, with what you've checked, your current assumption and when you need it, and teach the team to ask directly the same way. "'When DHCP is switched off with no static IP set, does 4.x reject the save or keep the old address?' can be answered in a line; 'how does the network page work?' can't. Saying what I've checked respects the expert's time and often reveals the answer. My current assumption makes silence productive: the team keeps moving on it, and the expert can correct it in one line. 'Needed by, because…' lets them prioritise honestly, and it's the date I'd use if I had to escalate. And my India engineers ask the client directly, because a lead who relays every question becomes the bottleneck."

Learn more: Working with a client's engineering team and Shifting priorities and incomplete documentation.

As a menu with prices: the decision and its deadline first, two or three options described by their consequences, my recommendation in one sentence, and one ask. "I translate rather than simplify: same substance, their units, which are outcomes, dates, costs and risks. For example: 'We need a decision by Friday on the settings page for launch. We can rebuild everything and slip about three weeks, or launch on time with the rarely used settings on the old-style page and finish them in the first update. I recommend launching on time; the cost is a mixed look for a few weeks. Are you comfortable with that?' Ranges, not false precision, and I check understanding by asking what they'd tell their boss."

Learn more: Explaining technical trade-offs to non-engineers.

Agree the question and who decides before arguing about answers, give everyone a way to be heard, find the criterion you actually disagree on, and end with a written decision. "Usually one approver, the person who owns that area. I send a short pre-read with the options a day ahead, start with silent reading, and ask the quieter and more junior people first. If we're split, a quick weighted comparison often shows it's one assumption, like whether we need two-way messaging, and that becomes a question with an owner. I match the process to how reversible the decision is. And I end by saying the decision, the reasons and any dissent out loud, then write it down the same day."

Learn more: Running technical discussions and making decisions.

(a) two-way, light process; (b) one-way: design doc and the contract owner approves; (c) two-way: decide, ship, watch; (d) one-way and a security decision: design review, security sign-off, owner approves. "The test for each: if we're wrong, how expensive is it to undo, and how many people outside the team pay? A library inside the web UI can be undone and affects only us, so a short ADR is enough. Public field names become a contract the moment partners script against them and firmware ships with them. Tab order is reversible next release. And a Telnet default ships on every device, sends credentials in clear text, and is very hard to take back from a fleet in the field."

Learn more: Running technical discussions and making decisions and Shifting priorities and incomplete documentation.

Against a rubric, from the interviewer's written notes, competency by competency, so anything you don't say didn't happen. "In a structured interview each interviewer has a few competencies, asks prepared questions with prepared follow-ups, writes down what I say and rates the evidence afterwards, usually before hearing anyone else's view. So I make the notes easy to write: one specific time, 'I' for my actions, the options I saw and why I chose one, a result with a number, and what I learned. For a lead role, at least half my stories should be lead-sized: other people did most of the building, and my actions were deciding, unblocking, reviewing, teaching and communicating."

Learn more: How behavioural interviews are scored.

One specific time, told as STAR with a learning, in about two minutes, with "I" for your actions; the story itself has to be yours, from your story bank. "I'd open with a one-line headline of what I did and the result, give about 30 seconds of situation and task (team, sites, the problem and why it mattered), spend about half the answer on three to five actions, each with a 'because', end with a result that has a number and says how I know it, and one thing I learned or kept doing. Then stop and let the interviewer steer with follow-ups." The card can't give you the story: find it with the story prompts for requirement 8, mentoring and distributed teams, and write it in My notes.

Learn more: The STAR method and its variants, Story prompts: build your own stories and your own stories in My notes.

The shape is one real time where you made the ambiguity explicit: what you wrote down and confirmed, the trade-off you made visible, and what you left behind for the next person. The common mistake is a generalised answer about what you "usually do". "'Documentation is always out of date; what I generally do is read the code and talk to people' describes good habits and scores nothing, because there's no situation, no action that happened and no result. The fix is to anchor those habits in one story: the specific feature, what the only specification was, what I did to find out and confirm the behaviour, the result, and the document or tests that existed afterwards." Find the story with the prompts for requirement 10, ambiguity and shifting priorities.

Learn more: Questions for a lead full stack role, Story prompts: build your own stories and Shifting priorities and incomplete documentation.

Both halves of disagree-and-commit: that you understood their side and disagreed with evidence, and what happened to the decision and the relationship afterwards. "The structure: the decision and why it mattered in a sentence or two; their position restated in a way they'd agree with; what I did, privately first, with evidence or a cheap way to find out; who decided, and what I did after the decision, including how I reduced the risk I'd worried about; the result, including the working relationship; and what I'd do differently." The story has to be a real one of yours; the prompts for requirement 9, client and stakeholder communication, are the place to look for it.

Learn more: The STAR method and its variants, Story prompts: build your own stories and Working with a client's engineering team.

Exactly what's true, in three parts: the adjacent thing you have done, what you understand about the gap, and how you'd close it in the first weeks. "A shape: 'I haven't used MCP in a job yet. What I do use daily is [your real assistant workflow], and here's how I verify its output. I understand MCP as an open protocol that lets an AI host connect to tool and data servers through a standard interface' (and only if you've built one: 'I've built a small server that…'). 'In the first weeks I'd…'. Interviewers hire people who learn quickly and tell the truth, and reject people caught overstating."

Learn more: Questions for a lead full stack role, Reviewing AI-generated code, and MCP itself from zero on the AI-Assisted Dev site: What MCP is and the problem it solves.

Three to five specific, open questions tailored to who they are, ideally one that follows up on something they said earlier. "With a hiring manager: 'What would make you say in six months that this hire was a great decision? And what's the hardest part of getting there?' Then something from the conversation: 'You mentioned the Telnet API has partners on old firmware; how does the team decide how long to support an old version?' And: 'How do the US and India teams split the work today, and what would you change?' Then I listen and take notes, because the answers are data about the job."

Learn more: Questions to ask the interviewer.