The Lead Engineer Role

// A lead's calendar in New York (08:00–17:00), working with a team in Bengaluru. How much time is left
// for hands-on work, and is there any block long enough to do it? Times are local "HH:MM".
const DAY_START = "08:00", DAY_END = "17:00", FOCUS_MIN = 120;
const week = {
  Mon: [["08:00", "08:15", "standup (India evening)"], ["08:15", "09:00", "1:1 Asha"], ["10:00", "11:00", "sprint planning"], ["13:00", "14:00", "design review"]],
  Tue: [["08:00", "08:15", "standup"], ["08:15", "09:00", "1:1 Ravi"], ["11:00", "12:00", "client sync"], ["15:00", "15:30", "PM catch-up"]],
  Wed: [["08:00", "08:15", "standup"], ["08:15", "09:00", "1:1 Meera"], ["10:00", "10:30", "hiring screen"], ["11:00", "11:30", "architecture forum"], ["14:00", "14:30", "1:1 manager"], ["15:30", "16:00", "incident review"]],
  Thu: [["08:00", "08:15", "standup"], ["08:15", "09:00", "1:1 Karthik"], ["11:00", "12:00", "client sync"]],
  Fri: [["08:00", "08:15", "standup"], ["08:15", "09:00", "refinement"], ["14:00", "15:00", "demo + retro"]],
};
// Every day also has a review block for the India team's PRs and lunch.
for (const meetings of Object.values(week)) meetings.push(["09:00", "09:45", "PR reviews"], ["12:00", "12:30", "lunch"]);
const min = (hhmm) => { const [h, m] = hhmm.split(":").map(Number); return h * 60 + m; };
const hours = (m) => `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}`;

let freeTotal = 0, focusTotal = 0;
console.log("day    booked  free   longest free block   focus blocks ≥ 2h");
for (const [day, meetings] of Object.entries(week)) {
  const sorted = meetings.map(([a, b]) => [min(a), min(b)]).sort((x, y) => x[0] - y[0]);
  const gaps = [];
  let t = min(DAY_START);
  for (const [a, b] of sorted) { if (a > t) gaps.push(a - t); t = Math.max(t, b); }
  if (min(DAY_END) > t) gaps.push(min(DAY_END) - t);
  const free = gaps.reduce((s, g) => s + g, 0);
  const busy = min(DAY_END) - min(DAY_START) - free;
  const focus = gaps.filter((g) => g >= FOCUS_MIN).reduce((s, g) => s + g, 0);
  freeTotal += free; focusTotal += focus;
  console.log(`${day}  ${hours(busy).padStart(8)}  ${hours(free)}  ${hours(Math.max(...gaps)).padStart(19)}   ${focus ? hours(focus) : "none"}`);
}
console.log(`\nweek: ${hours(freeTotal)} unbooked, of which ${hours(focusTotal)} in blocks of 2 hours or more.`);
console.log("Reviews and unblocking come out of the free time first; hands-on work needs the long blocks.");

day    booked  free   longest free block   focus blocks ≥ 2h
Mon      4h15  4h45                 3h00   3h00
Tue      3h45  5h15                 2h30   2h30
Wed      4h15  4h45                 1h30   none
Thu      3h15  5h45                 4h30   4h30
Fri      3h15  5h45                 2h15   4h15

week: 26h15 unbooked, of which 14h15 in blocks of 2 hours or more.
Reviews and unblocking come out of the free time first; hands-on work needs the long blocks.

// A workstream's risk register, reviewed every week. Score = likelihood × impact (1–5 each).
const REVIEW_DATE = "2026-11-02";
const risks = [
  { risk: "Client's device firmware API docs are incomplete", likelihood: 4, impact: 4, owner: "Lead",
    mitigation: "Spike against a real device; list assumptions; confirm with client's firmware team", reviewed: "2026-10-30" },
  { risk: "Only Asha knows the device sync code", likelihood: 3, impact: 4, owner: "Lead",
    mitigation: "Pair Ravi on the next two sync tickets; write the sync runbook", reviewed: "2026-10-30" },
  { risk: "Staging has 3 devices; production sites have 400", likelihood: 3, impact: 5, owner: "",
    mitigation: "Load-test the status poller with simulated devices", reviewed: "2026-10-12" },
  { risk: "Diwali (8 Nov): most of the India team on leave", likelihood: 5, impact: 2, owner: "Lead",
    mitigation: "Plan the sprint around it; nothing risky ships that week", reviewed: "2026-10-26" },
  { risk: "SSO library major upgrade pending", likelihood: 2, impact: 3, owner: "Meera",
    mitigation: "Upgrade in its own PR after the release", reviewed: "2026-10-28" },
];

