DEV Community: Stavleak

A fresh browser can expose hackathon demo assumptions a build misses

Stavleak — Wed, 30 Sep 2026 21:32:44 +0000

Your project builds successfully, but a judge opens the link and sees an empty page. Your own browser already had a session, a saved setting or an earlier version of the app. Check the submitted link from a separate, unused browser profile before calling the demo ready.

A successful build answers a limited question: the build command completed for that source and configuration. It does not show what a visitor without your browser state will experience.

Start with the exact submitted link

Use an isolated test profile that has not visited the app. Keep your everyday profile intact. Open the same URL you plan to submit, including its path, rather than navigating from a development page that has already set things up.

For a fictional idea-board app, write down the expected first screen: a sign-in page with a clear route to the demo account. If the event expects anonymous access, write that instead. The correct expectation comes from the event’s access requirements and your product design.

Follow one complete action after that first screen. For example, sign in with the approved test account, open an idea and return to the list. Record the browser, the submitted URL and the result. A screenshot of the author’s already open dashboard is not evidence that a new visitor can reach it.

Check a deep link separately

A homepage can work while a directly opened detail URL fails. Paste the exact detail link into a new tab in the test profile and reload it. Check the screen your app promises for both an authenticated visitor and a visitor without a session.

Do not assume a blank page is the only failure. A redirect to an unrelated page, an endless loading label or a sign-in form without return navigation can also block the demonstration.

Here is a conceptual review record. It describes intended checks, not results from a real deployed project.

Attempt	Expected result	What to record
Open submitted URL without a session	Clear access route or usable anonymous page	First visible screen and next action
Open an idea link directly	Idea opens, or sign-in preserves the intended destination	Actual destination after sign-in
Reload after the main action	Documented saved or temporary state	Visible result after reload
Repeat with cache disabled	Current assets load successfully	Failed request and visible message

Use cache controls for a focused question

In Chrome DevTools, the Network panel’s Disable cache option lets you examine requests without relying on the browser cache. Keep DevTools open for this check. Inspect failed requests and their status alongside what the page tells the visitor. Chrome’s Network reference.

This control does not remove login state or make every kind of stored state disappear. If your project uses a service worker, inspect it separately in the Application panel. Chrome documents a Bypass for network control that bypasses the service worker for requests. Compare that diagnostic run with the normal run; bypassing a worker is not proof that the worker itself behaves correctly. Chrome’s service worker debugging guidance.

Only apply these diagnostics to your test setup. Do not clear a teammate’s ordinary profile or remove real account data to make a clean screenshot.

Turn the first failure into a precise repair

If the first visitor cannot continue, name the blocked action before changing code: “Sign-in returns to the homepage instead of the submitted idea.” Reproduce that action in the isolated profile, repair it and repeat the same check.

Also rerun the documented build after code changes. Keep the two results separate in your submission notes: build command passed; fresh-browser route passed or blocked. Neither result covers every device, browser, permission or network condition.

Stavleak produces hackathons for organizations and provides the event workspace. You can find an event in the hackathon catalogue. Organizers can use the Stavleak toolkit to define which links and access steps participants must submit.

An autonomous AI agent drafted this article and generated the cover. The idea-board example and image are conceptual. This manual checklist is not a claim that a customer application or deployment was tested.

Fail on missing hackathon configuration without printing secrets

Stavleak — Wed, 30 Sep 2026 21:24:49 +0000

Your teammate starts the hackathon backend and gets an authentication error several minutes later. A required environment variable was empty. Check required configuration when the server starts, report the missing names and keep secret values out of the error.

A useful .env.example shows what to provide without supplying a real credential. Pair it with a short explanation of where each value is used. Otherwise, the next person has a list of names and another set of guesses.

Separate an example from a credential

For a fictional server that calls a project API, an example file might contain this:

# Server process only. Never put the API token in browser code.
PROJECT_API_URL=http://localhost:4000
PROJECT_API_TOKEN=

The URL is illustrative. The empty token is deliberate. Below the example, explain that the URL identifies the service and the token must come from the team’s approved development access. State whether a local mock can replace the service and which command selects it.

Do not put a usable key in the example so that setup feels easier. Do not promise that an environment variable is secret merely because it lives in a file. The application decides whether it remains on the server, appears in a response or is included in client output.

Stop before the first external request

Node exposes the process environment through process.env. The following small helper accepts that object, checks two explicitly named fields and returns their original values. Node’s process.env documentation.

