The Promotion Packet Nobody Tells You to Build

You did the work. You know you did. The projects shipped, the incidents got resolved, the junior engineers got better. You’ve been operating at the next level for months - maybe longer.

And then the calibration meeting happens, and your manager comes back with “the committee felt you weren’t quite there yet.”

The gap is almost never talent. It’s almost always evidence.

Most engineers spend years doing promotion-worthy work and arrive at the conversation with nothing to show for it except their memory and their manager’s impression. Meanwhile, the people who get promoted aren’t necessarily doing more - they’re documenting better. They’ve been building a case, quietly, over months. By the time the promo cycle opens, their manager isn’t advocating for them. Their manager is presenting evidence that a decision has already been made.

That’s the system. Here’s how to build it.

What a Promotion Packet Actually Is

The promo doc is not the packet. The promo doc is the final deliverable - the 3-5 page document that goes to the committee. By the time you’re writing it, the work is supposed to be done.

The packet is everything that feeds into that document. Design docs, project postmortems, peer feedback, cross-team receipts, a running log of decisions you made and problems you solved. It’s the raw material. The promo doc is just the synthesis.

Here’s why this matters: most engineers start writing the promo doc when their manager says it’s time to start the promo doc. At that point, they’re reconstructing six to eighteen months of work from memory, Slack searches, and old Jira tickets. That’s not a promotion campaign. That’s archaeology.

The engineers who get through calibration cleanly have a different problem: they have too much material. They’re editing down, choosing which stories best demonstrate the behaviors the level requires. That’s a good problem to have.

A real promotion packet has four components:

1. The weekly log - raw, low-effort, captured in real time. Not polished. Just facts.

2. Design docs and technical artifacts - the actual evidence that you drove technical decisions, not just executed them.

3. Cross-team receipts - messages, emails, or mentions where other teams acknowledge your impact on their work.

4. The brag doc - structured summaries of your most significant contributions, updated monthly.

The promo doc is what you write when all four of these are full.

The Evidence Trail You Should Be Building Now

If you’re six months from a promotion conversation, you’re already behind. Start today anyway.

The weekly log

Every Friday, write down three to five things. What shipped. What you unblocked. What decision you made and why. What you taught someone. What problem you caught before it became an incident. Keep it in a private doc. Don’t polish it. Five minutes maximum.

This sounds trivial. It isn’t. The weekly log is what you’ll mine when you sit down to write the brag doc. Without it, you’ll forget the meeting in November where you talked three teams out of a bad architectural decision. You’ll forget the on-call incident in February where you caught the cascading failure before it hit users. These things happen, they matter, and they evaporate.

Design docs and technical artifacts

If you’re making significant technical decisions and there’s no written record, you don’t get credit for them. That’s the rule. Committees can’t evaluate what they can’t see.

For every significant project or technical decision: write the doc. Doesn’t need to be long. Needs to exist. It needs to show that you identified the problem, considered the options, recommended an approach, and drove it to execution. A design doc with your name on it that references a real decision is worth more than six months of verbal mentions in standups.

At Facebook, design docs were the primary evidence for Staff promotions. Not performance reviews. Not manager testimony. Docs, because docs prove you can think at scale, communicate to a broader audience, and drive alignment across teams you don’t own.

Cross-team receipts

Staff-level impact is cross-team impact. If everything you’re pointing to is work done within your immediate team, you’re building a Senior case, not a Staff case.

When another team uses something you built, asks you to review their design, or credits you in a postmortem - save it. Screenshot the Slack message. Forward the email. Write a sentence in your weekly log. These are receipts, and you’ll need them when someone in calibration asks “but is this just internal to their team?”

The Brag Doc Framework

Monthly. Not quarterly. Monthly.

Quarterly feels manageable and results in four rushed sessions per year where you try to remember what happened. Monthly takes twenty minutes and stays accurate.

What to track:

For each significant contribution, capture five things:

1. What was the situation? What was broken, missing, or suboptimal before you got involved?
2. What did you specifically do? Not your team - you. What decision did you make? What did you build or change?
3. What changed? Metrics if you have them. Qualitative if you don’t. Be specific.
4. Who else noticed? Names, teams, any public acknowledgment.
5. What level does this demonstrate? This is the part most people skip. Force yourself to map each contribution to the behaviors in your company’s leveling rubric.

What not to track:

Activity. “Participated in design reviews for five projects” is not a brag doc entry. It’s a calendar summary. The question is not what you showed up to - it’s what changed because you were there.

“Contributed to migration planning” tells a calibration committee nothing. “Identified a race condition in the proposed migration approach that would have caused data loss during the cutover window - the team adopted a different sequencing after my review, and the migration completed without incidents” tells them everything.

One of those is activity. The other is evidence.

Format:

Keep it simple. A table works. Three columns: project/area, what you did, impact/evidence. One row per significant contribution. Aim for five to ten entries per month. More than that and you’re padding. Fewer than that and you may not be operating at the right level yet - which is itself useful information.

How to Structure Impact Narratives

When you write the promo doc itself, you’ll turn brag doc entries into narratives. The structure that works:

Situation - What was the context? Why did this matter? How big was the problem? (One to two sentences. Don’t dwell here.)

What you saw - What did you notice that others weren’t addressing? What was the technical or organizational gap? This is where Staff-level thinking shows up: not just “here was a problem” but “here was a systemic problem that wasn’t on anyone’s radar.”