const days = (a, b) => Math.round((Date.parse(b) - Date.parse(a)) / 86_400_000);
const flagged = risks.map((r) => {
  const score = r.likelihood * r.impact;
  const flags = [];
  if (score >= 15) flags.push("ESCALATE");
  if (!r.owner) flags.push("NO OWNER");
  if (days(r.reviewed, REVIEW_DATE) > 14) flags.push(`STALE ${days(r.reviewed, REVIEW_DATE)}d`);
  return { ...r, score, flags };
}).sort((a, b) => b.score - a.score);

console.log(`Risk review ${REVIEW_DATE}`);
for (const r of flagged) {
  console.log(`${String(r.score).padStart(2)}  ${r.risk.padEnd(50)} ${(r.owner || "-").padEnd(6)} ${r.flags.join(", ")}`);
}
const toRaise = flagged.filter((r) => r.flags.length);
console.log(`\nFor the status update: ${toRaise.length} risks need attention, ${flagged.filter((r) => r.flags.includes("ESCALATE")).length} to escalate.`);

Risk review 2026-11-02
16  Client's device firmware API docs are incomplete   Lead   ESCALATE
15  Staging has 3 devices; production sites have 400   -      ESCALATE, NO OWNER, STALE 21d
12  Only Asha knows the device sync code               Lead
10  Diwali (8 Nov): most of the India team on leave    Lead
 6  SSO library major upgrade pending                  Meera

For the status update: 2 risks need attention, 2 to escalate.

// Which tasks decide the date? Earliest start/finish through the dependency graph, then slack per task.
const tasks = [ // id, working days, depends on
  ["spike", 3, []], ["contract", 2, ["spike"]], ["schema", 2, []], ["api", 5, ["schema", "contract"]],
  ["ui", 6, ["schema"]], ["ui-wire", 2, ["ui", "api"]], ["load-test", 3, ["api"]], ["pilot", 1, ["ui-wire", "load-test"]],
];
const byId = new Map(tasks.map(([id, days, deps]) => [id, { id, days, deps }]));

// Forward pass: a task starts when all its dependencies have finished.
const order = [];
const visit = (t, seen = new Set()) => { if (seen.has(t.id)) return; seen.add(t.id); t.deps.forEach((d) => visit(byId.get(d), seen)); if (!order.includes(t)) order.push(t); };
for (const t of byId.values()) visit(t);
for (const t of order) { t.start = Math.max(0, ...t.deps.map((d) => byId.get(d).finish)); t.finish = t.start + t.days; }
const end = Math.max(...order.map((t) => t.finish));

// Backward pass: the latest a task can finish without moving the end date.
for (const t of [...order].reverse()) {
  const next = order.filter((n) => n.deps.includes(t.id));
  t.latestFinish = next.length ? Math.min(...next.map((n) => n.latestFinish - n.days)) : end;
  t.slack = t.latestFinish - t.finish;
}
console.log("task        days  start  finish  slack");
for (const t of order) console.log(`${t.id.padEnd(11)} ${String(t.days).padStart(4)} ${String(t.start).padStart(6)} ${String(t.finish).padStart(7)} ${String(t.slack).padStart(6)}${t.slack === 0 ? "  critical" : ""}`);
console.log(`\nend: day ${end}. Critical path: ${order.filter((t) => t.slack === 0).map((t) => t.id).join(" → ")}`);

// What if the firmware spike takes 2 days longer than planned?
byId.get("spike").days += 2;
for (const t of order) { t.start = Math.max(0, ...t.deps.map((d) => byId.get(d).finish)); t.finish = t.start + t.days; }
console.log(`spike +2 days → end: day ${Math.max(...order.map((t) => t.finish))}`);

task        days  start  finish  slack
spike          3      0       3      0  critical
contract       2      3       5      0  critical
schema         2      0       2      3
api            5      5      10      0  critical
ui             6      2       8      3
ui-wire        2     10      12      1
load-test      3     10      13      0  critical
pilot          1     13      14      0  critical

end: day 14. Critical path: spike → contract → api → load-test → pilot
spike +2 days → end: day 16

2026-10-28  Bulk actions run as a server-side job, not from the browser.
  Context:  A bulk reboot of 400 devices from the browser fails if the admin closes the tab.
  Options:  (a) browser loops over devices; (b) server-side job with progress API; (c) firmware batch command.
  Decision: (b) now; (c) later if the firmware supports it (spike by 13 Nov).
  Decided by: <lead>, with Asha and Ravi; <PM> informed. ADR-014.
  Revisit if: the firmware batch command turns out to exist and be reliable.

