Skip to content

Hotfix Fast Track

This guide is meant to help you understand what the AI assistant does when it runs this playbook. The idea is that you can read it, understand what happens at each step, and know what information you need to give the assistant so the work turns out well.

In short

  • What it's for: confirming in minutes, not hours, whether an urgent fix (hotfix) that has already been applied is safe to release to production.
  • When to use it: when the fix is already done and deployed, on a hotfix/* branch or with a ticket marked as hotfix, and there's no time for a full cycle.
  • What you need: a minimal set of critical tests ("smoke") for the module, the description of what was fixed, the story's test plan, and the project's qa-stack.yaml.
  • What you get: a clear verdict (release or stop), a test that watches over the fix, and a report with date and time.
  • Steps: 3, plus a pre-check — confirm the smoke exists, run it as a traffic light, leave a regression test, and generate the report.
What is a playbook? (if this is your first time using one)

Think of it as a cooking recipe for the AI assistant. You tell it "I want to do this" (for example, "I want to validate this urgent fix before releasing it") and the playbook is the recipe the assistant follows step by step, in order, without skipping anything, so the result is always the same no matter who asks for it.

Each step of the recipe uses a specific tool (in technical jargon they're called "skills"), a bit like a kitchen utensil: one is for peeling, another for cutting, another for baking. You don't need to know how each utensil works inside — you only need to know which ingredient goes into each step (for example, what was fixed, or which URL the fix is deployed on) so the final dish turns out well.

A playbook = an ordered guide of steps. A skill = the specific tool that carries out each step. You interact with the playbook — the assistant takes care of using the right tool at each moment.


1. What does this playbook do?

It's the playbook you use when an urgent fix (a "hotfix") has already been applied and you need to confirm in minutes, not hours, whether it's safe to release to production.

It's important to understand the difference from other playbooks: here the fix is already done. The focus isn't on helping the developer fix the bug (that's what the Bug Fix Cycle playbook is for) — the focus is on quickly validating that the fix works and that it didn't break anything critical, so you can decide on the spot: do we release it or not?

To achieve that speed, this playbook doesn't check the whole application end to end. Instead:

  1. It runs only an existing minimal set of critical tests (the "smoke" — the tests for the most important functions of that module, like someone who only checks a car's brakes and lights before hitting the road, not the whole car).
  2. It acts as an automatic traffic light: if those critical tests pass, it gives the green light to move forward; if any fails, it stops everything immediately.
  3. If it gave the green light, it saves one specific automated test that will watch over that particular fix in the future so it doesn't break again.
  4. It writes a report with the result and the exact date, so there's a record that the hotfix was validated before going out. The important parts (the traffic light, whether the test was saved, and the recommendation to release or not) are at the very top, so you can read them in a minute.

When it's done, the hotfix ends up with:

  • A clear verdict: approved for release or full stop with the reason documented.
  • A new automated test that protects that specific fix going forward (if time allowed).
  • A report with date and time, which serves as backing that the hotfix wasn't released "blindly".

2. When should I use this playbook?

Use it when you're facing any of these situations:

Situation Business example
There's an urgent fix already applied and it needs to go to production as soon as possible A TechStore customer discovers on a Friday afternoon that, when applying a valid discount coupon at checkout, the total isn't recalculated — the customer ends up overpaying. A developer has already applied the fix and is waiting for the OK to release it.
There's no time for a full test cycle (reproduce, write a red test, wait for the fix, verify in green) The TechStore team needs to release the checkout fix before the Friday night traffic peak starts — there's no room for a long cycle.
An automatic "traffic light" is needed before approving the release TechStore's QA lead doesn't want to approve the hotfix release "on someone's word" — they want a minimal set of critical tests to confirm that nothing essential broke.
The ticket or the branch are already marked as hotfix The developer pushed the fix to a branch called hotfix/checkout-discount or the ticket has the hotfix label.

Important

  • This playbook needs a minimal set of critical tests ("smoke") to already exist for the affected module, saved in its own smoke/ folder inside the module's tests. If there are none, the playbook stops immediately and doesn't continue — you first need to create at least one critical test for that module. This is non-negotiable: without that minimal safety net, there's no way to guarantee the hotfix is safe.
  • This playbook assumes the fix is already applied and deployed. If the bug hasn't been fixed yet, this isn't the playbook — it's the Bug Fix Cycle playbook, which does accompany the whole process of fixing it.
  • This playbook is specifically designed for a hotfix/* branch or a ticket with the hotfix label. If the fix isn't in that context, it isn't this playbook either — again, Bug Fix Cycle is the one that applies.
  • It's a playbook designed for urgency: it prioritizes speed over exhaustive coverage. It doesn't replace a full regression when there is time available.
  • If the project doesn't have the basic automated QA configuration yet (the qa-stack.yaml file), you first need to run the project setup playbook.

3. Walkthrough example: "TechStore", an online store with a shopping cart

We'll follow the same business case as in the project setup guide: TechStore, an online electronics store with a shopping cart.

It's Friday at 5 PM. A customer reports the following:

"I apply the coupon DESC10 at checkout, the website tells me the coupon is valid, but the total to pay doesn't change — I end up paying the full price."

The team confirms the bug: the business rule says "when a valid coupon is applied, the total must be recalculated with the discount applied", and today that isn't happening. It's a critical bug because it directly affects payments. A developer has already identified the problem and pushed the fix to the hotfix/checkout-discount branch, deployed to staging. The team needs to confirm in minutes whether it's safe to release it before the Friday night traffic peak starts.

That's exactly the scenario this playbook is for.

3.1 Before you start: what you need to have on hand

You don't need to know how to program, but you do need to have this information on hand:

Information TechStore example
Hotfix or ticket identifier HOTFIX-17
Affected module or story (with the story ID, if there is one) Checkout / applying discount coupons — story TS-US-14
What was fixed, in simple words "The checkout total wasn't recalculated when applying a valid discount coupon"
Which business rule the fix covers (the acceptance criterion, with its ID if it has one) "When a valid coupon is applied, the total must be recalculated with the discount applied"
Which environment the fix is deployed to https://techstore-staging.com, branch hotfix/checkout-discount
Confirm that a minimal set of critical tests exists for the checkout module A smoke/ folder inside the checkout tests, with at least one test. If TechStore never set up critical tests for checkout, you need to create at least one before continuing
The story's test plan test-plans/TS-US-14-test-plan.md — the case used for the Step 2 regression test comes from there

If you're not sure whether critical tests exist for that module, check it in the pre-check below (or ask the technical team to confirm whether the module's smoke/ folder exists).

Original playbook

The general playbook is in the NEO-releases repository.

3.2 How to start

Before Step 1, tell the assistant about the hotfix in question, with as much detail as possible:

💬 Prompt for the assistant
I want to validate the following hotfix before the release:
- Hotfix ID: HOTFIX-17
- Affected story or module: TS-US-14 / checkout - discount coupons
- What was fixed: the total wasn't recalculated when applying a valid coupon
- Rule it covers: "when a valid coupon is applied, the total must be recalculated
  with the discount applied"
- The app is at https://techstore-staging.com, branch hotfix/checkout-discount

Don't run any command yet, just save this information as context.

The last line is useful

It asks the assistant to wait for your confirmation before it starts running tests — that way you can review the information before starting.


3.3 Step by step

Pre-check — Is there a minimal safety net?

Skill used: none — it's a check you do before starting.

What happens: before touching anything, you confirm whether the affected module already has a minimal set of critical tests saved (the "smoke"): a smoke/ folder inside the module's tests, with at least one test in it. It's like asking "does this road already have guardrails?" before driving fast on it.

The Step 1 tool doesn't do this check for you

If there are no tests in that folder, the tool that runs the tests doesn't stop on its own: that's why this check is done beforehand, manually (or by asking the technical team to confirm it). What counts is the smoke/ folder: marking tests as "smoke" in some other way (for example, with a tag inside the file) isn't enough for them to be taken into account.

Result What it means What you do
✅ Critical tests do exist for the module There's a minimal safety net Move on to Step 1
❌ Critical tests don't exist for the module There's no way to guarantee the hotfix is safe The playbook stops right here — you need to create at least one critical test in that module's smoke/ folder before continuing

Why this check isn't optional

It's the reason this playbook can be so fast in the following steps: it relies on a minimal base of reliable tests already existing.


Step 1 of 3 — Quick traffic light: run the critical tests

Skill used: lippia-neo-run-and-heal

What happens: the assistant runs only the existing critical tests of the affected module (the ones in the smoke/ folder) — not the whole application, just the essentials. It acts as a traffic light: it doesn't try to "fix" anything if something fails, it just reports the result as it is.

💬 Prompt for the assistant
/lippia-neo-run-and-heal
Run the priority smoke for the checkout module (its smoke/ folder) with:
- max_iterations: 1
- plateau_detection: false
- run_label: "smoke-hotfix"

With TechStore, this means running the critical tests of the checkout module (for example: "the customer can complete a purchase", "the total is calculated correctly", "valid coupons are applied") and seeing whether they all still work with the fix applied.

Two details about this step

  • Even though nothing is repaired if a test fails, the assistant still does two automatic checks before running: it fills in pending data (values marked as TODO) and replaces hand-written credentials with the ones from the configuration file. If it touches any of that, it's noted in the result.
  • Running only the smoke/ folder works with Playwright. If the project uses Lippia, it can't be limited by folder and the full set is run.

Checkpoint 1 — Release traffic light

Result Traffic light What you do
✅ All the critical tests pass 🟢 Green Move on to Step 2
❌ Some critical test fails 🔴 Red Full stop. Step 2 is skipped and you go straight to building the report (Step 3), documenting the block and what needs to be escalated, and the hotfix is not released until it's resolved

This is the heart of the playbook

If the traffic light turns red, there's no automatic way back — the developer needs to check what else broke with the hotfix before trying again.


Step 2 of 3 — Leave a test that watches over this fix forever

Skill used: lippia-neo-generate-test-suite

It only runs if Step 1 gave 🟢 green

What happens: the assistant writes one specific automated test, dedicated exclusively to this fix, that confirms the correct behavior (the coupon is applied and the total is recalculated) keeps working. To do so, it takes only the case for the fixed rule from the story's test plan — and without a test plan, it can't generate it. Unlike the Bug Fix Cycle playbook, here this test is born green — there's no need to see it fail first, because the fix was already applied from the start.

💬 Prompt for the assistant
/lippia-neo-generate-test-suite
Hotfix regression mode: generate ONLY the test for the fixed AC "when a valid
coupon is applied, the total must be recalculated with the discount applied"

It's like installing a security camera pointed exactly at the spot where there used to be a problem: from now on, if that specific problem came back, something would detect it on its own.

If there's evidence from a previous exploration of checkout, the assistant uses that real technical data from the screen. If there isn't, the test ends up with some data marked as pending (TODO) — in this playbook that's acceptable, and it gets filled in later.

A touch-up before saving the test

The tool gives the test a header comment designed for the bug cycle ("this test should FAIL until the bug is fixed"). Since in a hotfix the fix is already applied, that comment needs to be changed by hand to something like Regression test — HOTFIX-17: recálculo del total con cupón before saving it. The hotfix ID (HOTFIX-17) goes in that comment, in the commit message, and in the report: the tool doesn't receive it as input.

What you have at the end of this step: a new automated test file, saved in the project's history (a "commit" in Git, mandatory before moving on), dedicated to this hotfix. It goes in the story's tests folder, with a name along the lines of tc-<number>-<short-description>.

If the urgency is so extreme there aren't even minutes for this step

It can be skipped — but it's recorded in the final report as a pending task, and a follow-up ticket is created, so you don't lose track of the fact that it still needs to be covered.


Step 3 of 3 — Final hotfix report

Skill used: lippia-neo-write-test-report

What happens: the assistant builds the report with the traffic light result, whether or not the watch test was generated (or whether it was left pending), and the exact date and time of the validation.

The report always has the same structure as any other test report (there's no "short" version): the sections that don't apply to a hotfix, like manual tests, show up marked as "no findings". You'll find the hotfix-specific parts in three places:

Report section What you'll see
Executive summary The smoke traffic light (✅ / ❌), whether the regression test was saved or left pending, and the overall status
Automated results The details of which critical tests passed and which failed; if the traffic light was red, what needs to be escalated
Summary and recommendations The recommendation to release or not release, and the pending task if the regression test was postponed

What you have at the end of this step: a document that answers a single key question: was this hotfix validated and is it safe to release, or not? It goes in the project's reports folder (by default test-results/reports/), with a name along the lines of TS-US-14-bug-HOTFIX-17-test-report-<date-and-time>.md.

If the traffic light was red, the report also documents why it was stopped, and distinguishes two cases: ❌ failed (the application really has a problem) or ⚠️ blocked (the cause was the environment, for example it wasn't responding).


3.4 What do I have after completing all the steps?

What you get What it's for
A clear traffic light verdict (green or red) Knowing, in minutes, whether the hotfix is safe to release
An automated test that watches over the specific fix (if there was time) It protects that specific fix from breaking in the future without anyone noticing
A report with date and time Evidence that the hotfix wasn't released "blindly" — there's a record of the validation
If the traffic light was red: the documented reason The team knows exactly what to check before trying the release again

From here on, the TechStore team can decide with real information whether to ship the discount coupon fix before the Friday traffic peak — and if at some point more complete coverage of that module is needed, it can be added later with another playbook, without holding up today's urgency.


4. Common problems (and what to do)

What you see Why it might happen What to do
The pre-check shows there are no critical tests The affected module never had a minimal suite ("smoke") set up in its smoke/ folder Create at least one critical test for that module before trying this playbook again
The Step 1 traffic light turns red after applying the hotfix The urgent fix broke another important feature in the same module Don't release; coordinate with the developer to check what other behavior was affected
The Step 2 test passes, but the assistant had to "help" it pass There may be fragile selectors or data in the generated test Review the result; if the fix is a real one, it shouldn't depend on automatic adjustments
Step 2 doesn't generate the test The story's test plan doesn't exist Build the story's plan, or postpone the test and record it as pending in the report
The Step 2 test ends up with data marked as TODO The hotfix arrived without a previous exploration of the screen It's acceptable in this playbook; it gets completed in the follow-up ticket
There's no time even for Step 2 Extreme urgency It can be deferred — it's recorded as pending in the final report, so it isn't lost sight of
The tests fail at login The project's test credentials (.env.tests file) are empty or incomplete Ask someone on the technical team to fill in the real values — they're never written by hand inside the tests — and run Step 1 again
The project doesn't have qa-stack.yaml The initial bootstrap was never run First run the project setup playbook

5. Visual summary of the flow

flowchart TD
    A([🚑 Hotfix already applied<br/>e.g.: TechStore, discount coupon<br/>fix at checkout]) --> B{Does the module<br/>smoke exist?}
    B -->|No| C([⛔ STOP: create critical<br/>tests before continuing])
    B -->|Yes| D["<b>Step 1</b> — Traffic light: run<br/>the critical tests"]
    D --> E{Traffic light?}
    E -->|🔴 Red| G["<b>Step 3</b> — Stop report<br/>with what needs escalating"]
    E -->|🟢 Green| F["<b>Step 2</b> — Leave a test<br/>that watches over this fix"]
    F --> H["<b>Step 3</b> — Final hotfix<br/>report"]
    G --> I([❌ Not released])
    H --> J([✅ Approved for release])