Run pnpm build to enable search.

Code Review

Code review exists for two things: quality and growth. The mistake is using it as a gate.

The gate is upfront clarity — a definition doc before Build starts, tests that prove the feature works, and a feature flag for rollout control. If those are in place, the PR is how code gets merged, not how it gets approved. Review that blocks shipping is a scheduling problem dressed up as a quality process.

Most decisions are reversible. Make them. The team is trusted to think critically and ship. You do not need sign-off on everything — only on changes where the consequences are hard to undo. If you can revert it, roll it back, or turn it off with a flag, that is a two-way door. Walk through it. The list below is the one-way doors: changes where getting it wrong has lasting consequences.

When Another Engineer Must See Your Code

Some changes carry enough risk to require a second set of eyes before merge:

  • Authentication or authorization
  • Payment processing
  • Data migrations or deletions
  • API contracts other teams or external clients depend on
  • Introducing an architectural pattern that will propagate widely

When your change touches any of these:

  1. Open the PR.
  2. Message the engineer who knows this area best. If you are not sure who that is, ask your lead. One message — PR link and one sentence on what needs their eyes.
  3. They respond within the same working day with a comment on the PR or a direct reply. “LGTM” is sufficient. Specific feedback is better.
  4. Once you have that response, merge.

If there is no response by end of day: ping once more. If still nothing, flag it to your lead. Do not sit on it. Do not merge without sign-off.

The reviewer owns the turnaround. You own getting it in front of the right person clearly and early.

Everything else ships on your judgment.

The First 90 Days

On your first day, your lead assigns you a designated reviewer. This person is your primary set of eyes for the onboarding period. The goal is not supervision — it is pattern transfer. The fastest way to learn what belongs in this codebase is to have someone who knows it read your code while you are still building the mental model.

0–30 days: Everything reviewed before merge

Every PR goes to your designated reviewer before you merge.

  1. Open the PR.
  2. Message your designated reviewer with the link. One sentence on what you built and what you want them to check.
  3. They respond same working day — a PR comment or a direct reply is the sign-off.
  4. Address any feedback. Then merge.

You do not merge without their sign-off. They do not make you wait more than a working day.

30–60 days: Review on new ground

You merge freely in any area of the codebase you have already shipped in. You still go to your reviewer when:

  • Your change touches any required category listed above
  • It is your first time in a part of the codebase you have not worked in before

Same process. Same turnaround expectation.

60–90 days: Full autonomy except required categories

You follow the same rules as every other engineer. Required categories go for review. Everything else ships on your judgment.

Graduating between phases

Moving between phases is not automatic. At the end of each phase, your lead reviews the code you shipped — in the monthly code walk — and makes the call. You do not assume you have graduated. Your lead tells you explicitly.

If you are not ready at 30 days, the phase extends. There is no penalty. The timeline is a guide, not a deadline.

The Code Walk

Every engineer, regardless of level or tenure, does a code walk in their 1:1. Once a month, 30 minutes. The engineer leads. The lead asks questions.

This is not a code review. The code shipped — if it is broken, that is a different conversation. The code walk is a coaching session. It is how leadership stays close to quality without blocking anyone, and how mentoring needs surface before something goes wrong.

Before the meeting — engineer’s prep

Pick 1 to 2 PRs from the past month. Not your best work. Representative work — the kind of thing you shipped most of. Share the links with your lead 24 hours before.

The meeting

0–5 min: Context Engineer gives a one-minute summary per PR. What was the problem, what you built, what shipped.

5–20 min: Walk Engineer shares screen and walks through the code. Lead asks questions as they come up:

  • Why did you structure it this way?
  • What would you do differently now?
  • How would someone new to this area understand what is happening here?
  • Is there anything here you were not sure about when you wrote it?

The lead is not approving or rejecting. They are asking the questions the engineer should be asking themselves.

20–28 min: Observations Lead shares 2 to 3 specific observations — what is working, what to tighten, what pattern is worth repeating or dropping. Tied to the actual code, not general advice.

28–30 min: One thing to carry forward One specific improvement the engineer applies before the next code walk. It must be named and concrete. “Write cleaner function names” is not a carry-forward. “Every function in the payment module should be nameable in under five words” is.

What comes out of it

The lead keeps a short running note per engineer: what was reviewed, the carry-forward from each session, and whether it showed up in the next month’s code. This is the mentoring record — not a performance file.

What Good Code Looks Like

When you review your own work — before merge, in the code walk, or when helping a teammate — these are the five things that matter:

  1. Consistent. Someone new to this module feels at home. It follows the patterns already established here.
  2. Scoped. It does exactly what the definition doc said. No more, no less. Additions that weren’t in the doc belong in the next ticket.
  3. Instrumented. You can tell if it’s working from a dashboard. No SSH required to verify the feature is alive.
  4. Readable. A teammate can understand it in six months without you in the room. Variable names, function names, and structure do the explaining — not comments.
  5. Tested. The edge cases in the definition doc have tests. The happy path has a test. If you wouldn’t bet money the feature works without running it manually, write more tests.

If any of these are weak, fix it before you merge.

PR Format

Every PR must follow the format in Pull Requests. This is a standard, not a preference.

Title: type: concise description

Types: feat fix refactor perf infra docs test chore

Description must include: What Changed, Why, Before / After, Risks & Mitigation, Testing, Deployment Notes.

The format takes 10 minutes. A description without it costs the reviewer 10 minutes just to orient before reading a single line of code. That math compounds across every PR, every week.

The only exception is trivial changes — typo fixes, dependency patches — where a one-liner description is sufficient. If there is any behavior change, use the full template.

Related: Pull Requests, Build, Engineering Levels