Update README and add documentation files for agent skills, issue tracking, and MVP details

armoutihansen · armoutihansen · commit b175aa8cf815 · 2026-05-15T20:40:41.000+02:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issues and PRDs are tracked in GitHub Issues for `armoutihansen/choicekit`. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Uses the default five-label triage vocabulary. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context repo: root `CONTEXT.md` plus root `docs/adr/`. See `docs/agents/domain.md`.
diff --git a/CONTEXT.md b/CONTEXT.md
@@ -0,0 +1,47 @@
+# choicekit
+
+choicekit is a Python package context for modeling choices from long-format random utility data. Its language distinguishes the row shape of the data from the statistical decision instances being modeled.
+
+## Language
+
+**Choice Set**:
+One observed decision instance containing two or more alternatives, exactly one of which is chosen.
+_Avoid_: Case, choice situation, group, sample
+
+**Alternative Row**:
+One long-format row representing a candidate alternative within a Choice Set.
+_Avoid_: Sample, observation
+
+**Alternative**:
+The real-world option identified within a Choice Set, which may appear across many Choice Sets.
+_Avoid_: Class, label
+
+**Chosen Alternative**:
+The Alternative Row marked as selected within a Choice Set.
+_Avoid_: Positive class
+
+**Individual**:
+An optional entity associated with one or more Choice Sets.
+_Avoid_: Person, customer, panel unit
+
+**Long-Format Choice Data**:
+Tabular data where rows are Alternative Rows and Choice Sets are represented by metadata.
+_Avoid_: Wide choice matrix
+
+## Relationships
+
+- A **Choice Set** contains two or more **Alternative Rows**.
+- A **Choice Set** has exactly one **Chosen Alternative**.
+- An **Alternative Row** refers to exactly one **Alternative**.
+- An **Individual** may be associated with zero or more **Choice Sets**.
+- **Long-Format Choice Data** represents **Choice Sets** as collections of **Alternative Rows**.
+
+## Example Dialogue
+
+> **Dev:** "Should `predict_proba` return probabilities per sample?"
+> **Domain expert:** "In this context, the rows are **Alternative Rows**. Return one probability per **Alternative Row**, normalized within each **Choice Set**."
+
+## Flagged Ambiguities
+
+- "sample" is ambiguous between a scikit-learn row and a statistical decision instance; resolved: use **Alternative Row** for rows and **Choice Set** for decision instances.
+- "class" is ambiguous with classifier labels; resolved: use **Alternative** for choice options.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
-# ChoiceKit
+# choicekit
 
-ChoiceKit is an early-stage Python package for choice modelling.
+choicekit is an early-stage Python package for choice modeling.
 
 ## Public interface
 
diff --git a/docs/adr/0001-estimator-compatibility-over-full-sklearn-integration.md b/docs/adr/0001-estimator-compatibility-over-full-sklearn-integration.md
@@ -0,0 +1,3 @@
+# Estimator compatibility over full scikit-learn integration
+
+choicekit's MVP targets scikit-learn estimator compatibility rather than full compatibility with every scikit-learn model-selection utility. `ConditionalLogit` should follow the estimator protocol through constructor parameters, cloning, learned trailing-underscore attributes, and familiar `fit`, `predict`, `predict_proba`, and `score` methods, while preserving Choice Set semantics through explicit metadata arguments. Direct `GridSearchCV` and `cross_val_score` support are deferred because forcing long-format choice data into row-wise classifier conventions would obscure the model's grouped likelihood and prediction semantics.
diff --git a/docs/adr/0002-row-aligned-predict-proba.md b/docs/adr/0002-row-aligned-predict-proba.md
@@ -0,0 +1,3 @@
+# Row-aligned predicted probabilities
+
+choicekit's MVP returns one probability per Alternative Row from `predict_proba`, aligned exactly to the input row order and normalized within each Choice Set. This deliberately deviates from scikit-learn's usual classifier shape of `(n_samples, n_classes)` because long-format choice data can have unbalanced Choice Sets, Alternatives are not ordinary classifier classes, and the natural prediction target is the probability that each Alternative Row is the Chosen Alternative.
diff --git a/docs/adr/0003-metadata-arguments-for-choice-structure.md b/docs/adr/0003-metadata-arguments-for-choice-structure.md
@@ -0,0 +1,3 @@
+# Metadata arguments for choice structure
+
+choicekit's MVP represents Choice Set, Alternative, and Individual identifiers as explicit metadata arguments rather than feature columns in `X` or a public dataset object. This keeps model features compatible with scikit-learn-style preprocessing while preventing identifiers from being accidentally estimated as numeric variables, and it leaves room for a private normalized data representation without committing to a public `ChoiceDataset` API before the core estimator semantics are proven.
diff --git a/docs/agents/domain.md b/docs/agents/domain.md
@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md
@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.
diff --git a/docs/mvp-conditional-logit.md b/docs/mvp-conditional-logit.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Estimator compatibility over full scikit-learn integration`
	`2`	`+`
	`3`	+choicekit's MVP targets scikit-learn estimator compatibility rather than full compatibility with every scikit-learn model-selection utility. `ConditionalLogit` should follow the estimator protocol through constructor parameters, cloning, learned trailing-underscore attributes, and familiar `fit`, `predict`, `predict_proba`, and `score` methods, while preserving Choice Set semantics through explicit metadata arguments. Direct `GridSearchCV` and `cross_val_score` support are deferred because forcing long-format choice data into row-wise classifier conventions would obscure the model's grouped likelihood and prediction semantics.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Row-aligned predicted probabilities`
	`2`	`+`
	`3`	+choicekit's MVP returns one probability per Alternative Row from `predict_proba`, aligned exactly to the input row order and normalized within each Choice Set. This deliberately deviates from scikit-learn's usual classifier shape of `(n_samples, n_classes)` because long-format choice data can have unbalanced Choice Sets, Alternatives are not ordinary classifier classes, and the natural prediction target is the probability that each Alternative Row is the Chosen Alternative.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Metadata arguments for choice structure`
	`2`	`+`
	`3`	+choicekit's MVP represents Choice Set, Alternative, and Individual identifiers as explicit metadata arguments rather than feature columns in `X` or a public dataset object. This keeps model features compatible with scikit-learn-style preprocessing while preventing identifiers from being accidentally estimated as numeric variables, and it leaves room for a private normalized data representation without committing to a public `ChoiceDataset` API before the core estimator semantics are proven.