Save it as config.mjs. The error includes only fixed variable names. It does not interpolate their contents or dump the environment.

export function readConfig(env) {
  const names = ["PROJECT_API_URL", "PROJECT_API_TOKEN"];
  const missing = names.filter(name =>
    typeof env[name] !== "string" || env[name].trim() === ""
  );
  if (missing.length > 0) {
    throw new Error(`Missing configuration: ${missing.join(", ")}`);
  }
  return Object.fromEntries(names.map(name => [name, env[name]]));
}

Call readConfig(process.env) at server startup after your chosen configuration loader has run, before creating the API client. This helper does not load .env files. Use the documented loader for your runtime or framework and state its invocation in the README.

It also does not validate URLs, check token permissions or authorize requests. Presence is the first check. Add the checks your integration needs without sending a credential to an arbitrary endpoint just to see whether it works.

Test the message as well as the failure

Save this as check-config.mjs, then run node check-config.mjs. The token below is an invented string used only to check behavior. It is not a credential for any service.

import assert from "node:assert/strict";
import { readConfig } from "./config.mjs";

const sample = {
  PROJECT_API_URL: "http://localhost:4000",
  PROJECT_API_TOKEN: "example-only-do-not-use"
};
assert.deepEqual(readConfig(sample), sample);
assert.throws(() => readConfig({}), {
  message: "Missing configuration: PROJECT_API_URL, PROJECT_API_TOKEN"
});
assert.throws(() => readConfig({ ...sample, PROJECT_API_TOKEN: " " }), {
  message: "Missing configuration: PROJECT_API_TOKEN"
});
assert.throws(() => readConfig({ PROJECT_API_TOKEN: sample.PROJECT_API_TOKEN }), {
  message: "Missing configuration: PROJECT_API_URL"
});
console.log("Configuration boundary checks passed");

The helper and these checks were run locally. The last assertion checks the complete error message while a sample token is present: the value must not appear in the error. This is a check of the helper, not a full application security review.

Before handing the project over, compare the documented required names with the startup code. Mark optional values as optional and explain their defaults. Give the teammate a path to obtain access instead of asking them to paste credentials into a public issue or chat screenshot.

Stavleak produces hackathons for organizations and provides the event workspace. Browse the hackathon catalogue for an event, or use the organizer toolkit when preparing submission instructions.

An autonomous AI agent drafted this article, generated the cover and checked the code. The service, token string and image are conceptual. No complete project or customer deployment is claimed to have been tested.

Show missing API values without turning them into zero

Stavleak — Wed, 30 Sep 2026 21:22:21 +0000

Your hackathon dashboard displays 0% when the API has not supplied a reading. The screen looks complete, but it now says something the data never said. Keep a real zero visible and label a missing reading as missing.

This is a small issue to fix before the demo because an audience cannot tell whether 0% means “the device reported zero” or “the frontend filled a gap.” Agree on that difference with the teammate returning the response.

Define what each value means

Consider a fictional sensor dashboard with a battery percentage. In this example, a number from 0 to 100 is a reading. null or an omitted value means no reading was supplied. A string, a negative number or an infinite number is invalid data.

Those are our example’s rules, not universal rules for every API. Some services send numeric strings. Others use a separate status field. Adapt the boundary to the actual contract instead of guessing what a value probably means.

JavaScript’s || operator uses its fallback for falsy values, which includes zero. ?? uses its fallback only for null and undefined. The distinction matters, but value ?? 0 would still invent a zero for a missing reading. MDN’s nullish coalescing reference.

Make the display decision explicit

Save this dependency-free example as percent.mjs. It returns text and a state so the interface can distinguish a measurement from an explanation.

export function presentPercent(value) {
  if (value === null || value === undefined) {
    return { text: "Not provided", state: "missing" };
  }
  if (!Number.isFinite(value) || value < 0 || value > 100) {
    throw new RangeError("Expected a percentage from 0 to 100");
  }
  return { text: `${value}%`, state: "reading" };
}

Number.isFinite checks for an actual finite number without converting a string into one. The range checks then apply the percentage rule we chose. MDN’s Number.isFinite reference.

At the response boundary, catch invalid-data failures and show an honest error state. Do not catch them and return 0%. A missing field and a failed request also need separate messages: “Not provided” describes a successful response without a reading; “Could not load the reading” describes a request failure.

Check the cases a polished screenshot hides

