Handle a hotfix

Diagnose and patch a broken build or regression quickly, track the fix as a hotfix/ story in the current sprint's ** Hotfixes section, and land it via a PR — without disrupting the planned sprint work.

• The user has described or supplied a failing build, error output, or broken test. If neither is available, ask: "Can you paste the build output or describe what's failing?"
• compass, gh, and the session's SSH agent are available (see Do not interfere with SSH session variables).
• Current sprint exists at doc/agile/versions/v0/sprint_NN/.

In execution order:

1. Extract the error. Ask the user to supply the full build output if not already provided:

   cmake --build --preset <preset> 2>&1 | tee /tmp/build.log
   

   Read the output and identify: the failing file, line, and error message. If the source is unclear, ask the user before proceeding.

2. Fetch latest main. Do not branch off a stale base:

   git fetch origin main
   

3. Create a hotfix branch and scaffold the story. Use How do I start a unit of work with compass? — compass story new — with --kind hotfix. The slug names the broken thing, not the fix:

   ./projects/ores.compass/compass.sh story new \
     --slug <broken_thing> \
     --kind hotfix \
     --title "Hotfix: <broken thing>" \
     --description "<one sentence: what is broken>." \
     --tags "hotfix:<component>"
   

   compass story new --kind hotfix creates hotfix/<broken-thing>, story.org, and a linked task. See How do I start a new feature branch phase?.

4. Read all generated files. Before writing any content, read story.org and the task file and note their :ID: values. Do not write [[id:...]] references from memory.
5. Fill in the story and task. In story.org: Goal = what is broken and what the fix will restore; Acceptance = build passes / test passes. In the task file: Goal = the specific code change needed; Plan = the diagnosis so far.

6. Wire the story into the sprint's ** Hotfixes section. Open doc/agile/versions/v0/sprint_NN/sprint.org and add a row under ** Hotfixes:

   | [[id:UUID][Hotfix: broken thing]] | STARTED | date | | One-line description. |
   

   If the sprint has no ** Hotfixes section yet, add it at the end of * Stories, before * Health Review.

7. Diagnose and fix. Read the failing file(s). Apply the minimal change that resolves the error. If the root cause is unclear or the fix would touch more than ~5 files, ask the user before proceeding.

8. Verify. Build and/or run the affected tests:

   cmake --build --preset <preset> 2>&1 | tail -20
   

   If the build is still red, return to step 7.

9. Update the task. Fill in * Notes with the root cause and the fix approach. Update Now → Fix verified locally., Next → PR., Last touched → today.

10. Commit using ORE Studio conventions. Follow Check git commit conventions before committing:

    git add <files>
    git commit -m "[component] Fix <what was broken>
    
    Story-ID: <story-UUID>
    Task-ID: <task-UUID>
    Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
    

11. Open a PR. Leave the SSH session variables alone, per the SSH memory, then compass pr create — it pushes the branch, builds the body (Summary, Changes, Traceability), and records the PR on the task.

    ./compass.sh pr create --title "[component] Fix <broken-thing>" \
      --summary "..." --change "..."
    

• hotfix/ branch exists on origin and a PR is open.
• Story is STARTED in the sprint's ** Hotfixes table.
• Task * Notes records the root cause and fix.
• PR number is recorded in the task's * PRs table.
• Build is green locally.

• How do I start a new feature branch phase? — hotfix branch naming convention.
• How do I start a unit of work with compass? — compass story new --kind hotfix syntax.
• Check git commit conventions before committing — commit format.
• Start work on a new story — the normal (non-hotfix) story runbook.