Story: Hotfix handling

Table of Contents

This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Provide a standard procedure for diagnosing and patching a broken build quickly, without disrupting the current sprint's planned work. Three deliverables:

  1. A hotfix runbook at doc/llm/runbooks/hotfix/runbook.org that guides the LLM through: extracting the error from a user-supplied build, fetching main, creating a hotfix/ branch, scaffolding a linked story and task with compass, diagnosing and fixing the issue, updating the task with details, committing, pushing, and opening a PR. The runbook should prompt the LLM to ask the user when anything is unclear.
  2. An update to the branching recipe (How do I start a new feature branch phase?) documenting the hotfix/<description> branch naming convention and when to use it versus feature/.
  3. A ** Hotfixes subheading in the sprint template (v2_doc_sprint.org.mustache) under * Stories, so emergency fixes land in their own clearly-labelled table and are not mixed with planned sprint work.

Status

Field Value
State DONE
Parent sprint Sprint 18
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-05-28

Acceptance

  • doc/llm/runbooks/hotfix/runbook.org exists and covers all steps from error extraction to merged PR.
  • The runbook instructs the LLM to ask the user when the error source, branch, or fix strategy is unclear.
  • Branching recipe updated: hotfix/<description> convention documented, * Conventions section distinguishes feature vs. hotfix branches.
  • Sprint template has a ** Hotfixes section under * Stories (after the theme sections), with its own #+ATTR_HTML and table scaffold.

Tasks

Task State Start End Description
Implement hotfix handling STARTED 2026-05-28   Write runbook, update branching recipe, update template.

Decisions

Out of scope

  • Automating the build error extraction (capturing stderr from cmake --build output is sufficient for now; no structured error parser).
  • A compass hotfix subcommand — the runbook calls compass goto with a hotfix/ branch slug; no new compass command is needed yet.

Emacs 29.1 (Org mode 9.6.6)