Save this beside the helper as check-percent.mjs, then run node check-percent.mjs. These assertions check real zero, both missing forms and inputs that must not look like valid readings.

import assert from "node:assert/strict";
import { presentPercent } from "./percent.mjs";

assert.deepEqual(presentPercent(0), { text: "0%", state: "reading" });
assert.deepEqual(presentPercent(72), { text: "72%", state: "reading" });
assert.deepEqual(presentPercent(100), { text: "100%", state: "reading" });
for (const value of [null, undefined]) {
  assert.deepEqual(presentPercent(value), {
    text: "Not provided", state: "missing"
  });
}
for (const value of ["0", -1, 101, NaN, Infinity]) {
  assert.throws(() => presentPercent(value), RangeError);
}
console.log("Percentage boundary checks passed");

The helper and these checks were run locally. They verify this display boundary, not a complete dashboard or its network behavior.

When wiring the interface, try the same values through a fixture response. Keep the explanatory text visible; color alone cannot tell a viewer why a number is absent. Check a slow response as well, so an old reading is not presented as the newly loaded result without a label.

For the demo, use clearly identified sample data if a device is unavailable. A sample value can demonstrate the interface. It cannot prove the device supplied that value.

Stavleak produces hackathons for organizations and provides the event workspace. Find an event in the hackathon catalogue, or use the organizer toolkit to make demo expectations clear to participants.

An autonomous AI agent drafted this article, generated the cover and checked the code. The sensor example and image are conceptual. No customer results or device performance figures are claimed.

Write hackathon README instructions that a teammate can check

Stavleak — Wed, 30 Sep 2026 21:17:00 +0000

Your teammate opens the repository and finds “run the app.” They still need to ask which folder to use, what should appear and whether the result is correct. A useful hackathon README answers those questions before the author joins the call.

Start with one complete path from opening the project to seeing its main result. Give every step an action and an observable outcome. A command that finishes without an error is only part of the check.

Pick one job the reader can finish

Suppose a fictional project lets a participant add an idea to a board. “Explore the dashboard” is too broad for a first run. “Create an idea called Water meter and find it on the board” gives the reader a finish line.

Write the path for someone who did not build the project. Name the starting page, the button and the result using the words visible in the interface. If your README says “submit” but the button says “Add idea,” change the README.

GitHub describes a README as a place to explain what a project does and how to get started. That is a useful priority when time is short: make the first successful action easy to find before adding a long account of your architecture. GitHub’s README guidance.

Put the outcome beside the instruction

This is an illustrative acceptance section for that idea board. The paths, labels and behavior are invented; adapt them to the project you have actually checked.

## Check the first successful action

Starting point: the app is running and the home page is open.
Required access: the local demo participant account described above.

1. Open the Ideas page.
   Expected: a heading named Ideas and a button named Add idea.
2. Select Add idea and enter Water meter as the title.
   Expected: the title stays visible in the form.
3. Save the form once.
   Expected: one Water meter card appears on the board.
4. Reload the Ideas page.
   Expected: the same card is still present, without a duplicate.

If the account is unavailable, stop at step 1 and report access_blocked.
The fallback screenshot demonstrates layout only; it does not prove saving works.

The reload expectation is a product decision. A temporary prototype might intentionally lose data. If that is your design, say so and change the expected result. Do not promise persistence because it sounds more complete.

Keep setup instructions immediately above this section. For each real command, state the working directory and when it is finished. If two processes must remain running, label their terminals. Copy the commands from the successful attempt rather than from memory.

Ask someone to follow the words exactly

Give a teammate the README and stay quiet during their first attempt. Record the first place where they must guess. That is usually a more useful edit than another introductory paragraph.

A small review record is enough: instruction, expected result, observed result and next change. “Step 3: one card expected; two cards observed; disable repeated submission while saving” points to a specific fix. “The README is confusing” does not.

Separate an instruction failure from an application failure. A missing account name belongs in the README. A duplicate save belongs in the application. Documenting a workaround does not make the underlying behavior pass.

Before submission, check that screenshots match the current labels and that links to files still open. Give the reader one main route, then place optional features below it. A judge should be able to finish the main route without searching through every feature you built.

Stavleak produces hackathons for organizations and provides the event workspace. If you are choosing where to use this checklist, browse the hackathon catalogue. Organizers can use the Stavleak toolkit when preparing participant materials.

An autonomous AI agent drafted this article and generated the cover. The project, interface labels and image are conceptual. The README example is an illustration, not a claim that a complete application was tested.

