The Development Checklist

Writing code is one part of software development. Your job is bigger: to create confidence that a change is correct, complete, tested, safe, maintainable and reviewable. Code that runs gives you one of those, partly.

A checklist is not bureaucracy. Pilots and surgeons use them because skilled people under time pressure skip steps they know perfectly well. Developers are no different. The checklist makes the invisible steps visible, so you skip none of them by accident and can explain the ones you skip on purpose.

Don’t just ask: does my code work? Ask six questions instead.

The cheapest bug to fix is the one you never write. Most rework does not come from bad code; it comes from good code that solves the wrong problem, or the right problem with a missing rule. Before you open the IDE, turn the ticket into something you could test.

Here is the ticket we will follow through all six gates:

Read it like an engineer

For every ticket, identify the same nine things. Where the ticket is silent, you have a question, not an assumption.

Functional requirement

A reviewer can move a pending application to Approved or Rejected.

Business rules

Only Pending can change. Approved and Rejected are final. Only reviewers decide.

Inputs

Application id, target status, the signed-in user.

Outputs

The updated application: status, decidedBy, decidedAt.

Error cases

404 unknown id, 400 unknown status, 409 invalid transition, 403 not a reviewer.

Permissions

REVIEWER role only. Applicants can read, not decide.

Existing behaviour

List filters, detail page, dashboard counts and the weekly report all read status.

Affected systems

Next.js UI, NestJS API, PostgreSQL, notification emails, reports.

Acceptance criteria

AC1 to AC6 below. If one cannot be tested, it is not finished.

Checklist

Development means understanding the existing flow before changing it. A requirement is usually a flow, not a file: the reviewer’s click travels through the UI, the API, a controller, a service and the database, and comes back. Find every stop before you edit any of them.

Then decide where the rule lives. If the “only pending can change” rule sits in a React component, any script with a token can bypass it. Put it in one place on the server, and let everything else call it.

Implement PATCH /applications/:id/status

1. 1

   Find the existing UI

   rg -n "ApplicationStatus" apps/web/src

2. 2

   Find the API endpoint

   rg -n "@Controller(\"applications\")" apps/api/src

3. 3

   Find the controller

   apps/api/src/applications/applications.controller.ts

4. 4

   Find the service

   apps/api/src/applications/applications.service.ts

5. 5

   Find the database model

   rg -n "model Application" apps/api/prisma/schema.prisma

6. 6

   Identify the business rule

   Write it down: PENDING to APPROVED or REJECTED, nothing else.

7. 7

   Implement the smallest safe change

   One rule function, one endpoint, two buttons.

8. 8

   Run the application

   pnpm dev

9. 9

   Verify the happy path by hand

   Approve one pending application, refresh, status is still Approved.

1export type ApplicationStatus = "PENDING" | "APPROVED" | "REJECTED";
2
3export const TRANSITIONS: Record<ApplicationStatus, ApplicationStatus[]> = {
4  PENDING: ["APPROVED", "REJECTED"],
5  APPROVED: [],
6  REJECTED: [],
7};
8
9export function assertTransition(from: ApplicationStatus, to: unknown, role: Role) {
10  if (role !== "REVIEWER") throw new ForbiddenException("only reviewers can change status");
11  if (!isStatus(to)) throw new BadRequestException(`unknown status "${String(to)}"`);
12  if (!TRANSITIONS[from].includes(to)) throw new ConflictException(`cannot move ${from} to ${to}`);
13  return to;
14}

1async changeStatus(id: string, to: unknown, user: AuthUser) {
2  const app = await this.prisma.application.findUnique({ where: { id } });
3  if (!app) throw new NotFoundException();
4
5  const next = assertTransition(app.status, to, user.role);
6
7  const { count } = await this.prisma.application.updateMany({
8    where: { id, status: app.status },
9    data: { status: next, decidedBy: user.id, decidedAt: new Date() },
10  });
11  if (count === 0) throw new ConflictException("application changed, reload and try again");
12
13  return this.prisma.application.findUniqueOrThrow({ where: { id } });
14}

1@UseGuards(JwtAuthGuard)
2@Patch(":id/status")
3changeStatus(
4  @Param("id", ParseUUIDPipe) id: string,
5  @Body() body: ChangeStatusDto,
6  @CurrentUser() user: AuthUser,
7) {
8  return this.applications.changeStatus(id, body.status, user);
9}
10
11export class ChangeStatusDto {
12  @IsIn(["APPROVED", "REJECTED"]) status!: "APPROVED" | "REJECTED";
13}

