Cron Jobs Need Run Verdict Files

Recurring automation usually fails in boring ways. The job runs at 2 a.m., something times out, and by morning all you have is a red badge and a half-helpful log line. The painful part is not the failure itself. It is the lack of a clear story about what the job decided, what inputs it saw, and why it stopped.

That is why I like adding a run verdict file to scheduled workflows. Think of it as a smal receipt for the job: one structured file, written at the end, that explains the run in plain terms. It gives humans a quick summary and gives future automation a stable artifact to inspect.

This pattern fits all kinds of Automation work, not just email flows. I first leaned on it while cleaning up recurring background tasks that looked healthy from the outside but kept producing fuzzy incident reports. The code was okay. The observability was not.

Why recurring automation is hard to debug

A cron job has a weird life. It wakes up inside yesterday's state, hits today's inputs, and leaves behind artifacts for tomorrow. That makes it differenly fragile from a local script you run by hand.

Three things usually create the mess:

• The job logs a lot, but does not state its final decision clearly.
• Retries overwrite context instead of preserving it.
• Operators have to reconstruct the timeline from five places.

You can see similar failure patterns in adjacent workflows too. Articles about risk tiers for noisy signup paths and avoiding inbox guesswork in scheduled checks are really about the same underlying need: automation should prove what it believed, not just emit noise.

I also notice teams chasing random search terms like tamp mail com when a flaky recurring check pops up. Sometimes the provider is weird, sure, but often the deeper issue is that the run leaves no trustworthy verdict artifact behind.

What a run verdict file should contain

The verdict file does not need to be fancy. It just needs enough aligment between operators, scripts, and postmortems.

I usually include:

• run_id
• started_at and finished_at
• status
• inputs_summary
• checks_performed
• decision
• next_action
• evidence

The key is the decision field. Not "step 6 passed." Not "done." A real sentence like: "Skipped publish because no eligible records were newer than the watermark." That one line saves more time than ten extra debug statements.

The evidence block should point to stable facts. File paths, record counts, request ids, maybe a matched subject line if the workflow handles notifications. Keep it short, but make it enough for someone else to retrace the job without guessing thier way through raw logs.

A small implementation pattern

Here is the shape I reach for in Developer Tools projects:

type Verdict = {
  runId: string;
  startedAt: string;
  finishedAt: string;
  status: "ok" | "skipped" | "failed";
  decision: string;
  nextAction: string;
  evidence: Array<{ label: string; value: string | number }>;
};

const verdict: Verdict = {
  runId,
  startedAt,
  finishedAt: new Date().toISOString(),
  status: publishedCount > 0 ? "ok" : "skipped",
  decision:
    publishedCount > 0
      ? `Published ${publishedCount} post(s) from approved input`
      : "Skipped publish because nothing met the freshness rules",
  nextAction:
    publishedCount > 0
      ? "Monitor comments and retry only on platform failure"
      : "Wait for the next scheduled run",
  evidence: [
    { label: "approvedItems", value: approvedItems.length },
    { label: "publishedCount", value: publishedCount },
    { label: "watermark", value: watermarkIso }
  ]
};

Then write it once, near the end of the run:

await fs.writeFile(
  `runs/${runId}/run-verdict.json`,
  JSON.stringify(verdict, null, 2) + "\n"
);

That single file becomes the handoff point between the cron worker, the operator, and any follow-up job. It also discourages a bad habit: letting each helper decide its own success language. One helper says "completed", another says "done", another throws a warning and exits zero. A verdict file forces one shared contract, which is nice.

How verdict files change incident review

The best part is not the code. It is how reviews get shorter.

Without a verdict file, incident review sounds like this: "I think the job skipped because the query returned nothing, unless the publish step bailed first, or maybe the retry hit an old lock." With a verdict file, you get a plain answer first and then inspect logs only if needed.

That changes team behavior in a good way:

• Operators ask better questions.
• Retries become safer because the prior decision is preserved.
• Dashboards can summarize real outcomes, not just exit codes.

I would still keep normal logs and traces, of course. The verdict file is not a replacement. It is the thin layer that turns raw execution into an explainable result. In practice, that makes recurring jobs feel less mysterious and a bit more humane, which is rarer than it should be.

Q&A

Should every cron job write one?

If the job matters enough to page someone, publish content, move money, or mutate customer state, yes, pretty much. Tiny cleanup jobs can stay simpler, but even there the pattern ages well.

JSON only?

Usually yes. JSON is easy for machines and still readable for people. If your team likes Markdown summaries, generate them from the verdict file rather than treating Markdown as the source of truth.

What is the smallest useful version?

run_id, status, decision, and one evidence field. Start there. The pattern gets useful surprisingly fast, even before you add richer metadata.