## DEV-412: Rename a device group

**Why:** admins rename groups when floors are reorganised; today they must delete and recreate.

**Acceptance criteria**
- PATCH /v1/groups/{groupId} with { name } renames the group; returns 200 with the group.
- Names are 1–80 characters, unique per site (case-insensitive); otherwise 422 with a problem body.
- Only users with device-admin on the group's site can rename (403 otherwise).
- The rename appears in the audit log with the user, old name and new name.

**Out of scope:** renaming from the bulk-action screen (DEV-415).

**Notes for the implementer**
- Follow the pattern in groups-api.js (createGroup) for validation and errors.
- The UI calls this from GroupHeader.jsx; Meera owns that part (DEV-413).

**Questions answered so far:** "Do renames notify devices?" No, devices don't store group names.

// After the first round of one-to-ones: what did people say, and what do they agree on?
// Each answer to "What slows you down most?" was tagged with one or more themes while writing notes.
const notes = [
  { who: "Asha (Bengaluru)", slows: ["ci-slow", "ci-flaky"], protect: "daily standup is short" },
  { who: "Ravi (Bengaluru)", slows: ["ci-flaky", "unclear-tickets"], protect: "pairing with Asha" },
  { who: "Meera (Bengaluru)", slows: ["review-wait"], protect: "freedom to pick UI libraries" },
  { who: "Karthik (Bengaluru)", slows: ["ci-slow", "review-wait", "no-staging-devices"], protect: "-" },
  { who: "Dana (US)", slows: ["unclear-tickets"], protect: "client demos every sprint" },
  { who: "Sam (US)", slows: ["ci-flaky", "review-wait"], protect: "daily standup is short" },
];
const LABELS = { "ci-slow": "CI takes ~40 min", "ci-flaky": "CI fails randomly", "review-wait": "waiting for review",
  "unclear-tickets": "tickets missing detail", "no-staging-devices": "too few test devices" };

const count = new Map();
for (const n of notes) for (const t of n.slows) count.set(t, [...(count.get(t) ?? []), n.who.split(" ")[0]]);
console.log("What slows you down most?");
for (const [theme, people] of [...count].sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]))) {
  console.log(`  ${String(people.length).padStart(1)}/${notes.length}  ${LABELS[theme].padEnd(24)} ${people.join(", ")}`);
}
const ci = new Set(notes.filter((n) => n.slows.some((t) => t.startsWith("ci-"))).map((n) => n.who));
console.log(`\nAnything about CI: ${ci.size}/${notes.length} people, in both locations.`);

const keep = new Map();
for (const n of notes) if (n.protect !== "-") keep.set(n.protect, (keep.get(n.protect) ?? 0) + 1);
console.log("Don't break:", [...keep].sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} (${v})`).join("; "));

What slows you down most?
  3/6  CI fails randomly        Asha, Ravi, Sam
  3/6  waiting for review       Meera, Karthik, Sam
  2/6  CI takes ~40 min         Asha, Karthik
  2/6  tickets missing detail   Ravi, Dana
  1/6  too few test devices     Karthik

Anything about CI: 4/6 people, in both locations.
Don't break: daily standup is short (2); pairing with Asha (1); freedom to pick UI libraries (1); client demos every sprint (1)

// First-month reconnaissance: where does this codebase change most, and who knows it? Real git history.
import { execFileSync } from "node:child_process";
import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "hotspots-"));
let day = 0;
const git = (author, ...args) => {
  const when = new Date(Date.UTC(2026, 3, 1 + day, 10)).toISOString(); // one commit a day from 1 April 2026
  return execFileSync("git", args, { cwd: dir, encoding: "utf8", env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null",
    GIT_CONFIG_NOSYSTEM: "1", GIT_AUTHOR_NAME: author, GIT_AUTHOR_EMAIL: `${author.toLowerCase()}@example.com`,
    GIT_COMMITTER_NAME: author, GIT_COMMITTER_EMAIL: `${author.toLowerCase()}@example.com`, GIT_AUTHOR_DATE: when, GIT_COMMITTER_DATE: when } });
};
const grow = (path, n) => { // append n lines to a file
  const file = join(dir, path);
  mkdirSync(join(file, ".."), { recursive: true });
  const old = existsSync(file) ? readFileSync(file, "utf8") : "";
  writeFileSync(file, old + Array.from({ length: n }, (_, i) => `// ${path} change ${day}.${i}`).join("\n") + "\n");
};

