Senior-Level Engineering Skills

Key features

• An ADR records Context (the problem/forces), Decision (what was chosen), and Consequences (what this costs, including what it makes harder)
• Architecture review happens BEFORE implementation — its entire value is catching a structural mistake while it is still cheap to change
• A real review always names at least one real cost, not just benefits — a decision with zero listed downsides was not reviewed critically
• A reviewer can raise a blocking concern (must be resolved before approval) or a non-blocking one (worth discussing, does not gate the decision)
• An ADR is a paper trail: six months later, "why did we choose this?" has a written answer instead of relying on someone's memory

Command

def render_adr(title, status, context, decision, consequences):
    return (
        f"# {title}\nStatus: {status}\n\n"
        f"## Context\n{context}\n\n"
        f"## Decision\n{decision}\n\n"
        f"## Consequences\n{consequences}"
    )

Key features

• A function contract states parameters, return value, and every exception it can raise — a caller who only reads the signature still needs to know what can go wrong
• A README's job is getting a new engineer from zero to a running system — install steps, a minimal working example, nothing assumed
• Documentation that restates what the code already says plainly (function_doc for a self-explanatory function) adds maintenance cost with no new information
• Documentation goes stale the moment behavior changes and the docs do not — a docstring claiming a contract the code no longer honors is worse than no docstring
• The best documentation lives next to what it describes (a docstring beside the function) rather than in a separate wiki nobody remembers to open

Command

def function_doc(name, params, returns, raises):
    lines = [f"{name}({', '.join(params)})"]
    lines.append(f"    Returns: {returns}")
    if raises:
        lines.append(f"    Raises: {', '.join(raises)}")
    return "\n".join(lines)

Key features

• A correlation ID (generated at the edge, passed through every downstream call) is what makes one request's log lines findable among millions of interleaved lines from concurrent requests
• A structured log at each boundary (before/after a DB call, before/after an external API call) narrows a failure to a specific step, not just "somewhere in this function"
• git bisect binary-searches deploy history for the exact commit that introduced a regression — O(log n) commits checked instead of a linear crawl through history
• Reproducing locally with production-shaped inputs (the actual failing payload, not a synthetic one) catches bugs a synthetic test case never would
• The goal during an active incident is narrowing fast, not full understanding — a bisected commit or an isolated boundary is often enough to mitigate before every detail is known

Command

import logging, uuid

logger = logging.getLogger(__name__)

def handle_request(payload):
    correlation_id = str(uuid.uuid4())
    logger.info("request_start", extra={"correlation_id": correlation_id})
    # ... every downstream log call also includes correlation_id ...

Key features

• PERT weighting: (optimistic + 4*most_likely + pessimistic) / 6 — most_likely counts four times as much as either extreme
• The pessimistic estimate should account for realistic risk (a dependency turns out to be missing, a design needs revisiting) — not a worst-case asteroid strike
• A large gap between optimistic and pessimistic signals real uncertainty in the task itself — that gap is information, not noise to average away
• Estimating a large, vague task produces a large, vague number — breaking it into smaller pieces first (next concept) makes every individual estimate more honest
• An estimate is a forecast, not a commitment — re-estimating as new information arrives is expected, not a failure of the original estimate

Command

def three_point_estimate(optimistic, most_likely, pessimistic):
    expected = (optimistic + 4 * most_likely + pessimistic) / 6
    return round(expected, 1)

Key features

• A subtask is independently shippable if it is additive (new code, nothing existing changes) or gated behind a feature flag (existing behavior unchanged until the flag flips)
• The genuinely risky step — a cutover, a flag flip, removing the old path — is usually small and should be the LAST subtask, not the first
• Shipping subtasks continuously means each one gets real code review and can be reverted independently, unlike one giant end-of-epic merge
• A task that cannot be split into any independently shippable piece is often a sign it needs a different design, not just smaller commits
• Splitting also improves estimation (previous concept) — five small, well-understood pieces estimate more accurately than one large, vague one

Command

def is_independently_shippable(task):
    return task.get("behind_flag", False) or task.get("additive", False)

Key features

• TODO/FIXME/HACK/XXX comments are the tracked, searchable layer of technical debt — a good first pass, not the whole picture
• A dated TODO ("TODO(2026-06-01): ...") is more actionable than an undated one — it signals when to revisit, not just that something should be revisited eventually
• The riskier debt is untracked: code with no comment at all that the team quietly avoids touching, works around, or over-tests out of fear
• A rising bug rate concentrated in one module, or repeated "just copy that pattern" instead of extracting a shared abstraction, are both symptoms of debt nobody labeled
• Not all debt is bad — deliberate, tracked debt taken to hit a real deadline is a normal engineering tradeoff; the danger is debt nobody can see or plan to repay

Command

import re

