Scheduled Batch Job
Build a scheduled batch job that runs on a cadence, processes a unit of work, is safe to re-run, and reports its outcome. Scopes the job FIRST — trigger cadence, the work it does, batch/chunk size, idempotency, failure/partial-failure handling, and observable output — then implements the runnable job, then tests a clean run, an empty run, a partial-failure run, and re-run safety. Covers cron scheduling semantics, batch processing, idempotent reruns, chunking, structured logging, exit codes, and graceful partial-failure handling.
Steps
Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.
- Scope the jobplannerentry
lock cadence, work unit, idempotency, failure handling
Show working prompt
Scope the batch job before coding. Step 1: State the cadence (e.g. the cron expression) and what one run is responsible for. Step 2: Define the unit of work and how items are fetched and chunked (batch size, ordering). Step 3: Decide idempotency: how a re-run avoids double-processing already-done items, and what happens if a previous run died mid-batch. Step 4: Define failure handling: does one bad item abort the run or get skipped-and-logged, the exit code on full vs partial success, and what gets logged for observability. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'a clean run processes all items and exits 0', 'an empty input run is a no-op that exits 0', 'a re-run does not reprocess completed items', 'a bad item is logged and skipped without aborting the batch'). `write_task_note` the scope + checklist and write the same to the produces path.
- Build the jobdeveloper
implement the runnable batch job
Show working prompt
Implement the job as a single runnable script with a clear entry point. Step 1: Fetch the work items and process them in chunks of the scoped batch size. Step 2: Make it idempotent — check a done-marker/store before processing each item so re-runs skip completed work. Step 3: Handle failures per the scope (skip-and-log vs abort) and emit structured log lines (start, per-batch progress, per-item errors, summary count). Step 4: Exit 0 on full success, a non-zero code on full failure, and the scoped code on partial. Use an in-memory store/sample data if none specified. On a loop-back, fix only the named gaps. `write_task_note` the file path and which criteria now pass.
- Write job testsdeveloper
test clean, empty, partial-failure, and re-run
Show working prompt
Write tests that invoke the job's run function with controlled inputs. Step 1: Assert a clean run processes every item and exits 0 with a correct summary count. Step 2: Assert an empty-input run is a no-op exiting 0. Step 3: Inject one failing item and assert it is logged/skipped (or aborts) per the scope, with the right exit code. Step 4: Run twice over the same input and assert the second run skips already-done items. `write_task_note` the test file path and pass/fail count.
- Evaluatereviewer
Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.
Show working prompt
Run the tests and execute the job. For EACH acceptance criterion: confirm a clean run processes all items and exits 0, confirm an empty run is a safe no-op, confirm a re-run does not reprocess completed items, confirm a bad item is handled per the scope, and confirm exit codes and log output match. Write PASS/FAIL per criterion. Then route — this is the whole point of the loop: - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`. - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps. Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in. - Finishdeveloper
All acceptance criteria met. Stamp a short summary and report DONE.
Show working prompt
Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.
Triggers
Phrases that suggest this craftbook to a crew.
- build a cron job
- scheduled batch job
- nightly job
- recurring task script
- batch processor
Source
View this craftbook on GitHub · MIT license