git("Lead", "init", "-q", "-b", "main");
// [author, message, [file, lines added]...]: a made-up history, compressed to one commit a day.
const history = [
  ["Asha", "Device list API", ["src/api/devices.js", 120]], ["Ravi", "Room status page", ["src/ui/RoomStatus.jsx", 90]],
  ["Asha", "Login with SSO", ["src/api/auth.js", 200]], ["Asha", "Fix device paging", ["src/api/devices.js", 15]],
  ["Ravi", "Status colours", ["src/ui/RoomStatus.jsx", 20], ["src/lib/format.js", 10]],
  ["Asha", "Fix offline devices shown online", ["src/api/devices.js", 25]], ["Meera", "Duration formatting", ["src/lib/format.js", 15]],
  ["Asha", "Device reboot endpoint", ["src/api/devices.js", 60]], ["Ravi", "Fix status flicker", ["src/ui/RoomStatus.jsx", 12]],
  ["Asha", "Fix reboot timeout", ["src/api/devices.js", 10]], ["Meera", "Fix negative durations", ["src/lib/format.js", 5]],
  ["Asha", "Firmware version filter", ["src/api/devices.js", 40], ["src/ui/RoomStatus.jsx", 15]],
  ["Asha", "Fix firmware sort", ["src/api/devices.js", 8]], ["Ravi", "Settings page", ["src/ui/Settings.jsx", 70]],
];
for (const [author, message, ...changes] of history) {
  for (const [file, lines] of changes) grow(file, lines);
  git(author, "add", "-A");
  day++;
  git(author, "commit", "-q", "-m", message);
}

// Change frequency, fix commits and authors per file, from git log alone.
const log = git("Lead", "log", "--format=@%an|%s", "--numstat");
const files = new Map();
let author, subject;
for (const line of log.split("\n")) {
  if (line.startsWith("@")) [author, subject] = line.slice(1).split("|");
  else if (line.trim()) {
    const path = line.split("\t")[2];
    const f = files.get(path) ?? { commits: 0, fixes: 0, authors: new Map() };
    f.commits++;
    if (/^fix/i.test(subject)) f.fixes++;
    f.authors.set(author, (f.authors.get(author) ?? 0) + 1);
    files.set(path, f);
  }
}
const loc = (path) => readFileSync(join(dir, path), "utf8").split("\n").length - 1;
const rows = [...files].map(([path, f]) => ({ path, ...f, loc: loc(path), score: f.commits * loc(path) }))
  .sort((a, b) => b.score - a.score);
console.log("file                     commits fixes   LOC  hotspot  main author (share)");
for (const r of rows) {
  const [top, n] = [...r.authors].sort((a, b) => b[1] - a[1])[0];
  console.log(`${r.path.padEnd(24)} ${String(r.commits).padStart(7)} ${String(r.fixes).padStart(5)} ${String(r.loc).padStart(5)} ` +
    `${String(r.score).padStart(8)}  ${top} (${Math.round((100 * n) / r.commits)}%)`);
}
rmSync(dir, { recursive: true, force: true });

file                     commits fixes   LOC  hotspot  main author (share)
src/api/devices.js             7     4   278     1946  Asha (100%)
src/ui/RoomStatus.jsx          4     1   137      548  Ravi (75%)
src/api/auth.js                1     0   200      200  Asha (100%)
src/lib/format.js              3     1    30       90  Meera (67%)
src/ui/Settings.jsx            1     0    70       70  Ravi (100%)

// Is the lead the only person who knows the critical code? `git shortlog` per area answers it in seconds.
import { execFileSync } from "node:child_process";
import { mkdtempSync, mkdirSync, appendFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "knowledge-"));
let n = 0;
const git = (author, ...args) => {
  const when = new Date(Date.UTC(2026, 4, 1, 9, n)).toISOString();
  return execFileSync("git", args, { cwd: dir, encoding: "utf8", env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null",
    GIT_CONFIG_NOSYSTEM: "1", GIT_AUTHOR_NAME: author, GIT_AUTHOR_EMAIL: `${author.toLowerCase()}@example.com`,
    GIT_COMMITTER_NAME: author, GIT_COMMITTER_EMAIL: `${author.toLowerCase()}@example.com`, GIT_AUTHOR_DATE: when, GIT_COMMITTER_DATE: when } });
};
const commit = (author, path) => {
  mkdirSync(join(dir, path, ".."), { recursive: true });
  appendFileSync(join(dir, path), `change ${++n}\n`);
  git(author, "add", "-A");
  git(author, "commit", "-q", "-m", `Change ${n} to ${path}`);
};