Agree on your hackathon API before frontend and backend split

Stavleak — Wed, 30 Sep 2026 20:02:48 +0000

Your frontend expects tasks. Your backend returns items. Both branches run, but the first integrated screen is empty. Agree on one response shape before the team starts working separately, then test the first real request while there is still time to change it.

An API contract is a shared description of a request and its response. For a small hackathon prototype, it can start as a short Markdown file with a route, a JSON example and clear rules for empty results and errors.

The task board below is a fictional teaching example. It is not a Stavleak endpoint or a description of a customer project.

1. Pick the screen you will demonstrate

Start with one user action: a teammate opens the task board and sees the tasks and their owners. The frontend needs a list. The backend needs to return the same fields every time.

Write down what that screen needs before designing every endpoint in the project. For this example, the first contract is:

Question	Team decision
Request	`GET /api/tasks`
Successful response	HTTP `200`, `Content-Type: application/json`
Response container	An object with an `items` array
No tasks yet	`{"items": []}` with HTTP `200`
Task identity	A non-empty, unique string `id`
Task title	A string with at least one non-space character
Task owner	`assignee` is always present: a non-empty name or `null`
Task state	`status` is exactly `todo` or `done`

For this prototype, null means the task has no owner. A missing assignee field is a contract mistake. That decision lets the frontend show “Unassigned” without guessing what the server meant.

If your route returns private team data, add authentication and authorization requirements to the contract and enforce them on the server. A sample JSON response does not provide access control.

2. Share three examples, including the awkward ones

Put the successful response in the repository beside the contract:

{
  "items": [
    {
      "id": "task-demo-1",
      "title": "Connect the first screen to the API",
      "assignee": "Demo teammate",
      "status": "todo"
    },
    {
      "id": "task-demo-2",
      "title": "Check the empty state",
      "assignee": null,
      "status": "done"
    }
  ]
}

The frontend can use this file to build the screen while the backend is unfinished. Label the data as sample data during a demonstration if it is still being used.

Also share the empty response, {"items": []}, and an error example. Agree on the error status and body for each failure you intend to handle. An HTTP error must remain an error; do not quietly replace it with sample tasks.

For example, if a later search endpoint rejects malformed input, the team can specify an HTTP 400 response with {"error": {"code": "INVALID_QUERY", "message": "Check the search query."}}. MDN describes 400 Bad Request as a client-side request error. The code and message here are your own choices, not fields supplied by HTTP.

Make the screen show different states for “no tasks” and “could not load tasks.” Otherwise, the user cannot tell whether the board is empty or the request failed.

3. Catch a response mismatch close to the request

A small guard can catch the exact mismatch your team is worried about. This JavaScript function checks our example response before the frontend renders it:

export function assertTaskResponse(value) {
  if (!value || typeof value !== "object" ||
      Array.isArray(value) || !Array.isArray(value.items)) {
    throw new TypeError("Expected an object with an items array");
  }

  const ids = new Set();
  const nonEmpty = (text) =>
    typeof text === "string" && text.trim().length > 0;

  for (const task of value.items) {
    if (!task || typeof task !== "object" || Array.isArray(task) ||
        !nonEmpty(task.id) || !nonEmpty(task.title) ||
        !(task.assignee === null || nonEmpty(task.assignee)) ||
        !["todo", "done"].includes(task.status) || ids.has(task.id)) {
      throw new TypeError("Task response does not match the contract");
    }
    ids.add(task.id);
  }
  return value;
}

This guard accepts extra fields. It does not validate every possible API design, sanitize content, authenticate a user or replace backend validation. It checks the fields this screen needs, including the distinction between a missing owner and null.

Save it as task-contract.mjs. A quick Node.js check for the common tasks versus items mistake looks like this:

import assert from "node:assert/strict";
import { assertTaskResponse } from "./task-contract.mjs";

assert.deepEqual(assertTaskResponse({ items: [] }), { items: [] });
assert.throws(() => assertTaskResponse({ tasks: [] }), TypeError);
assert.throws(() => assertTaskResponse({
  items: [{ id: "task-1", title: "Wire API", status: "todo" }]
}), TypeError); // assignee is missing

console.log("Contract checks passed");

Run the check with node check-contract.mjs after saving that second snippet as check-contract.mjs. The published guard and check were executed locally. Additional tests covered valid tasks, missing fields, duplicate IDs, unsupported states and malformed containers.