What you did - Specific actions. Decisions you made. Alignment you drove. Code you wrote. Not “led a team” but “proposed the approach, drove the three-team alignment meeting, wrote the design doc, reviewed the implementation plan.”

What changed - Results, in the most concrete terms you can manage. Latency numbers. User impact. Incident rate before and after. If you don’t have hard metrics, use scope: “all three downstream teams adopted the new pattern within 90 days.” That’s a real outcome.

Here’s the difference in practice:

Weak: “Led the cache invalidation project that improved performance across the platform.”

Strong: “Reduced cache invalidation latency by 40% (from 850ms to 510ms at p99), eliminating a class of timeout errors that had been generating 200+ user-visible errors per day for eight months. The fix required identifying that three separate teams were using different invalidation strategies that were amplifying each other - I drove the cross-team design review and proposed the unified approach that all three teams shipped within Q3.”

The weak version is what a Senior engineer writes. The strong version is what gets a Staff candidate through calibration. The difference isn’t that one person did more work. It’s that one person documented the specific nature of the problem, the cross-team complexity, and the concrete outcome.

I’ve sat in calibration rooms. The question that kills promotions is not “did they do good work?” It’s “can we articulate exactly what they did and why it mattered?” If your manager can’t answer that specifically, the committee defaults to “not quite there yet.”

The 6-Month Timeline

Months 1-2: Build the habit

Start the weekly log. Start the monthly brag doc. Don’t worry about quality yet - just build the practice. Review your company’s leveling rubric and identify the two or three behaviors where you have the clearest evidence and the two or three where you’re thinnest.

The thin areas are your roadmap for the next four months.

Months 3-4: Close the gaps

You know where your evidence is weak. Go get the evidence. If you’re thin on cross-team impact, find the project where you can genuinely contribute to another team’s work - not to pad your doc, but because that’s where Staff-level engineers operate. If you’re thin on technical leadership, write the design docs you’ve been putting off.

Talk to your manager during this window. Not “am I on track for a promotion?” but “here’s what I’ve been building, here’s where I think I’m strong, here’s where I’m still developing - does this match what the committee will see?” This conversation surfaces misalignments while there’s still time to fix them.

Month 5: Draft the promo doc

Don’t wait for your manager to say it’s time. Draft it yourself. Use the brag doc as your source material. Get your manager’s feedback on the draft - their reaction tells you everything about where the gaps are.

A manager who reads your draft and says “this looks strong, let me add context on X” is a different conversation than a manager who says “I’m not sure the committee will read this the way you intend.” You want to have either of those conversations in month five, not month six.

Month 6: Ready

Ready means: your manager has the narrative. The doc is finalized. You have specific examples for every behavior the rubric requires. You know which stories you’d tell in a skip-level conversation if asked to defend the case.

Ready does not mean you’ve done enough. It means the evidence exists and it’s organized.

Common Mistakes That Kill Promotions

Reconstructing from memory

You cannot accurately reconstruct six months of technical decisions from memory. You will forget the things that mattered most and remember the things that felt dramatic. Your brag doc exists so you don’t have to rely on memory. Start it now, not when you decide to go for a promotion.

Relying on your manager to track it

Your manager has twelve other direct reports. They’re in their own performance cycle. They want you to get promoted and they will advocate for you - but they cannot be the source of truth for your contributions. That’s your job. Give them the material. Don’t make them find it.

At Facebook, the engineers who got through calibration cleanly were the ones whose managers came in with structured notes: “Here’s the impact on the infrastructure reliability story, here’s the cross-team evidence, here’s the specific technical decision that demonstrates Staff-level thinking.” The managers who struggled were the ones saying “they’ve been doing great work, I know they’re ready” without specifics. The committee can’t act on impressions. They need evidence.

Confusing activity with impact

Attending meetings is not impact. Reviewing code is not impact unless the review changed something important. Being busy is not impact.

The test: if you removed this contribution, would anything have been measurably worse? If yes, that’s impact. If no - or if you can’t answer - it’s probably activity.

Collecting evidence without connecting it to the level

Your company has a rubric. It lists specific behaviors for each level. Your evidence needs to map to those behaviors, not just demonstrate competence in general.

If the Staff rubric says “drives technical direction across multiple teams,” and every example in your brag doc is within your own team, you have a framing problem. The work might be great. But it doesn’t answer the question the committee is actually asking.

Starting too late

Two months before the promo cycle is too late. By then you’re documenting history, not building evidence. The work needs to exist. The documentation needs to capture it accurately. The gaps need to be closed. None of that happens in two months.

Start the weekly log now. Even if you’re three years from a promotion conversation. Especially if you’re three years from a promotion conversation.

What This Looks Like When It Works

The engineers I’ve worked with who get through promotion cycles cleanly share one characteristic: they’ve been treating their career like a project. Not anxiously, not obsessively - just systematically. They have a doc that tracks their contributions. They have conversations with their manager about the level requirements. They know where their evidence is strong and where it’s thin.

They don’t arrive at the promo conversation hoping it worked out. They arrive having already built the case.

That’s not luck. That’s a system.

The work you’ve been doing deserves to be seen. Build the system that makes it visible.

If you want help applying this to your specific situation - your company, your rubric, your gaps - schedule a consultation. I’ve sat in those calibration rooms and I know what moves committees. We can work through exactly where your case is strong and where it needs work.

If you’d rather start on your own, the SWE Interview System covers the full evidence-building and narrative process in a self-guided format.