What an engineering partner delivers in week one

Week one is a diagnostic, not a ramp

The first week of an outside engineering engagement usually disappears into things nobody can point at afterward. Accounts get requested. Repositories get cloned and skimmed. Somebody sets up a recurring meeting and writes a document called Onboarding Notes. On Friday the honest answer to "what did we get this week" is a shrug and a promise about next week, and everyone accepts it because ramping up is understood to be free. It is not free. You paid for it, and you paid at the same rate you will pay in month four.

The reason to care is not the money. It is that almost everything an outside team will get wrong in month three is already visible in your code, your migrations and your dashboards during the first five days, provided somebody looks with the intent to write down what they find. A team that spends week one absorbing context and asking to be brought up to speed has thrown away the only week in which they are still capable of noticing what your own engineers stopped seeing two years ago. Fresh eyes have a shelf life measured in days.

So we run week one as a fixed piece of work with named artifacts and a Friday deadline. If you are evaluating anyone to write code for you, this doubles as the standard to hold them to, and it is a fair one. Nothing below requires domain expertise you have to transfer first. It requires an engineer who reads carefully and writes things down.

The Friday test

There is one question worth asking at the end of the first week. If this team vanished over the weekend, what would you still have? Five things should survive that question.

A running environment, reproduced by someone who had never seen it, with the setup time measured. Not a screenshot. A corrected setup document and a number in hours.

A system map drawn from the code and the live traffic, with the places it disagrees with your official architecture diagram called out explicitly.

A production baseline: latency percentiles by route, error rates, queue depth and age, the ten most expensive database queries, deploy frequency, all read-only, all timestamped.

A ranked risk register in which every single entry cites evidence you can open yourself in under a minute.

One merged, reviewed, deployed change in your main branch.

Four of those five are documents, and that is on purpose. The one that is code exists mostly to prove the pipeline works. Together they cost about a week of one senior engineer, and they are worth having even if the engagement ends there, which is the only real test of whether a deliverable is a deliverable.

Note what is missing from that budget. There is no line for stakeholder interviews as a category of work. We will talk to two or three people who know where the difficult parts are, for about ninety minutes each, and those conversations come out of the reading and measurement lines. A first week built around a tour of the org chart produces a document about the org chart.

Day zero: the access list goes out before the contract is signed

The single most reliable way to lose the first week is provisioning. It is serial, it runs through people who have other jobs, and every item has a dependency in front of it. An identity account has to exist before group membership, which has to exist before tool access, which has to exist before anyone can see the log that answers the question. Two days lost at the front of that chain is not two days, it is the week.

So the list goes out the moment there is a verbal yes, well before signature, because none of it requires a signed agreement to begin moving through your internal queues. Here is what we ask for.

• Read access to every repository the system touches, including infrastructure code, deploy configuration and the scripts nobody considers part of the product
• An identity-provider account in whatever gates your tooling, plus the group memberships that actually grant access
• A read replica, an anonymized dump, or a written path to representative data
• Read-only cloud credentials, plus billing read if cost is anywhere in scope
• Read access to observability: application performance monitoring, the log store, the error tracker, dashboards, alert definitions and the on-call rotation
• The issue tracker, and separately the incident record, which is the more useful of the two
• A channel in the chat tool your engineers actually use
• A named person who can unblock access, and a named backup for when that person is out

The data item is where most engagements quietly fail, because the answer is often "just use staging" and staging holds two hundred rows seeded in 2023 by someone who has since left. A system that behaves correctly on two hundred rows tells you nothing about a system serving forty million. If real data cannot leave your boundary, say so on day zero and we work inside your environment instead. That is a normal arrangement and it changes the plan, not the outcome. What is expensive is discovering it on Wednesday.

Day one and two: clone to running, and put a clock on it

The first technical task is not reading code. It is getting the system to run, following your written setup instructions literally, without asking anyone anything. That constraint is the whole point. The moment an engineer asks a colleague which environment variable is missing, the measurement is destroyed and the document stays broken for the next hire.

