aboutsummaryrefslogtreecommitdiff
path: root/docs/design
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-04-30 07:55:28 -0500
committerCraig Jennings <c@cjennings.net>2026-04-30 07:55:28 -0500
commitb0d722d1a985326fb38e4e7fea237b9c4a2adcfd (patch)
tree47793265082155fe8ddacfc09d5990d7760de15a /docs/design
parent9e90517a98785c450cd13cd940bd1787a4771529 (diff)
downloadgloss-b0d722d1a985326fb38e4e7fea237b9c4a2adcfd.tar.gz
gloss-b0d722d1a985326fb38e4e7fea237b9c4a2adcfd.zip
docs: record four ADRs for gloss design decisions
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.
Diffstat (limited to 'docs/design')
-rw-r--r--docs/design/gloss.org12
1 files changed, 6 insertions, 6 deletions
diff --git a/docs/design/gloss.org b/docs/design/gloss.org
index 649eb24..c4b2e1a 100644
--- a/docs/design/gloss.org
+++ b/docs/design/gloss.org
@@ -294,14 +294,14 @@ Per-source statuses from Error Handling land here verbatim. No personal data bey
No metrics export, no telemetry, no profiling hooks — v3 territory if the package ever needs them.
-* Open Questions (will become ADRs)
+* Decisions Recorded
-Each was decided during the brainstorm. Listed for traceability; each becomes an ADR in the gloss repo's =docs/decisions/=.
+The four design decisions called out during the brainstorm are now ADRs under [[file:../decisions/][docs/decisions/]]:
-- [ ] *ADR-1: storage path default* → =(expand-file-name "gloss.org" (or org-directory user-emacs-directory))=. Rationale: respects the user's existing =org-directory= convention; falls back gracefully.
-- [ ] *ADR-2: auto-fetch on local miss* → silent fall-through with graceful network-failure path. Rationale: y/n prompt is yes 99% of the time and an annoyance the other 1%; the offline case is better handled by detecting the failure than by pre-asking permission.
-- [ ] *ADR-3: drill direction* → =:DRILL_CARD_TYPE: twosided=. Rationale: tests both recognition and recall over time without doubling the deck.
-- [ ] *ADR-4: HTML strip strategy* → =libxml-parse-html-region= (plain text only, no italic/bold preservation). Rationale: more robust than regex on edge cases; libxml2 is standard on Linux/Mac; ~30 lines.
+- [[file:../decisions/0001-storage-path-default.org][ADR-1: Storage path default]] → =(expand-file-name "gloss.org" (or org-directory user-emacs-directory))=.
+- [[file:../decisions/0002-auto-fetch-on-local-miss.org][ADR-2: Auto-fetch on local miss]] → silent fall-through with graceful network-failure path.
+- [[file:../decisions/0003-drill-direction.org][ADR-3: Drill direction]] → =:DRILL_CARD_TYPE: twosided=.
+- [[file:../decisions/0004-html-strip-strategy.org][ADR-4: HTML strip strategy]] → =libxml-parse-html-region= (plain text only, no italic/bold preservation).
* Next Steps