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

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.