From b0d722d1a985326fb38e4e7fea237b9c4a2adcfd Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Thu, 30 Apr 2026 07:55:28 -0500
Subject: docs: record four ADRs for gloss design decisions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The four decisions called out in the brainstorm now have their own
files under docs/decisions/, each with Context / Decision /
Consequences / Alternatives Considered.

- 0001 — storage path default: respects org-directory if set, falls
  back to user-emacs-directory.
- 0002 — auto-fetch on local miss: silent fall-through, network
  failures surface via the regular error rollup. No y/n prompt for
  v1.
- 0003 — drill direction: every entry exports as twosided. One card
  per entry, both directions over time, no per-entry override.
- 0004 — HTML strip strategy: libxml-parse-html-region. Plain text
  only, no italic/bold preservation. Online fetch disabled package-wide
  for the session if libxml is missing.

The "Open Questions" section in the design doc is now "Decisions
Recorded" with links into the ADRs.
---
 docs/decisions/0003-drill-direction.org | 49 +++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 docs/decisions/0003-drill-direction.org

(limited to 'docs/decisions/0003-drill-direction.org')

diff --git a/docs/decisions/0003-drill-direction.org b/docs/decisions/0003-drill-direction.org
new file mode 100644
index 0000000..90073aa
--- /dev/null
+++ b/docs/decisions/0003-drill-direction.org
@@ -0,0 +1,49 @@
+#+TITLE: ADR-3: Drill direction
+#+DATE: 2026-04-30
+#+STATUS: Accepted
+
+* Context
+
+=gloss-drill-export-all= tags every entry for =org-drill=. The card
+type controls which direction(s) the drill quizzes — term-to-definition
+(recognition), definition-to-term (recall), or both.
+
+* Decision
+
+Set =:DRILL_CARD_TYPE: twosided= on every exported entry.
+=org-drill='s twosided card type alternates direction on consecutive
+visits, so a single entry quizzes both directions over time.
+
+No per-entry override in v1. Every entry exports as twosided.
+
+* Consequences
+
+*Positive.*
+
+- Tests both recognition and recall over time without doubling the
+  deck size — one entry, both directions, alternated by =org-drill='s
+  scheduler.
+- No per-entry decision burden during =gloss-add= or
+  =gloss-drill-export=.
+
+*Negative.*
+
+- Some terms make more sense one-directional. A user who saved
+  "SBIR" → "Small Business Innovation Research" probably wants
+  recognition only (acronym → expansion), not recall (expansion →
+  acronym). v1 doesn't accommodate this.
+- A future v2 may want a per-entry =:DRILL_CARD_TYPE:= override or a
+  defcustom for the default. Both are additive changes.
+
+* Alternatives Considered
+
+*=:DRILL_CARD_TYPE: simple= (term → definition only).* Rejected:
+half the value of the cards, and the user can always skip-back
+during drill if they don't want the reverse direction.
+
+*Two cards per entry, one each direction.* Rejected: doubles the
+deck size; adds maintenance burden when an entry is edited (now
+two cards diverge).
+
+*Cloze cards.* Rejected: needs a marked deletion in the body, which
+fights the "save once, drill forever" promise.
-- 
cgit v1.2.3