1000 PRs Won't Prove You're Promotion Ready
The artifact pipeline for turning designs, reviews, launches, and incidents into evidence your manager can defend.
Get the guide to build your first AI agent directly in your inbox on newsletter signup:
Last week, it was the performance cycle at Amazon, and I was told everything went as planned.
I had shipped a lot of code during that period. But the conversation with my manager was barely about particular commits. It was about decisions, documents, reviews, launches, incidents, and outcomes that other people could remember and explain.
That distinction matters for a promotion.
A software engineer promotion artifact is durable evidence of engineering judgment or impact. Sure, a commit can be, but most times, commits are treated as bulk. You raised 100 commits in a month, which makes you the best in your team in terms of quantity. But you need to build a narrative around it, like how you argued tradeoffs in a design document, a test plan uncovering blockers, a launch checklist, an incident analysis, etc
The artifact lets another person understand what you changed, how you operated, and why the work was above your current level. It’s not just a number.
I learned this lesson when I got promoted earlier in my career. The flagship project I drove involved an escalation and my involvement in a meeting with my L7 and the other team’s L7. That was more important than the code I wrote, which was mostly disambiguated already. I am applying it again now as I work toward the next level, and I’m recommending the same for my mentees, so I thought I’d write about it.
If you wait until review season, you will remember some tickets. You will forget the nuances of the requirements you negotiated, the risks you found, or the team you unblocked
In this post, you’ll learn
What counts as a software engineer promotion artifact?
Which artifacts should be created across the software development lifecycle?
How to distinguish useful evidence from documentation theater?
How to turn raw work artifacts into a concise promotion case?
What counts as a software engineer promotion artifact?
A promotion artifact is something another person can inspect to verify your judgment, influence, ownership, or results.
A task says what you did. An artifact preserves why the work mattered.
For example:
Requirements meeting: The calendar event proves you attended. A PRD comment and decision record shows the requirement you changed, your reasoning, and the final agreement with the product manager. If you save that evidence proactively in a brag doc, it’ll be much easier to find later than if you have to dive through old documents and comments.
Technical design: Even if it’s a one-page recommendation with alternatives, reviewers, decisions changed, and dependencies unblocked. This document proves your engineering judgment.
Implementation: A list of PRs proves activity, and it’s great to monitor your numbers to be at the top of your team/org. But it’s easy to game the metric by doing low-value work that generates tons of PRs. You need to be able to reference a critical-path contribution tied to quality, adoption, reliability, or a delivery outcome.
Production incident: Joining a war room proves presence. A timeline, diagnosis, decision, and implemented mitigation show how you helped resolve the problem. Being the one who analyzes and solves the problem, even if someone else writes the code, is a good narrative to save.
Promotion systems tend to evaluate 1/ the impact of the work and 2/ the competencies demonstrated while delivering it.
Code can support both. It rarely explains both on its own. The promotion committee will not reconstruct your reasoning from a pull request six months later. Your manager needs a shorter, defensible story that connects the problem, your decision, the people affected, and the result.
As you grow in level, the promotion committee will include more people who are not working with you every day. They will evaluate evidence where they were not present. Would they be able to use your artifact to explain your contribution when you are not in the room?
If the answer is no, important context still lives in your head.
If you need to map your daily work against the expectations of the next level, this role-gap analysis gives you a concrete system:
Build promotion evidence across the entire software lifecycle
I recommend that my mentees generate artifacts throughout the whole software development lifecycle.
Besides generating those artifacts (links), write in your brag doc a small narrative about what the context was (situation and task you had to do), what you did (action), what the results were (results), and then index all the links to the artifacts as evidence. Artifacts are the data; the entry in your brag doc is the narrative.
Some people work in companies where the software engineers are just one gear in the machine. Requirements come from PM, designs from architects/tech-leads, implementation from developers, testing from QA, and release from devops/SRE. Where I work, an engineer is supposed to contribute to all of these, so for a promotion, you need evidence through all of these.
I created something that I call the Artifacts Pipeline, and it looks like this:
Requirements
Create:
PRD comments.
A decision record for important tradeoffs in requirements and proposals you made.
The weak version says, “Worked with Product to define requirements.”
The stronger version shows the original requirement, the edge case you found, the tradeoff discussed with the product manager, and the requirement that changed because of your input.
Both texts above could be talking about the same situation. But the second one is much stronger.
Design
Ideally, you’ll have some strong documents with a technical design. But even if the project is small, write at least a one-pager before implementation when the project contains a meaningful decision.
The document should include:
The problem and constraints.
Your recommendation.
Alternatives you rejected.
Dependencies and risks.
Open decisions and owners.
Then review it with people who need to know your work and can improve it. That can include your tech lead, an architecture group, dependency teams, operations partners, or the senior engineers who understand adjacent systems.
A big part of a promotion is making your work visible for the people who will promote you.
Remember that once you have done the work to write the document, each review is almost free; you just have to go to a meeting with that person to review it. Each review becomes a new artifact. Record who reviewed the proposal, what concerns they raised, and what changed afterward.
“Attended a design review” is weak evidence. “Identified an unhandled flow and changed the design before implementation” is much better.
Create the backlog
Break the project into workstreams and identify the critical path.
The useful artifacts are boring:
A list of workstreams and owners.
A dependency map.
A milestone calendar.
The risks and open questions that need to be resolved, with owners.
Try to own a core workstream. Core means another part of the project depends on it, or the launch cannot happen without it. Another way of working is always jumping into the workstream that becomes the critical path. I remember I was doing this a few years ago in my previous team. I owned a smaller piece but then I jumped into any work where one engineer was blocking another.
Shipping many tickets is just a number. Dividing the work and picking one critical-path item shows you can be trusted with a project..