4. Integrate one real request before adding more screens

Choose a checkpoint early in the event for the frontend and backend owners to meet. Open the screen against the actual development API, inspect the response and confirm that the agreed JSON works without renaming fields in an unrelated component.

Check the route, base URL and status as well as the body. A correct object at the wrong URL does not connect the application. For browser requests across origins, check your server's CORS configuration rather than disabling browser security.

Test the populated state, the empty state and a failed request. Keep the development-only fixture switch explicit so the team knows which source the screen is using. Then record the working request and the commit that contains both sides.

5. Change the shared contract before changing either side

When a teammate wants to rename assignee to owner, update the contract, examples and check together. Tell the frontend owner which commit changes the response. During the event, that short message can prevent two people from debugging incompatible versions of the same screen.

If the project grows, OpenAPI gives you a standard way to describe HTTP API operations and their schemas. You can move the same decisions into an OpenAPI document and use tools that understand that format. Writing a specification does not by itself enforce the contract at runtime.

Before the team leaves the checkpoint, name the person responsible for the next integration, the route they will connect and the time they will check it. Put those three details beside the contract.

Stavleak produces hackathons for organizations and provides the event workspace. For your next event, you can browse hackathons on Stavleak. If you are preparing the event itself, the organizer toolkit contains planning materials.

An autonomous AI agent drafted this article, generated the cover and checked the code. The example, names and image are conceptual. No customer results or event performance figures are claimed.

The commit is correct. Why does the hackathon demo fail on a clean checkout?

Stavleak — Wed, 30 Sep 2026 15:42:42 +0000

Suppose your prototype processes a task successfully on your laptop. You submit that exact commit. A judge checks it out, follows the startup command, and gets a missing-file error. The code version is right, but the run depended on a generated file that never entered the repository.

You can expose this before submission with a short clean-start rehearsal. Give it a 15-minute timebox as an exercise budget. If setup takes longer, record the blocked step and its requirements.

1. Define the starting conditions

Choose one observable action, such as processing one synthetic task. Write down its input and expected output before running anything. “The app starts” is too vague when your pitch promises a completed action.

Here, cold means a fresh checkout without generated application state. Warm means the same directory after an action has changed that state. These terms describe our test conditions; they do not measure process startup performance.

Use a disposable environment without production credentials or sensitive host-folder mounts for unfamiliar code. Dependency installation and startup can execute code. Keep the rehearsal data synthetic, and choose a demo directory that contains nothing valuable.

2. Minutes 0 to 3: check the submitted version

Clone into a new directory. Substitute your repository URL and full submitted commit identifier:

git clone "<repository-url>" rehearsal
cd rehearsal
git checkout --detach "<full-submitted-commit>"
git rev-parse HEAD
node --version

Compare the printed commit with the submission record. Git's detached checkout puts HEAD at the selected commit. A fresh directory also stops a generated file in your working copy from silently becoming part of the rehearsal.

Record the working directory, operating system, exact runtime and dependency manager versions. Put the tested runtime version in the repository's version-manager file or environment instructions, and verify the selected version before installation. List external databases, operating-system libraries and service accounts separately when your scenario needs them.

3. Minutes 3 to 6: install the recorded dependencies

Use the project's chosen manager and committed lockfile. For a pnpm project, pnpm install --frozen-lockfile fails when the lockfile needs updating or is missing. For an npm project, npm ci requires an existing lockfile and fails when it disagrees with the manifest. Use the manager and configuration the project actually records.

If installation fails, preserve the error before changing anything. Updating dependencies until the screen opens gives you a different setup to document and test. Make permitted repairs in the working version before submitting it again under the event's rules.

Review install scripts before running unfamiliar packages. Skipping scripts can omit required build steps, so record that choice. The tiny example below requires Node.js 22+ and built-in modules only, with no installation, network calls or credentials. Record the exact Node version used for your run.

4. Minutes 6 to 10: expose the missing seed step

This toy program processes one fictional task. Its generated state lives beside the script in .demo-state/queue.json. Save the complete code as demo.mjs in a new empty demo directory. The code and data are an educational example, separate from Stavleak's product implementation.

import { mkdir, readFile, writeFile } from 'node:fs/promises';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';

const freshState = () => ({
  fixture: 'toy-task-queue-v1',
  tasks: [{ id: 'toy-task-1', done: false }],
});
const serialize = (state) => `${JSON.stringify(state, null, 2)}\n`;

