gilde

← All craftbooks

Hotfix Flow

Ship and releaseevalv2.0.2released 2026-09-05workflow: build-loop

Stop a live failure with the smallest change that fixes it at the real site: reproduce with the least machinery that demonstrates the failure, patch minimally with the proper repair recorded as follow-up, validate with a rollback path, and pass an enforced review of the blast radius.

Steps

Entry step: reproduce. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Reproduce with the least machineryincident responderentry

    Establish the failure cheaply and concretely: a command, a probe, or a focused test — whatever demonstrates it fastest.

    Show working prompt
    The incident to hotfix: {{scope}}

Establish the failure with the LEAST machinery that honestly demonstrates it — this is an emergency, not the time to build test infrastructure. Read the incident report and the involved source with `read_file`. Choose the cheapest real reproduction: the command or entry point the report names, a few-line probe script, or a focused test only when the project already has an obvious test layout and it costs minutes. When a script-execution tool such as `run_nodejs_script` is wired this turn, actually run the reproduction and capture the output — the error text, the stack line, the wrong value. When no execution surface is available, say so plainly and pin the failure by reading the code to the exact line instead; never present a run you did not perform. Do not fix anything in this phase. If you cannot reproduce or locate the failure at all, record every attempt honestly rather than inventing a cause.

Write `{{workPath}}/repro.md` with exactly these sections: `## Symptom` (what is breaking, in the reporter's words), `## Repro command` (the exact command or probe that demonstrates it), `## Expected`, `## Actual` (the captured output or observed behavior — quote real text, and label anything you could not execute), `## Evidence` (the involved files with backtick paths, down to the line or symbol where the failure surfaces).

Observable handoff: write the completed result to `{{workPath}}/repro.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  2. Smallest change that stops the bleedingsoftware engineer

    Fix the cause at the real defect site with the minimum blast radius; defer the proper repair into Follow-up.

    Show working prompt
    Read `{{workPath}}/repro.md`, find the defect site it points at, and stop the bleeding with the SMALLEST change that fixes the cause. There is no prescribed output path for source changes — edit the actual files with `read_file` plus `write_file`/`replace_in_file`. Hotfix discipline: touch only what stopping THIS failure requires — no refactors, no renames, no drive-by cleanup, no new abstractions. When the proper repair is bigger than the emergency allows, make the safe narrow change now and write the proper repair into Follow-up instead of attempting it. Never special-case the exact reproduction input just to silence it, and never hide the failure behind a blanket try/catch that swallows the error instead of preventing it. Re-check the reproduction as you work.

Write `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (one paragraph), `## Change` (what you altered and why it stops the failure at its cause), `## Files touched` (backtick path per line), `## Risk` (what this patch could still break and anything you did not verify — be honest), `## How to verify` (the exact commands or checks a person runs to confirm), `## Follow-up` (the deferred proper fix and the debt this patch leaves, plus the backport note when other branches or releases need it). Before working, open `{{workPath}}/repro.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/fix-notes.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  3. Re-run the reproduction and record rollbacksoftware engineer

    Prove the failure is gone, be explicit about what was and was not verified, and write the escape route.

    Show working prompt
    Prove the patch did its one job, and write down the escape route. Read `{{workPath}}/repro.md` and re-run the EXACT reproduction it records — the failure must be gone. Exercise the immediate neighborhood the cheapest honest way you can (the same entry point on a healthy input, an existing script, a small probe) so the patch did not trade one failure for another. Anything you could not actually run is recorded as unverified, never claimed — and when no execution surface is available this turn, verify by re-reading the changed code against the reproduction and say plainly that the run itself is still owed. Then record the rollback: exactly how to undo this patch fast if it goes wrong after shipping.

Write `{{workPath}}/validation.md` with exactly these sections: `## Repro re-run` (the command and what happened, or the honest record of why it could not run), `## Result` (what is fixed, what was verified, what remains unverified), `## Rollback` (the concrete, runnable way to revert this patch — the exact files to restore or the commit to revert, plus any step that must accompany it). Before working, open `{{workPath}}/repro.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/validation.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  4. Evaluate the deliverableincident reviewer

    Independently grade the observable deliverable and route it to finish, repair, or user escalation.

    Show working prompt
    Review `{{workPath}}/validation.md`, `{{workPath}}/repro.md`, `{{workPath}}/fix-notes.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone.

1. repro.md is concrete and honest: it quotes real captured output from a run that actually happened, or explicitly records that execution was unavailable and pins the failure to a line in the source — never an invented run.
2. The change is genuinely minimal: open every file fix-notes.md names and count the blast radius — nothing rode along beyond what stopping this one failure requires (no refactor, rename, or cleanup).
3. The patch fixes the cause at the real defect site rather than special-casing the reproduction input or swallowing the error with a blanket catch.
4. validation.md re-ran the original reproduction and the failure is gone — or states plainly what could not be run and why; nothing is claimed verified that was not.
5. The Rollback section is a real, runnable path: the exact files or commit to revert plus any accompanying step, not a vague instruction to undo the change.
6. The Follow-up section records the deferred proper fix and the debt this patch leaves, with a backport note when other branches or releases need it.
7. Every file path cited across repro.md, fix-notes.md, and validation.md exists in this project.

Open `{{workPath}}/validation.md`, `{{workPath}}/repro.md`, `{{workPath}}/fix-notes.md` with `read_artifact`. Write the evidence-backed review to `{{workPath}}/review.md` in the artifacts drawer with `write_artifact`.

List the findings as a markdown table with columns `| Severity | File | Line | Problem | Fix |` (severities: critical/major/minor/nit; empty table only on PASS). Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. The gate ENFORCES the verdict: a well-formed REVISE is rejected and routed back to `repair` automatically, carrying your findings — so list every finding in the table with a concrete fix. On PASS, `advance_task_step` to `finish`. Never write PASS while a criterion is unmet.
  5. Finishproject lead

    All deterministic and reviewer criteria passed.

    Show working prompt
    The independent review passed. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`{{workPath}}/validation.md`, `{{workPath}}/repro.md`, `{{workPath}}/fix-notes.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
  6. Repair the deliverablesoftware engineer

    Fix only the concrete gaps from the latest independent review.

    Show working prompt
    Read `{{workPath}}/review.md` with `read_artifact` and repair every failed criterion in `{{workPath}}/validation.md`, `{{workPath}}/repro.md`, `{{workPath}}/fix-notes.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `{{workPath}}/validation.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.
  7. Escalate unresolved concernsproject lead

    The bounded repair loop ended without a defensible pass.

    Show working prompt
    The deliverable did not pass after 3 review rounds. Do not claim success. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license