def has_debt_marker(line):
    return bool(re.search(r"#\s*(TODO|FIXME|HACK|XXX)", line))

Key features

• A characterization test asserts what the code currently does, not what it should do — even a documented bug gets pinned down, not "fixed" as a side effect of adding the test
• Once a characterization test exists, refactoring proceeds exactly like the tests-before-tests-after case — the test just came from observation instead of a spec
• A "seam" is a place a legacy function can be tested or replaced without touching the rest of the system — extracting a seam is often the very first refactor, before any deeper change
• Fixing a bug discovered via a characterization test is a SEPARATE, deliberate step from the refactor — mixing "pin down current behavior" with "also fix this bug" defeats the point of the pin
• Legacy code with tightly coupled global state or hidden dependencies often needs to extract those dependencies (see: hidden global dependencies) before a characterization test can even be written

Command

def characterize(func, *args, **kwargs):
    """Call the existing function and pin down what it ACTUALLY returns —
    used once to write down current behavior, not to judge correctness."""
    return func(*args, **kwargs)

Key features

• A routing layer decides, per-request, whether a given path/feature has been migrated yet — migrated paths go to the new system, everything else still goes to legacy
• The set of migrated paths only grows over time — each addition is a small, independently shippable and revertible step (see: breaking large tasks into smaller pieces)
• A big-bang rewrite (freeze the old system, build the whole replacement, cut over once) carries much higher risk: months of work either all works on day one or all needs unwinding
• The legacy system is only decommissioned after the LAST piece migrates — until then, both systems coexist and the routing layer is the seam between them
• Migration progress is measurable — the fraction of routes/features already migrated — which makes "how close are we" an actual number instead of a guess

Command

def strangler_route(request_path, migrated_paths):
    return "new_service" if request_path in migrated_paths else "legacy_service"

Key features

• Each migration records a revision id and a down_revision (the migration it builds on) — this chain is how a tool like Alembic knows the order to apply them in
• upgrade() applies the change; downgrade() must be its exact inverse — a migration without a working downgrade cannot be safely rolled back
• A migration should be small and single-purpose (one column, one index) — a migration doing five unrelated things is five migrations pretending to be one
• Migrations run in order, tracked by a version table in the database itself — the database always knows which migrations it has already applied
• A destructive downgrade (DROP COLUMN) permanently loses any data written to that column after the upgrade — rolling back is not free even when it "works"

Command

def upgrade():
    return "ALTER TABLE users ADD COLUMN last_login_at TIMESTAMP NULL"

def downgrade():
    return "ALTER TABLE users DROP COLUMN last_login_at"

Key features

• A canary starts at a small traffic percentage (5-25%) and widens only while the error rate stays under a defined threshold
• A breach at any step sends traffic back to 0% — the rollout does not "hold steady and hope it recovers"
• Widening should be gradual (25% at a time, not 0% straight to 100%) — each step is a fresh chance to catch a problem before more users are exposed
• Safe deployment is a PREVENTIVE practice (limit exposure before full traffic); a rollback is the REACTIVE one (undo a deploy already at full traffic)
• An automated canary check removes the "we forgot to look at the dashboard" failure mode — the rollout can revert itself before a human notices

Command

def route_traffic_percent(canary_healthy, canary_percent):
    return min(canary_percent + 10, 100) if canary_healthy else 0

Key features

• A comment prefixed "blocker:" must be resolved before merge; "nit:" is a minor, optional suggestion; "question:" invites explanation rather than demanding a change
• A teaching comment states WHY, not just what — the underlying rule, not only the specific fix for this one line
• Mentoring is not only correcting mistakes — a "nit:" suggestion to extract a helper function models good practice without blocking anyone's progress
• Over-blocking every minor style preference teaches a junior developer to fear review rather than learn from it — reserve "blocker:" for things that are actually wrong
• The same why explained in review should be something the junior developer can apply unprompted next time — that transfer is the actual measure of successful mentoring

Command

def review_comment(kind, text):
    prefix = {"blocking": "blocker:", "suggestion": "nit:", "question": "question:"}[kind]
    return f"{prefix} {text}"

Key features

• State each option as gain (the concrete benefit) versus cost (what it actually costs — money, complexity, an ongoing operational burden)
• Plain language over jargon — "the page loads 12x faster" lands with a stakeholder in a way "p99 latency drops from 500ms to 40ms" alone may not
• A trade-off summary that lists options with no recommendation pushes the decision onto someone with less context than the engineer who did the analysis
• Cost is not only dollars — "a new dependency to operate," "harder to onboard a new engineer," and "less flexible later" are all real costs worth naming
• A one-sided pitch (all gain, no cost) is not communicating a trade-off — it is a sales pitch, and it erodes trust the first time the hidden cost surfaces

Command

def summarize_tradeoff(option, gain, cost):
    return f"{option}: gain={gain}; cost={cost}"