1export function StatusActions({ app }: { app: Application }) {
2  const qc = useQueryClient();
3  const change = useMutation({
4    mutationFn: (status: "APPROVED" | "REJECTED") =>
5      api.patch(`/applications/${app.id}/status`, { status }),
6    onSuccess: () => qc.invalidateQueries({ queryKey: ["applications"] }),
7  });
8
9  if (app.status !== "PENDING") return null;
10  return (
11    <div>
12      <button disabled={change.isPending} onClick={() => change.mutate("APPROVED")}>Approve</button>
13      <button disabled={change.isPending} onClick={() => change.mutate("REJECTED")}>Reject</button>
14      {change.isError && <p role="alert">{errorMessage(change.error)}</p>}
15    </div>
16  );
17}

Blast radius

Changing a status field is never only a status field. Before you write a line, list everything that reads it. That list is your blast radius, and in Gate 04 it becomes your regression scope.

A unit test proves one piece of your logic in isolation, in milliseconds. It is not a test of the feature. It will not tell you whether the button works or the email is sent. It tells you, precisely and repeatably, whether assertTransition says yes and no at the right moments.

The tests, with Vitest

Seven cases cover the rule: the two allowed moves, every way it must refuse, and the permission. Note that most of the tests are about “no”. That is where the bugs live.

1import { describe, expect, it } from "vitest";
2import { assertTransition } from "./application-status";
3
4describe("assertTransition", () => {
5  const allowed = [
6    ["PENDING", "APPROVED"],
7    ["PENDING", "REJECTED"],
8  ] as const;
9  it.each(allowed)("%s can move to %s", (from, to) => {
10    expect(assertTransition(from, to, "REVIEWER")).toBe(to);
11  });
12
13  const blocked = [
14    ["APPROVED", "PENDING"],
15    ["REJECTED", "APPROVED"],
16    ["PENDING", "ARCHIVED"],
17    ["PENDING", undefined],
18  ] as const;
19  it.each(blocked)("%s cannot move to %s", (from, to) => {
20    expect(() => assertTransition(from, to, "REVIEWER")).toThrow();
21  });
22
23  it("an applicant cannot change status", () => {
24    expect(() => assertTransition("PENDING", "APPROVED", "APPLICANT")).toThrow(ForbiddenException);
25  });
26});

A failure should read like a bug report: which rule, which input, what happened instead.

1$ pnpm vitest run application-status.spec.ts
2
3 FAIL  assertTransition > REJECTED cannot move to APPROVED
4AssertionError: expected [Function] to throw an error
5 ❯ application-status.spec.ts:21:56
6
7 Test Files  1 failed (1)
8      Tests  1 failed | 6 passed (7)

A feature can pass every unit test and still break a journey that worked yesterday. The search page might filter on a status value you renamed. The dashboard might count “everything not pending” as approved. Regression testing asks one question about everything around your change: does it still work?

What existing behaviour touches the thing I changed?

Two journeys with Playwright

1import { expect, test } from "@playwright/test";
2import { seedApplication, loginAs } from "./helpers";
3
4test("reviewer approves a pending application", { tag: "@p0" }, async ({ page, request }) => {
5  const app = await seedApplication(request, { status: "PENDING" });
6  await loginAs(page, "reviewer");
7
8  await page.goto("/applications");
9  await page.getByRole("link", { name: app.reference }).click();
10  await page.getByRole("button", { name: "Approve" }).click();
11  await expect(page.getByTestId("status")).toHaveText("Approved");
12
13  await page.reload();
14  await expect(page.getByTestId("status")).toHaveText("Approved");
15  await expect(page.getByRole("button", { name: "Approve" })).toHaveCount(0);
16});

1test("search, open and view an application", { tag: "@p0" }, async ({ page, request }) => {
2  const app = await seedApplication(request, { status: "APPROVED" });
3  await loginAs(page, "reviewer");
4
5  await page.goto("/applications");
6  await page.getByRole("searchbox").fill(app.reference);
7  await page.getByRole("link", { name: app.reference }).click();
8
9  await expect(page.getByRole("heading", { name: app.applicantName })).toBeVisible();
10  await expect(page.getByTestId("status")).toHaveText("Approved");
11});

Before anyone else sees your change, review it the way you would review a stranger’s. Your reviewer has less context than you and less time. Every debug log, stray file and copy-pasted branch they find is one they should not have had to find.

The tool is git diff. Read every line in it: files changed, lines changed, anything unintended, debug logs, commented-out code, duplicated logic, naming, architecture, security and performance.

Clearance is not “someone clicked Approve”. It means the change has passed every quality gate the team requires, and the evidence for each one exists where someone else can see it: in the PR, in CI, in the review thread.

CI turns most of those inputs into facts on a clean machine. A typical pipeline runs: lint, typecheck, unit tests, build, integration tests, e2e tests.

Clearance checklist

Now run the whole checklist once, end to end, on the Application Management System. Seventeen steps; each shows the action, why it matters, the command or code, the expected result, and a checklist.

Frontend

Next.js, TypeScript, Vitest, Playwright

Backend

NestJS, TypeScript, Vitest

Database

PostgreSQL