1. Introduction

This article is the tenth in a series explaining the design of Hora Kit, the AI development framework that we (Open Reach Tech) released as open source. The main article is here.

We open-sourced Hora Kit, an AI development framework for truly automated development

A note on terminology. There is only one command you type in Hora Kit: /hora. Depending on the situation, /hora calls /hora-spec (writes the spec), /hora-setup (creates the implementation repositories), /hora-plan (fixes the version and writes the feature list and contracts), /hora-build (takes one feature through the 18 checkpoints), and /hora-accept (performs acceptance), in that order. /hora-hotfix is the only one that /hora does not call; a person types it directly. The docs call /hora-spec "the deciding side" and the rest "the building side", and this article uses those names too.

Hora Kit's normal path is to write the spec, plan, pass the 18 checkpoints, and accept. It is the right path, but when something is broken in production and you have only two hours, this path is too slow.

/hora-hotfix is the second path, for exactly that. It fixes one defect, ships it, and writes down everything it skipped. What was skipped does not quietly disappear; it comes back later as actual work.

/hora          one feature  →  18 checkpoints  →  accepted
/hora-hotfix   one defect   →  6 gates         →  landed, but with debt

/hora does not launch this. Whether it is an emergency is for a person to decide, so you type /hora-hotfix yourself. If you have ever handled an outage in the middle of the night, try reading this while comparing it with your own company's hotfix procedure.

2. What is given up, and what is not

The docs explain the reasoning behind this line as follows. What eats the time is not the unit tests; they finish in minutes and are the only grounds for saying this fix has not broken something else somewhere, so they stay. What takes hours is the review, and that is what gets deferred.

We too believe that "we're in a hurry, so skip the tests" is the most dangerous judgment precisely when you are in a hurry, and this line is the starting point of the hotfix path.

3. The six gates

Each gate has exactly one passing condition, and the next does not begin until the previous one is finished. Let us go through them in order.

H1 is the admission judgment. Two things happen here. The first is deciding whether this belongs on the hotfix path at all; if it matches any of the following six, it does not. A schema change that is not backward compatible; a schema change that touches a table for which the open release/<version> has unapplied migrations; a change to a contract that another repository is in the middle of building against; adding, removing, or updating a dependency; a new operation, screen, or background job; and work that does not fit in a single branch. The second is deciding what "fixed" means, and a person writes this as a single sentence. It is a sentence stating how the product should be, and that belongs to a person. This one sentence becomes the entire acceptance criterion for this run.

H2 is reproduction. Write a failing test. And one that fails because of this defect. It is written before the fix, not after. Some defects cannot be caught by a test, such as slow queries or things that only appear with production data. In that case, write reproduced: no and the reason in the record, and include measurements from before and after the fix instead.

H3 is the fix. Only the minimal change that makes the H2 test pass goes in. No refactoring, no tidying up while you are at it.

H4 is the blast radius. Run the full unit suites of every repository, and on top of that, run whatever the touched surfaces enforce.

H5 is the record. Write .hora/hotfix/<hotfix-id>.md. This is the payment for everything this run skipped, so no item is optional.

H6 is landing. Cut hotfix/<hotfix-id> from main and merge it back into main. Branches are never cut from there. After that, /hora brings the open release/<version> up to date with the new main.

4. Instead of refusing, offer options

When H1 judges "does not belong", /hora-hotfix does not refuse. The docs say "nobody is helped by being told 'I can't' at 3 in the morning."

Instead, it assembles actual alternatives for your defect, then presents three options.

1. Ship a code-only fix now (usually this)
     Stop the exposure, stop the bad writes, add a guard.
     The breaking half goes to the next version

2. Do it on release/<version> with the patch bumped
     The normal path. Slow, but properly accepted

3. A person does it outside hora          (only for breaking schema changes)
     The kit does not pretend to have passed the gates.
     It only records who decided and what was done

/hora-hotfix does not choose on your behalf. There is a reason the third option is provided on purpose: a gate with no way through is a gate people go around, and when that happens, nothing is left in the record.

5. The schema-change test is "can the code be rolled back without rolling back the DB?"

Whether a hotfix may touch the schema is not a question of "does it need a migration?". It is "can the code be rolled back without rolling back the DB?".

If all three of the following hold, the migration can ship first and the code after, so no atomic deploy is needed. It is backward compatible (the code running in production right now keeps working as-is after the migration is applied), it is lossless (nothing existing is dropped, renamed, narrowed, or overwritten), and its time is stated (execution time and locking behavior are given as numbers against the actual row count). The third is not a formality: a CREATE INDEX that stops writes for an hour is a failure as a fix that has to ship in two hours.

Repairing broken rows is not a migration. Migration files are replayed forever in every environment. Repairs are done with a one-off script that a person runs and that can be restored from backup.

6. What goes into the record

# Hotfix — session-expiry-blank

<!-- landed: 2026-08-23 -->
<!-- touches: attendance, sign-in -->
<!-- reproduced: yes -->
<!-- suites: full -->
<!-- data-damage: none -->
<!-- deferred: acceptance review, live run, UX audit, scenario list -->
<!-- debt: open -->

## What "fixed" means
<the one sentence written at H1>

## What backs this
- <test> — fails before the fix, passes after
- Full unit suites: backend 214 passed, frontend-employee 51 passed

## What was skipped
This code has not been accepted. …

The verdict word is landed, not passed. passed belongs to /hora-accept, so that a hotfix record is never mistaken for acceptance. touches: holds the features the changed files belong to, and this is the line that later decides which acceptances get redone.

7. The debt comes back as ordinary work

Nothing new has been added to stop anything for the sake of hotfixes. The debt is converted into work that the existing gates already know how to handle.

Next /hora        Reports all unpaid debt, with names and links

Next /hora-plan   For each feature listed in touches:, resets checkpoint 18
                  to [ ]. Along with the plan-side entry. Then writes debt: closed

From there it is the normal path. /hora-build picks up that feature, /hora-accept accepts it at its proper scope, and the version cannot complete until that passes.

In other words, a hotfix is not free; using it adds work to the next version. This is what keeps the hotfix from becoming everyone's everyday path.

8. Summary

In the design of the emergency path, there are three things we consider important. What gets skipped is the review, not the tests. Do not refuse; offer options (a gate with no way through gets bypassed, and no record remains). Record what was skipped as debt and return it to the normal path (if it were free, it would become the everyday path).

I hope this is useful to teams that tend to settle a late-night hotfix with "we'll do it all properly later".

The original source is here. https://github.com/openreachtech/hora-core/blob/main/docs/hotfix.ja.md