We record every place the instructions are wrong, with the error text, and we keep a timestamp. The failures repeat across companies with unusual consistency. A container image that no longer builds because a base image moved underneath a floating tag. A pinned dependency that was yanked from the registry. A migration chain that runs fine against a snapshot and fails from an empty database because migration nineteen assumes a row that migration twelve stopped creating. A service that silently requires network access nobody documented. Seed data that exists on one laptop. A build step that works only on the architecture the original author happened to use.

We timebox this at one working day. If it is not running by then, we stop and write down exactly where it broke, and that becomes the first entry in the risk register rather than a private struggle that consumes Tuesday and Wednesday. The number itself is worth having on its own. If clone-to-running is under two hours, your team can onboard an engineer in a week and you should tell candidates that. If it is three days, every hire costs three days of two people, and the fix is usually a day of work that nobody has ever been assigned because the pain is distributed across people who each feel it once.

The corrected setup document is a pull request that same day. It is a small change, it is real, and it is the first evidence that the delivery path works end to end.

Day two and three: read the system as it is, not as it is drawn

Now the code. Not all of it, and not in file order. There are five reads that produce most of the value, and together they take about a day.

The commit history as a heat map. Which files change most often, and who changes them. A short script over git log gives you change frequency per path in a minute, and the top decile is where your product is genuinely being built. That is where the tests belong, and it is usually not where they are. The same query grouped by author gives you a bus factor per subsystem, and a subsystem where one person wrote most of the commits and left in March is a risk with a name and a date attached.

The migration history. Read the migrations in order, oldest first. This is the honest version of your domain model, including the column added in a hurry during an incident, the field that is nullable because a backfill was started and never finished, the table nobody has written to since 2024, and the moment somebody gave up on a foreign key. An entity relationship diagram tells you what was intended. The migration folder tells you what happened.

Every outbound call. Grep for the HTTP clients and vendor SDKs, list every third party the system talks to synchronously, and check which of those calls have timeouts, retries and circuit breakers. A synchronous call with no timeout, sitting inside a request path, is the most common latent outage we find. It costs nothing while the vendor is healthy and takes the whole service down the first time that vendor gets slow rather than failing outright. Slow is worse than down, because slow fills your connection pool.

The configuration surface. What is set by environment, what is hardcoded, what differs between staging and production, and which secrets are in the deploy configuration versus a secret manager. Configuration drift between environments explains a large share of the bugs that only reproduce in production.

One request, end to end. Pick a genuinely important user action and trace it from the edge through every service, queue and table it touches, and back. Then put that beside the architecture diagram somebody drew.

They always disagree somewhere. There is a service on the diagram that was decommissioned and a direct database read that bypasses the API it is supposed to go through. There is a queue in the picture and a synchronous call in the code. Every one of those gaps is a place where an engineer will reason correctly from the documentation and be wrong, and they compound, because each gap makes the next reader trust the diagram slightly less until nobody uses it and it stops being maintained.

The read-only production pull

In parallel with reading, we take a baseline of the running system. Everything here is read-only and none of it changes behavior. We take it in week one specifically because it will be different later, and a baseline taken after work has begun is not a baseline. It is a defense.

Signal	Where it comes from	What a bad answer looks like
Latency by route, p50 / p95 / p99	Application performance monitoring, or access logs with percentiles computed directly	A single global average. Averages hide the tail, and the tail is what users describe when they say the product feels slow
Traffic and total time by route	Same source, sorted by total time rather than request count	Nobody can name the endpoint that consumes the most database time. It is rarely the one people assume
Most expensive queries	pg_stat_statements ordered by total execution time, then EXPLAIN (ANALYZE, BUFFERS) on the top few	The extension is not enabled, which is itself the finding: nobody has ever looked at query cost with data
Error volume and top errors	The error tracker, grouped and sorted by count over 30 days	Thousands of unresolved issues and no triage. An error tracker nobody reads is an unlit dashboard
Queue depth, oldest message age, retries, dead letters	Broker or worker metrics, plus the dead-letter queue itself	Depth is monitored and age is not. Depth can sit flat at zero while the oldest item is six hours old and a whole class of jobs is stuck
Deploy frequency, lead time, rollback time	CI history and the deploy log, counted rather than recalled	"We deploy when it is ready." Deploy cadence and time to roll back predict more about the next quarter than any architecture decision
Connections, pool size, cache hit ratio, longest transaction	pg_stat_activity, pg_stat_database, the pooler's own metrics	Connection count sitting near the ceiling with no pooler configured, or a long-running idle transaction nobody has noticed holding locks

