# AI Write Debugging Guide

The AI Write feature has multiple call sites with different element IDs, and
several silent-failure modes. Use this guide when "AI Write does nothing."

## Call sites (3 locations, different element IDs)

| Function | Button ID | Explanation ID | Notes ID |
|----------|-----------|---------------|----------|
| `setupCustomServiceModalEventListeners()` | `custom-service-ai-write-btn` | `custom-service-explanation` | `custom-service-technician-notes` |
| `setupServiceEditEventListeners()` (inline modal) | `ai-write-btn-quote` | `service-edit-explanation-quote` | `service-edit-technician-notes-quote` |
| Settings `setupServiceEventListeners()` | `ai-write-btn-settings` | `service-edit-explanation-settings` | `service-edit-technician-notes` |

## Common failure modes

### 1. Element ID mismatch
The handler looks for one ID but the HTML has a different suffix. Always use
`||` fallback chains that include ALL possible ID variants:
```javascript
const btn = document.getElementById('ai-write-btn-main') 
         || document.getElementById('ai-write-btn-fallback') 
         || document.getElementById('ai-write-btn-quote');
```

### 2. Duplicate event listeners (race condition)
`setupServiceEditEventListeners()` was called every time the modal opened,
accumulating click handlers via `addEventListener()`. After 3 opens, clicking
AI Write fired 4 simultaneous API calls. Fix: guard with attribute.
```javascript
if (modal.hasAttribute('data-edit-event-listeners-attached')) return;
modal.setAttribute('data-edit-event-listeners-attached', 'true');
```

### 3. FormValidator blocks save silently
FormValidator initialized with wrong IDs → `validateForm()` always false →
`saveServiceEdit()` never called. No error shown. Fix: call `saveServiceEdit()`
directly.

### 4. LLM ignores technician notes
The notes were sent to the LLM but the prompt never told it to use them. Fix:
put notes in the system prompt body with a prominent header AND add explicit
numbered instructions.

### 5. `explanationTextarea` vs `explTextarea` typo
Variable defined as `explanationTextarea` but used as `explTextarea` at one
call site. ReferenceError — caught by the catch block, shows generic error.

### 6. Custom service modal AI Write missing technician notes / vehicle context
`setupCustomServiceModalEventListeners()` calls `handleAiWrite(nameInput, recInput, explTextarea, aiWriteBtn)` — only 4 args. Missing:
- 5th arg: `technicianNotesEl` (the `custom-service-technician-notes` textarea)
- 6th arg: `vehicleContext` object with vehicleInfo and mileage

Without these, the LLM prompt never includes \"Technician's internal notes:\" or
\"Vehicle:\" / \"Current mileage:\" context. The AI writes generic explanations
instead of incorporating the technician's specific observations.

**Fix**: Match the edit-service call site pattern:
```js
const technicianNotesEl = document.getElementById('custom-service-technician-notes');
const vehicleCtx = {
    vehicleInfo: document.getElementById('vehicleInfo')?.value || '',
    mileage: document.getElementById('mileage')?.value || '',
    maintenanceInterval: null
};
await handleAiWrite(nameInput, recInput, explTextarea, aiWriteBtn, technicianNotesEl, vehicleCtx);
```

## Diagnostic checklist

1. `grep -n "ai-write-btn" repair-orders.html` — verify button ID exists
2. Check console for "Missing required elements for AI Write" log
3. Check if `handleAiWrite` is actually imported (line 5 of quote-tab-manager.js)
4. Verify the LLM endpoint is reachable: `curl -sk https://localhost/llm/v1/chat/completions`
5. Check nginx error log for 403 on shared modules