async function readState(stateFile) {
  let text;
  try {
    text = await readFile(stateFile, 'utf8');
  } catch (error) {
    if (error.code === 'ENOENT') throw new Error('state_missing');
    throw error;
  }
  let state;
  try {
    state = JSON.parse(text);
  } catch {
    throw new Error('invalid_state');
  }
  if (
    state?.fixture !== 'toy-task-queue-v1' ||
    Object.keys(state).sort().join(',') !== 'fixture,tasks' ||
    !Array.isArray(state.tasks) || state.tasks.length !== 1 ||
    state.tasks[0]?.id !== 'toy-task-1' ||
    Object.keys(state.tasks[0]).sort().join(',') !== 'done,id' ||
    typeof state.tasks[0].done !== 'boolean'
  ) throw new Error('invalid_state');
  return state;
}

export async function execute(command, stateFile) {
  if (!['seed', 'run', 'reset'].includes(command)) {
    throw new Error('bad_command');
  }
  if (command === 'seed') {
    await mkdir(dirname(stateFile), { recursive: true });
    try {
      await writeFile(stateFile, serialize(freshState()), { flag: 'wx' });
    } catch (error) {
      if (error.code !== 'EEXIST') throw error;
      await readState(stateFile);
      return { status: 'already_prepared' };
    }
    return { status: 'prepared' };
  }
  const state = await readState(stateFile);
  if (command === 'reset') {
    await writeFile(stateFile, serialize(freshState()));
    return { status: 'reset' };
  }
  if (state.tasks[0].done) return { status: 'nothing_to_process' };
  state.tasks[0].done = true;
  await writeFile(stateFile, serialize(state));
  return { status: 'processed', task: state.tasks[0].id };
}

const scriptFile = fileURLToPath(import.meta.url);
if (process.argv[1] && resolve(process.argv[1]) === scriptFile) {
  const stateFile = join(dirname(scriptFile), '.demo-state', 'queue.json');
  try {
    console.log(JSON.stringify(await execute(process.argv[2], stateFile)));
  } catch (error) {
    console.error(JSON.stringify({ error: error.message }));
    process.exitCode = 1;
  }
}

Run node demo.mjs run first. On a fresh copy, it prints {"error":"state_missing"} to stderr and exits with code 1. The failure is useful: it identifies a preparation requirement. Preparation remains a separate, visible step.

If you commit the example, add .demo-state/ to its .gitignore before staging files. Keep the generator in the repository and generated state outside it. Git's ignore rules do not affect an already tracked file or remove it from history.

5. Minutes 10 to 13: compare cold and warm results

Run these commands one at a time, waiting for each to finish:

node demo.mjs seed
# {"status":"prepared"}
node demo.mjs run
# {"status":"processed","task":"toy-task-1"}
node demo.mjs run
# {"status":"nothing_to_process"}

The first action consumes the task. The second action returns a different result because the input state changed. Restarting Node does not restore the file. If the presenter expects processed at every pitch, this is another missing assumption.

Running seed again returns already_prepared and preserves existing state. Separate “prepare if missing” from “restore the initial fixture” so a setup command does not quietly erase a previous run.

6. Minutes 13 to 15: reset and repeat the action

node demo.mjs reset
# {"status":"reset"}
node demo.mjs run
# {"status":"processed","task":"toy-task-1"}

The reset checks the fixed toy marker and shape before overwriting that one file. It refuses missing, malformed or unrelated state. Do not put real records in this directory. For your project, describe exactly which test records a reset affects and how to verify the initial conditions.

This is a sequential file-based demonstration. It has no concurrent-worker coordination, atomic replacement or crash-recovery guarantee. Node's file-system documentation warns against overlapping writes without waiting for them to settle. Use a real persistence design for a real queue; this script only demonstrates startup assumptions.

7. Turn the blocked step into a tested instruction

Keep a short rehearsal record: commit, environment, starting state, commands, expected output, observed output and first blocked step. If someone manually supplied a file, include its safe generator or an approved acquisition step. Repeat the rehearsal from another clean copy after the repair.

Name required environment variables without publishing secret values. An .env.example can show names and non-sensitive defaults. If a credential was committed, follow GitHub's guidance to revoke or rotate it first; deleting the latest file is insufficient.

Put the tested setup, seed and reset commands beside the demo scenario. Stavleak's project README guide helps place that scenario, fixed version and limitations together. Your rehearsal record should say what reproduced in this environment and what remains untested, including external services you could not pin.