None of that requires deep knowledge of your business. All of it requires access, which is why access is day zero. And each row has a version of "we do not have that" as the answer, which is a finding in its own right and often the most important one of the week. A system with no percentile latency data is not necessarily slow. It is a system where nobody can tell whether a change made things worse, and that constraint shapes everything that comes next.

The first merged change, by Friday

By the end of the first week there is a commit in your main branch with our name on it, reviewed by one of your engineers, through CI, deployed. The change itself is small on purpose. The point is the path.

Every step in that path fails somewhere. CI that passes only on a self-hosted runner nobody documented. A branch protection rule requiring review from a group whose only active member is on leave, with no backup approver configured. A test suite that is green locally and flaky in CI because it depends on wall-clock time. A deploy that claims to be automated and has a manual console step in the middle. A staging environment that has not matched production since a migration in the spring. Finding those in week one on a two-line change is cheap. Finding them in week six on a change that matters is not, because by then the change is urgent and the pipeline problem is in the way.

Good candidates for the first change: the setup document correction from Monday, a missing timeout on an outbound call, an index on a column the slow query log already named, a test that pins behavior somebody described verbally in a meeting, or a fix for a high-volume error in the tracker with an obvious cause. What it is not is a refactor. Nobody has earned the right to rearrange somebody else's code in week one, and a partner who opens with a large structural change is telling you they are more interested in their own preferences than in your system.

What lands on your desk, day by day

Day	Work	Artifact that lands
Day 0 Before the start date	Access list issued, security review opened, data path agreed in writing	The access request itself, with a named owner and a date beside every line
Day 1	Clone to running against the written instructions, unassisted and timed	Corrected setup document as a pull request, plus the clone-to-running number in hours
Day 2	Commit heat map, migration read, outbound-call inventory, configuration surface	First draft of the system map, with open questions listed rather than guessed
Day 3	Read-only production pull, one real user action traced end to end, one reported defect reproduced	The measured baseline, timestamped, with the queries and dashboards used to produce it
Day 4	Two or three focused conversations with the engineers who know the difficult parts, then reconciliation against what the code says	System map finalized, with every place it contradicts the official diagram marked
Day 5	First change merged and deployed, register ranked, scope reconciled against what the code actually requires	Ranked risk register, the merged change, and a written scope note including anything that changed

That sequence is deliberate in one respect worth naming. The conversations with your engineers happen on day four, after we have read the code and measured the system, not on day one. Asking an engineer how a system works before you have read it produces their mental model, which is usually a year old in the places that have changed most. Asking after you have read it produces something better: they correct you, and the corrections are precise, fast and about the parts that genuinely matter. It also respects their time. Ninety minutes with a prepared reader beats four hours of general orientation.

The risk register, and the rule that keeps it honest

The register is the artifact clients keep longest, and it is worthless without one rule. Every entry cites evidence you can open in under a minute: a file path and line number, a query plan, a dashboard with a fixed time range, a log line with a timestamp, an incident reference. No entry says the code quality is poor. No entry says the architecture needs modernization. Those are opinions dressed as findings, and they are how consulting reports become shelf documents.

Two columns matter more than the score. Cost of doing nothing, in engineering days per quarter, is what converts a technical concern into something a budget owner can act on. A flaky test suite that costs your team four re-runs a day is not a code-hygiene issue, it is a recurring expense with a number, and the number is what gets it funded. Cost to fix, stated as a range with the uncertainty visible, is what stops the register from becoming a wish list.

