Initiate onboarding flow

Terydin places people with client companies. Onboarding ran as a five-step wizard: candidate summary, Terydin onboarding tasks, client onboarding tasks, timeline, confirm. Two task steps, hardcoded in that order, one template chosen from a dropdown on each side.

Day 1 verification is an in-person identity check against a Ghana Card, carried out at the client site once the employee physically turns up. It sat inside Terydin onboarding as mandatory step five, described in the product's own words as Method: In-person (Accra). Not yet scheduled.

Client onboarding waited on Terydin onboarding. The step said so plainly: these tasks will be locked until Terydin system steps and template tasks are complete. So the phase that had to finish first contained a task that could not happen until after the employee started, and the phase that would follow was locked behind it.

Nobody had to be told there was a deadlock. The wizard specified one, in four separate places, in copy written by the product itself.

The work here was not interface work, it was dependency work. The existing wizard was coherent and well built, and it made one reasonable assumption, that onboarding is Terydin's part followed by the client's part. Everything that went wrong follows from that assumption meeting an in-person check at a client site.

So the pre-work was mapping the phases and their prerequisites and walking real placements through them, looking for the cases that break. That is what established the deadlock as structural rather than incidental: the sequence cannot be fixed by moving a task, because the step structure itself only has two places to put one.

Which led to the conclusion the whole redesign rests on. No fixed order survives every placement, so the target stopped being the right sequence and became a way for operations to express whatever sequence a placement actually needs.

The obvious fix is to move Day 1 verification to the end of the sequence. That fix is not wrong so much as insufficient, because it swaps one order baked into the product for a different order baked into the product. The next placement that does not fit the new order has exactly as little recourse as this one had.

So the sequence stopped being something the product knows and became something operations declares. What a phase waits on is an input now, set per placement, and it is allowed to be nothing at all.

Order and dependency are separate concerns, and both are editable. Phases are numbered and dragged into position independently of what they wait on, which means Day 1 sitting third is an arrangement rather than a rule. It can be dragged to second, and the phases after it can have their prerequisites cleared so nothing waits on it. Only the first phase is fixed, because there is nothing ahead of it to wait on.

Timing follows the same principle. A due date per phase in the timeline step, and due dates per task in the editor behind each phase, rather than one date covering the whole onboarding.

Templates are snapshotted when they are assigned, so editing a template later never disturbs somebody already halfway through their onboarding.

Configurability was bought with consistency. When operations assembles a stack per person, two people hired into the same role on the same day can end up onboarded differently, and there is no longer a single template to point at and say this is how we do it. That is a real cost and it was accepted deliberately, because a fixed template that deadlocks is worse than a flexible one that drifts.

It also moved work onto the onboarding specialist. The old flow asked them to pick two templates from two dropdowns. The new one asks them to make decisions per person, which is more thinking at the moment of assignment in exchange for placements that actually progress.

And the design it replaced was not careless. It was a coherent wizard built on an assumption that holds for most onboarding, that the employer's part comes first and the client's part follows. It only fails where a task needs the employee physically present at the client, which is exactly Terydin's model and nobody else's.

The outcome is not that Day 1 verification moved. It is that nothing in the sequence has a fixed position any more. The default stack runs Terydin pre-onboarding, then client assignment, then Day 1, which is right for an ordinary placement and is why the deadlock is gone. But a placement that needs Day 1 early, or needs two phases running with nothing between them, is now a configuration an operator makes rather than a change request an engineer takes. Placements move.

The assign flow drops from five steps to four, because two fixed task steps collapse into one configurable stack. On an employee's detail view the phases read in the order they were given, so an operations lead can see that Terydin pre-onboarding is complete, client assignment is in progress, and Day 1 is waiting behind it.

A pull request is raised with the full prototype and detailed documentation covering the entire feature. Every phase, every state, every edge case is documented so a developer picking it up has no ambiguity about what was built or why.

The docs spell out limitations, what the prototype fakes versus what comes from real endpoints, and where the boundaries are between frontend state and backend responsibility. Open questions are listed plainly rather than guessed at, and next steps are scoped so the backend team knows exactly what to build first.

The interesting part of this one was not the fix, it was proving the fix was right. I had the deadlock from having lived it, so I went back to the shipped flow and walked it step by step until the product said it out loud: Day 1 mandatory inside Terydin onboarding, client tasks locked behind that phase, and a timeline asking for completion three business days before the start date. Evidence beats recollection, and here the evidence was sitting in the interface the whole time.

That is the habit rather than a one-off. A comment in the templates file credits a meeting with moving onboarding to a modular set of phase templates, which describes the shape of the solution and says nothing about why it was needed. Taking it as the rationale is the easy mistake, and it hides the actual cause. Once the real reason was pinned down I wrote it into the project record, so the next person to open that file gets the deadlock rather than the comment.