From 3e7acb2b51b2a1c5c6a1917ba9efb1b1b1ccd813 Mon Sep 17 00:00:00 2001
From: "M.V. Hutz" <git@maximhutz.me>
Date: Sun, 5 Jul 2026 01:27:00 +0000
Subject: [PATCH] docs(adr): adr template, design principles adr (#26)

## Description

We need a more directed approach to `go-cuckoo`'s interface.
This ADR proposes that direction.

## Changes

- Add ADR template.
- Add "Adopt Congruent and Familiar Design For `go-cuckoo`" ADR.

## Design Decisions

- ~~Put ADRs under `adr/` for more. Because we don't realy have any docs right now, it doesn't make much sense to nest it.~~

## Checklist

- [x] Tests pass
- [x] Docs updated

Reviewed-on: https://git.maximhutz.com/tools/go-cuckoo/pulls/26
Co-authored-by: M.V. Hutz <git@maximhutz.me>
Co-committed-by: M.V. Hutz <git@maximhutz.me>
---
 docs/adr/000_template.md          | 15 ++++++++++
 docs/adr/001_design_principles.md | 46 +++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 docs/adr/000_template.md
 create mode 100644 docs/adr/001_design_principles.md

diff --git a/docs/adr/000_template.md b/docs/adr/000_template.md
new file mode 100644
index 0000000..3bf9789
--- /dev/null
+++ b/docs/adr/000_template.md
@@ -0,0 +1,15 @@
+# Title
+
+**Status**: <!-- Proposed, accepted, rejected, etc... -->
+
+## Context
+
+<!-- What is the issue that we're seeing that is motivating this decision or change? -->
+
+## Decision
+
+<!-- What is the change that we're proposing and/or doing? -->
+
+## Consequences
+
+<!-- What becomes easier or more difficult to do because of this change? -->
diff --git a/docs/adr/001_design_principles.md b/docs/adr/001_design_principles.md
new file mode 100644
index 0000000..8ca4744
--- /dev/null
+++ b/docs/adr/001_design_principles.md
@@ -0,0 +1,46 @@
+# Adopt Parity and Consistency as Principles For `go-cuckoo`
+
+**Status**: Accepted
+
+## Context
+
+I built `go-cuckoo`'s API interface without design intent.
+Up until now, I paid more attention implementing the underlying functionality of the cuckoo hashing.
+With the fundamentals of the algorithm built, I should revisit the interface.
+
+The goal of this project was to create an implementation of cuckoo hashing, while adhering to Go's idioms, and being as usable as possible.
+While the implementation does work, it lacks direction.
+
+## Decision
+
+To resolve this, I'm enforcing two new principles onto the contract of `go-cuckoo`:
+
+- **Parity (with `map`)**:
+  A `go-cuckoo` table should have the same core functionality as `map`.
+  By 'core', I mean `map`'s built-in syntax and functions (e.g. `range`, `m[k]`), and the `maps` package.
+  Higher parity means users can trust that `go-cuckoo` can do what `map` can do.
+
+- **Consistency (with `map`)**:
+  A `go-cuckoo` table should behave similarly to `map`, so users will intuitively know how to use it.
+  Higher consistency lowers the cognitive load users must carry.
+
+While these principles should guide the interface of `go-cuckoo`, they should not be absolute.
+The behavior of `go-cuckoo` is distinct from `map` (e.g. `Put` can fail; see `ErrBadHash`), so do not equate them.
+
+## Consequences
+
+1. The repository should contain a living document, describing the interface differences between `go-cuckoo` and `map`.
+   I should prioritize limiting any disparity.
+   (I already started work on branch `docs/interface-congruency-analysis`.)
+   - [ ] Produce the first draft to uncover any current disparity.
+   - [ ] Link the document to the `README.md`.
+2. Analyze the consistency of `go-cuckoo`'s current interface.
+   Unlike the analysis of parity, this should be a one time document.
+   Consistency is implicit to users, and does not need to be referenced.
+   But, any rationale should be documented in commit messages, or future ADRs.
+   - [ ] Produce the analysis document.
+   - [ ] Resolve any issues found.
+3. The repository should support both design principles.
+   As I resolve gaps in parity and consistency, I should feed any reusable heuristics back into the contributing guide.
+   - [ ] State these principles in the `README.md` and `doc.go`.
+   - [ ] Ground the contributing guide and pull request template in these new principles.