The register also carries a section headed with what we do not know yet, and that section is not short after five days. It should name the specific measurement or experiment that would resolve each item. The fastest way for a partner to lose credibility in week three is to have been confident in week one about something they had not measured, and the cheapest way to keep it is to be explicit about the edges of what a week can establish.

The scope revision nobody wants to write

The most valuable output of a first week is often the sentence a partner is least motivated to write: the work you scoped is not the work that needs doing.

It takes a few recognizable shapes. You hired someone to make an API faster, and the latency is dominated by a third-party call the team does not own, so the real work is caching and a fallback path rather than query optimization. You hired someone to build a feature, and the data model cannot express it without a migration larger than the feature, so the sequencing has to change. You hired someone to build a model, and the labels do not exist in usable form, so the first month is a labeling process and a baseline rather than model work. You hired someone to scale a service, and the service is fine while the database sits at ninety percent connection utilization behind it.

We send that note on Friday of week one, in writing, with the evidence attached and two or three options priced. Sometimes the answer is that the original scope stands and the finding goes in the register for later. Sometimes it means a smaller engagement than the one that was signed, which is an uncomfortable email to send and the correct one. A first week that cannot produce that email is not a diagnostic, it is a formality.

What week one is not

• A ramp. Getting up to speed is a state, not a deliverable, and it is not something you should be invoiced for
• A tour of the organization. Eight stakeholder conversations and no code produces a document about the organization
• A rewrite recommendation. Anybody proposing a rewrite after five days has not read enough to know what the current system handles that they have not thought of
• A tooling installation project. Introducing a new framework, linter or CI system before understanding the existing one is a preference, not a finding
• A demo. Something impressive built in a sandbox that touches none of your real constraints is theater
• Backlog grooming. Reordering tickets is work your own team can do and it teaches an outsider nothing
• Silence until a readout. Findings go out the day they are found. A partner who saves them for a formal presentation is optimizing the presentation

What we need from you

Half of what makes a first week work is on your side, and none of it is expensive. It just has to happen before the start date rather than during it.

• A named unblocker with a named backup, empowered to approve access without a committee
• Access requested on day zero, in parallel, not in sequence behind a signature
• One real dataset, or a written decision that work happens inside your environment instead
• The incident record for the last year, however informal, including the ones nobody wrote up
• Ninety minutes each from the two engineers who know where the difficult parts are, on day four, not day one
• A written statement of the decision this engagement is meant to unblock, in one paragraph
• Explicit permission to report that the scope is wrong, so nobody has to be brave to say it

That last item does more work than it looks like. Engineering partners are commercially incentivized to agree with the scope that was signed, and most of them will, right up until the point where the problem becomes undeniable and expensive. Saying out loud at kickoff that you want to hear it early removes the incentive, and it costs you nothing.

How this sets up day 30

A diagnostic week is only worth running if the next three weeks use it. The pattern we run afterward is the same shape every time, and it exists so that a decision point arrives at day 30 with evidence behind it rather than a request for more time.

Step three is the one people skip and the one that decides whether anybody believes the result. If you optimize something before you can measure it, you will finish with an improvement you cannot demonstrate and an argument about whether it happened. Instrument first, even when it delays the visible work by two days, because the two days buy you a number that ends the argument permanently.

The day-30 decision point is real, not ceremonial. Continuing should be a choice made against the register and the measured result, and a partner who has arranged the first month so that stopping is easy is a partner who expects the evidence to argue for continuing.

Bottom line

Week one is the cheapest week to find out what is true and the most expensive week to waste, because it is the only one in which the outside team can still see your system clearly. Hold it to five artifacts: a reproducible environment with the setup time measured, a system map drawn from the code, a read-only production baseline, a risk register where every line cites evidence, and one merged change. Send the access list on day zero and start the security review beside the contract. Ask on Friday what you would keep if the team disappeared, and expect a real answer.

We run first weeks this way for companies bringing in outside engineering for the first time and for teams that have been burned by an engagement that never quite started. The deliverable is the same either way, and it belongs to you whether or not anything follows it.

Frequently asked questions