Software engineer promotion evidence checklist

A folder full of pull requests is not yet a promotion case.

It shows that work happened. It does not automatically show the scope, judgment, results, or sustained behavior your employer expects at the next level.

A polished document cannot fix missing alignment either. Start with the real ladder and discuss it with your manager while there is still time to change the work.

The compact checklist

Use this before building a longer packet:

• I have the current written expectations for the target level.
• My manager and I agree which expectations matter for this cycle.
• Each claim maps to a representative outcome, not an activity count.
• My contribution is distinct from the team's result.
• Metrics include a source, denominator, and time window where relevant.
• Qualitative claims have an observable artifact or specific feedback.
• The examples show a pattern across time, not one exceptional project.
• Gaps are labelled as missing evidence or missing experience—not hidden.
• Confidential details have been removed or generalized.
• The packet follows my employer's required process and format.

This checklist improves the evidence conversation. It cannot predict calibration, guarantee promotion, or remove an organizational constraint.

Start with the next-level expectations

Turn the ladder into a small evidence map. The example below is fictional.

Next-level expectation	Evidence available now	What remains unclear	Next conversation
Owns a service through follow-up	Led the build-cache rollout and post-launch review	Is one project enough to show consistency?	Ask manager which second example would be representative
Influences beyond the team	Cache pattern adopted by two product teams	What changed for those teams?	Request specific feedback from both owners
Develops other engineers	Paired with two service owners on rollout	Did they become independent?	Capture later rollouts they completed without help

Do not assign yourself a score. A private rubric can create false confidence when it does not match the people and process used in calibration.

Follow one project through the evidence map

Imagine an engineer led a shared build-cache rollout over two quarters. The project can support several expectations, but each claim needs different evidence.

Impact: what changed?

The engineer has a dashboard showing shorter CI times after adoption. That supports a delivery result only if the comparison uses similar repositories and a clear time window.

The stronger evidence may be narrower: two teams removed a repeated local workaround and kept the cache enabled after the trial.

Scope: what made the work difficult?

A system diagram can show the repositories and runners involved. It cannot prove judgment by itself.

The useful record explains the constraints: different build tools, security rules for shared artifacts, and a rollout that could not break release branches.

Judgment: which decisions were yours?

The design document records several alternatives. The promotion evidence should identify the tradeoff the engineer owned and what happened when early cache-hit data contradicted the first plan.

Changing course can be stronger evidence than following the original proposal perfectly.

Collaboration: who became more effective?

Meeting attendance proves little. Specific feedback from a team owner can show that the rollout removed a blocker or made adoption possible.

If another engineer later onboarded a repository without help, that is evidence of leverage. It is not evidence that the first engineer deserves sole credit for the adoption.

Consistency: did the behavior repeat?

One successful platform rollout may show strong work without proving sustained next-level performance.

Look for the same behavior elsewhere: another ambiguous problem clarified, another risk carried through follow-up, or a practice reused after the original project ended.

Consistency does not mean repeating the same project. It means the behavior is no longer an isolated moment.

Evidence is not the same as readiness

When a promotion map has a blank cell, diagnose the gap before polishing the document.

The work happened, but the evidence is missing

Recover the artifact, measurement, or feedback. Ask the person who observed the work while their example is still specific.

The behavior appeared only once

The gap is consistency. Find another useful work opportunity instead of stretching one project into several claims.

The scope has not been demonstrated

The gap is experience, not wording. Agree on work that can test the missing expectation and how progress will be observed.

The manager disagrees with the mapping

Resolve that disagreement early. A stronger packet will not compensate for two different definitions of the target level.

GitLab's public engineering career guidance distinguishes development toward a more senior role from documenting demonstrated performance for a promotion process.

Your employer may use a different model. Its ladder and process remain the source of truth.

What different artifacts can prove

Use artifacts as supporting material, not as the argument itself.

Artifact	It may help show	It does not prove alone
Dashboard or dated query	A measurable change over a defined window	That your work caused the whole result
Design or decision record	Constraints, alternatives, and a decision	That the decision produced impact
Rollout plan	Risk ownership and operational preparation	That follow-up happened
Incident review	Diagnosis, learning, and carried actions	Sustained behavior outside the incident
Peer or stakeholder feedback	An observed behavior and its effect	The full target-level case
Pull requests and commits	Where implementation happened	Value, scope, or leadership by volume
Runbook or template	A reusable mechanism	Adoption or another person's independence

The packet should connect the expectation, your contribution, the result, and the supporting artifacts. Do not make the reviewer reconstruct that chain.

Capture evidence monthly

Use a short record rather than rebuilding the year during review season.

Month:

Outcome or change:
- What became better, safer, faster, clearer, or more reliable?

My contribution:
- What decision, implementation, or coordination did I own?

Scope and tradeoffs:
- Which systems, teams, constraints, or alternatives mattered?

Evidence:
- Metric, release, incident, document, feedback, or adoption signal

Who benefited:
- User, team, stakeholder, or operational consequence

Level expectation:
- Which written expectation might this support?

Follow-up:
- What still needs to be measured, finished, or learned?

Keep links to the source artifacts. The monthly note is an index into the evidence, not a replacement for it.

Build the promotion document

Follow the company's required template first. When no format exists, use:

1. Target level and criteria: the exact expectations being discussed;
2. Executive summary: two or three patterns supported across the period;
3. Evidence by expectation: representative examples, not every task;
4. Collaboration and feedback: observations from people affected by the work;
5. Growth and consistency: feedback acted on and behavior repeated over time;
6. Artifact index: links to decisions, launches, measurements, and follow-up.

GitLab's public professional-development guidance recommends reviewing promotion material with a manager.

The review should identify either a supported case or the evidence still missing.

That conversation is more useful before the packet is finished.

Questions worth asking your manager

• Which expectations have I demonstrated consistently?
• Which example would be strongest in a calibration discussion, and why?
• Where is my evidence narrow or dependent on one project?
• Which gap is missing documentation, and which is missing experience?
• What work opportunity could demonstrate the remaining scope?
• Who else observed the work closely enough to give specific feedback?
• Is there an organizational or timing constraint separate from readiness?

Privacy and technical boundaries

Follow your employer's confidentiality and data-handling policies. Do not copy source code, secrets, credentials, private customer data, or internal artifacts into an unapproved system.

Workrail does not ingest source code or diffs. Standard sync does send Git metadata such as commit messages, branch names, changed file paths, timestamps, and aggregate change counts.

Optional GitHub context adds repository-scoped pull-request and issue titles, descriptions, labels, dates, links, and commit relationships.

Metadata can still be confidential, so inspect it and follow your employer's policy before connecting a work repository.

Inside Workrail, Reviews are scoped to the projects, dates, and employer questions you choose.

Evidence-backed draft claims remain linked to selected entries. User-provided context and suggested future goals use separate provenance, and you own the final wording.

Growth compares review themes only after you confirm a review result. Metrics shows whether captured entries support confirmed themes and contain concrete outcomes.

Entry activity is a memory aid, not an employee score. Workrail does not predict promotion readiness or replace manager calibration.

Build the record before the packet

If an employer prompt is unclear, the free review question interpreter can suggest a likely category and evidence outline.

The interpreter runs in your browser. It does not send the question text to Workrail or an AI model, and its suggestion is not a judgment about your employer's intent.

For answer wording, use the performance review examples. For one contribution, use the impact statement guide.

You can also inspect a fictional Workrail Impact Snapshot before building your own record.