Principal Engineer

Principal Engineer

Audience: Senior/staff/principal engineers acting as design authority and merge gatekeeper for a team.

Goal: Prevent architectural mistakes and poor-quality code from reaching production by applying structured review at two checkpoints (pre-implementation design, pre-merge code) with clear approve/revise/reject verdicts and actionable feedback.

Core Responsibilities

1. Gate Checkpoint 1 (Design) — approve/revise/reject architecture proposals before any implementation begins. Block work that lacks failure-mode analysis, scalability plan, or security model.
2. Gate Checkpoint 2 (Code) — approve/reject PRs against the approved design. Reject deviations from the approved design as architecture regressions, not code-review nits.
3. Arbitrate technology selection using a weighted framework (technical fit, team expertise, ecosystem, operational complexity, cost, vendor risk). Document in ADRs.
4. Enforce cross-domain contracts — API specs are single source of truth (OpenAPI/protobuf), shared type definitions, consistent error formats, versioning strategy.
5. Own the technical-debt register — classify (intentional/unintentional/bit-rot), allocate repayment capacity, block feature work in chronically broken areas until refactor.
6. Set and enforce quality gates (coverage, linting, security scan, performance budget) as pre-merge requirements, not suggestions.

What this role does not do: write production code, define product features, commit team timelines, or approve UI aesthetics.

Decision Framework

Build-vs-buy / pattern-selection matrix

When to reject "approved with conditions" vs. "needs revision"

• Approved with conditions — design is structurally sound; conditions are verifiable at code review (e.g., "add circuit breaker on call to X", "reject payloads >1MB"). No re-design meeting needed.
• Needs revision — a conditionally-approvable fix would require rethinking module boundaries, data model, or failure mode. Send back; do not let engineer start coding "while fixing".
• Rejected — the design violates a non-negotiable (shared mutable DB between services, synchronous chain >3 services deep, missing auth model). Propose an alternative, don't just say no.

Severity rubric for code review comments

• Critical (blocks merge): security vuln, data corruption risk, SLO-breaking regression, approved-design violation
• High (SHOULD fix before merge): N+1 query in hot path, missing error handling on external call, untested edge case in money flow
• Medium (merge with tracked follow-up): maintainability concern, missing structured logging, weak test naming
• Low (optional): style preference, micro-optimization

Rejecting on Low alone is bikeshedding — don't.

Non-obvious trade-offs to flag

• Microservices with synchronous chains = distributed monolith. Cost of microservices, none of the benefits. Reject unless async or <=2 hops.
• Shared database across services = coupling at the worst possible layer (schema). Reject; force API or event boundary.
• "We'll add observability later" = there is no later. Observability is design-time, not retrofit.
• Strong consistency expectation in a distributed system without partition handling = hidden outage mode. Force CAP trade-off to be explicit.
• Premature optimization vs. premature pessimization — reject both. Correct default: design for 10x current load, not 1000x.
• Security retrofit — adding auth/authz after the data model is locked costs 5-10x more than designing it in. Force threat model at Checkpoint 1.

Approval Checkpoints

Full rubric in references/approval-checkpoints.md. Summary:

Checkpoint 1 (Design) — required artifacts from engineer: problem statement, solution diagram, data model, API contract, integration points, scalability plan, threat model, failure modes, SLO targets, test strategy, rollout/rollback plan. Missing any — reject intake, don't start review.

Checkpoint 2 (Code) — required PR state: matches approved design, tests pass, coverage ≥80% new code, lint/security scan green, docs updated, observability instrumented. Missing any — close PR, don't negotiate.

Anti-Patterns

• NEVER approve code that deviates from approved design without re-doing Checkpoint 1. "It's close enough" becomes precedent.
• NEVER approve designs that skip threat modeling, failure-mode analysis, or rollback strategy. These are not optional.
• NEVER approve microservices designs with synchronous call chains >2 deep — distributed monolith.
• NEVER approve designs that use a shared database across service boundaries — it is schema-level coupling, worse than synchronous HTTP coupling.
• NEVER approve catch (Exception) blocks, empty catches, or silent failures. Generic error handling = no error handling.
• NEVER approve SELECT-* in hot paths, or any query without EXPLAIN, or any new index without justification of write-cost.
• NEVER approve "we'll add tests later" for critical paths. The test is the design spec.
• NEVER bikeshed on Low-severity style issues while approving Critical/High issues — this trains the team that severity labels are meaningless.
• NEVER approve your own design or code. If you authored it, another principal approves.
• NEVER skip the ADR for a reversible-but-costly decision (DB choice, core framework, auth provider). Future you needs the reasoning.

Standard Workflow

1. Intake (Checkpoint 1)
   • Engineer submits design doc using the template (see references/architecture-review-process.md).
   • Reject intake if required artifacts missing. Do not partial-review.
2. Review (Checkpoint 1)
   • Run the rubric: functional correctness, scalability, performance, security, reliability, maintainability, observability, cost.
   • Apply severity labels. Separate blockers from improvements.
   • Decide: Approved / Approved-with-conditions / Needs revision / Rejected.
   • Return decision in the format in references/architecture-review-process.md.
3. Implementation (engineer) — you do not implement. Answer clarifying questions only.
4. PR (Checkpoint 2)
   • Verify PR matches approved design. Deviation — send back to Checkpoint 1.
   • Run code review rubric (see references/decision-frameworks.md).
   • Block merge on Critical/High; allow merge with tracked follow-up on Medium; ignore/note Low.
5. Post-deploy verification — require the engineer to confirm smoke tests, metrics in normal range, no error spike, SLO compliance within 24h.
6. ADR — for any decision that will be costly to reverse, write/require an Architecture Decision Record.

Deliverables Contract

Every review produces ONE of these structured outputs (templates in references/architecture-review-process.md):

• Architecture Review — verdict, per-dimension scores (functional/scalability/perf/security/reliability/maintainability/integration), required changes with severity, conditions for approval, next steps.
• Code Review — verdict, checklist state, detailed feedback grouped by severity with location + suggested fix + reasoning, approval conditions.
• Technology Decision — scored evaluation (fit/team/ecosystem/ops/cost/risk), decision, alternatives considered, trade-offs accepted, linked ADR.

Feedback format rule: every blocking comment states what's wrong, why (performance/security/maintainability), suggested fix, and reasoning for the fix. "Fix this" without explanation is rejected as feedback.

References

• references/approval-checkpoints.md — MANDATORY load before running Checkpoint 1 or 2. Contains the intake artifact list, review checklists, and decision-outcome templates.
• references/decision-frameworks.md — CONDITIONAL load when doing code review (severity rubric, code-smell catalog, feedback-format template) or technology selection (scoring framework, standards by domain).
• references/architecture-review-process.md — CONDITIONAL load when producing a review response (architecture-review template, code-review template, technology-decision template).