1 files changed, 85 insertions, 0 deletions
diff --git a/docs/adr/003-htmx-write-operations.md b/docs/adr/003-htmx-write-operations.md
new file mode 100644
index 0000000..2471a90
--- /dev/null
+++ b/docs/adr/003-htmx-write-operations.md
@@ -0,0 +1,85 @@
+# ADR 003: HTMX-Based Write Operations
+
+## Status
+Accepted
+
+## Context
+Phase 1-2 of the dashboard were read-only views. Phase 3 required transforming it into an active command center where users can:
+- Complete tasks/cards
+- Create new tasks
+- Add shopping items
+- Toggle item states
+
+Traditional approaches would require either:
+- Full page reloads (poor UX)
+- Complex JavaScript SPA framework (React, Vue)
+- Custom AJAX handlers
+
+## Decision
+Use **HTMX attributes** for all write operations, returning HTML partials that swap into the DOM.
+
+### Technical Details:
+
+**Pattern: Form submission with partial swap**
+```html
+<form hx-post="/complete-atom"
+      hx-vals='{"id": "{{.ID}}", "source": "{{.Source}}"}'
+      hx-target="closest .task-card"
+      hx-swap="outerHTML">
+    <button type="submit">✓</button>
+</form>
+```
+
+**Handler returns HTML partial:**
+```go
+func (h *Handler) HandleCompleteAtom(w http.ResponseWriter, r *http.Request) {
+    // ... complete the task via API
+    // Return completed state HTML or empty response
+    HTMLResponse(w, h.renderer, "completed-atom", data)
+}
+```
+
+**Quick Add Pattern:**
+```html
+<input hx-post="/unified-add"
+       hx-trigger="keyup[key=='Enter']"
+       hx-target="#task-list"
+       hx-swap="afterbegin"
+       name="content">
+```
+
+**Optimistic UI:**
+- Use CSS transitions for immediate visual feedback
+- On error, swap in error banner partial
+- HTMX `hx-on` events for state management
+
+**Unified Quick Add:**
+- Single input parses text for routing hints
+- `#groceries` tag → routes to shopping
+- `#work` tag → routes to Trello
+- Default → routes to Todoist
+
+## Consequences
+
+**Pros:**
+- No JavaScript framework needed
+- Server renders all HTML (single source of truth)
+- Progressive enhancement (works without JS, enhanced with)
+- Trivial to test (just HTTP handlers)
+- Fast development cycle
+
+**Cons:**
+- More HTTP requests than SPA approach
+- Partial HTML responses require careful template organization
+- Limited offline capability
+
+## Alternatives Considered
+
+**Option A: React/Vue SPA**
+- Rejected: Overkill for this use case, adds build complexity, harder to maintain
+
+**Option B: Full page reloads**
+- Rejected: Poor UX, especially on mobile
+
+**Option C: Custom JavaScript + JSON APIs**
+- Rejected: Reinventing what HTMX provides, more code to maintain