git("Lead", "init", "-q", "-b", "main");
const work = [["Asha", "src/sync/poller.js", 9], ["Ravi", "src/sync/poller.js", 1], ["Lead", "src/auth/sso.js", 6],
  ["Asha", "src/api/devices.js", 5], ["Ravi", "src/api/devices.js", 4], ["Lead", "src/api/devices.js", 1],
  ["Ravi", "src/ui/RoomStatus.jsx", 6], ["Meera", "src/ui/RoomStatus.jsx", 3]];
for (const [author, path, times] of work) for (let i = 0; i < times; i++) commit(author, path);

for (const area of ["src/sync", "src/auth", "src/api", "src/ui"]) {
  const counts = git("Lead", "shortlog", "-sn", "HEAD", "--", area).trim().split("\n")
    .map((l) => l.trim().split("\t")).map(([c, who]) => [who, Number(c)]);
  const total = counts.reduce((s, [, c]) => s + c, 0);
  const [top, topCount] = counts[0];
  const share = Math.round((100 * topCount) / total);
  const warn = share >= 80 ? (top === "Lead" ? "  ← only the lead knows this" : `  ← only ${top} knows this`) : "";
  console.log(`${area.padEnd(9)} ${counts.map(([w, c]) => `${w} ${c}`).join(", ").padEnd(28)} top ${share}%${warn}`);
}
rmSync(dir, { recursive: true, force: true });

src/sync  Asha 9, Ravi 1               top 90%  ← only Asha knows this
src/auth  Lead 6                       top 100%  ← only the lead knows this
src/api   Asha 5, Ravi 4, Lead 1       top 50%
src/ui    Ravi 6, Meera 3              top 67%

To a client asking for a feature mid-sprint:
  "We can do CSV export this sprint if we move the groups page to next sprint, or we can do it
   next sprint without moving anything. Which matters more to you for the 15 Dec release?"

To a date that isn't achievable:
  "With the current scope, 15 Dec isn't realistic: our estimate is 22 Dec, and the firmware
   API is still a risk. We can hit 15 Dec if bulk firmware update moves to January. I'd
   recommend that; bulk reboot alone covers the main request."

To a shortcut that creates reckless debt:
  "We can skip the integration tests to save two days, but the last three device-sync bugs
   were exactly what those tests catch. I'd rather cut the settings page polish instead."

To your own team, when someone wants to rewrite a module:
  "I agree it's painful. Let's write down what it costs us (time per change, bugs) and fix it
   in slices as we touch it. A full rewrite won't get scheduled; slices will."

// Four requests and one team. Order them by cost of delay ÷ duration (weighted shortest job first).
// Cost of delay is an estimate agreed with the product owner, in "value lost per week" units.
const requests = [
  { name: "Bulk reboot for device groups", costPerWeek: 8, weeks: 3 },
  { name: "CSV export of device list", costPerWeek: 2, weeks: 0.5 },
  { name: "Fix SSO tokens expiring early", costPerWeek: 10, weeks: 0.5 },
  { name: "Pay down device-sync debt", costPerWeek: 3, weeks: 2 },
];

function schedule(order) {
  let t = 0, totalCost = 0;
  const lines = order.map((r) => {
    t += r.weeks;
    totalCost += r.costPerWeek * t; // each request keeps costing until it's done
    return `${r.name} (done week ${t})`;
  });
  return { lines, totalCost };
}

const asked = schedule(requests); // the order they arrived in
const byScore = [...requests].sort((a, b) => b.costPerWeek / b.weeks - a.costPerWeek / a.weeks);
const wsjf = schedule(byScore);
console.log("score = cost of delay per week ÷ weeks:");
for (const r of byScore) console.log(`  ${(r.costPerWeek / r.weeks).toFixed(1).padStart(5)}  ${r.name}`);
console.log(`\nin arrival order: total cost of delay ${asked.totalCost}`);
console.log(`by score:         total cost of delay ${wsjf.totalCost}  →  ${wsjf.lines.join(", ")}`);

score = cost of delay per week ÷ weeks:
   20.0  Fix SSO tokens expiring early
    4.0  CSV export of device list
    2.7  Bulk reboot for device groups
    1.5  Pay down device-sync debt

in arrival order: total cost of delay 89
by score:         total cost of delay 57  →  Fix SSO tokens expiring early (done week 0.5), CSV export of device list (done week 1), Bulk reboot for device groups (done week 4), Pay down device-sync debt (done week 6)