88 lines
5.7 KiB
Markdown
88 lines
5.7 KiB
Markdown
# Plugin Requirements (locked, pre-build)
|
||
|
||
_Last updated: 2026-07-03_
|
||
|
||
Captured from the requirements-gathering conversation following the research phase
|
||
(`00-README.md`–`03-synthesis-and-opportunities.md`). These are decided; do not re-litigate them
|
||
in a future session without a new discussion that explicitly revisits one.
|
||
|
||
## Template decision
|
||
|
||
**One standardized template for every project, no client/tooling-mode split.** Superseding the
|
||
"two modes" option floated in `03-synthesis-and-opportunities.md` — that split was an artifact of
|
||
projects independently improvising with no shared plugin, not a real requirement. The user is not
|
||
a solo operator but works with a team of AI agents across every project; those agents need to
|
||
discover and write ADRs consistently, which a single template serves better than per-project
|
||
variants ever could.
|
||
|
||
- Customized Nygard: `Status` · `Context` · `Decision` · `Consequences` **+ `Alternatives
|
||
rejected`** as a first-class section (highest-value-per-word field per
|
||
`02-external-research.md`).
|
||
- Frontmatter: `supersedes:` / `superseded-by:`, `affected-paths:`/`affected-components:` (for
|
||
deterministic retrieval), `date`, sequential ID.
|
||
- MADR's RACI fields (Deciders/Consulted/Informed) explicitly rejected — no project run by this
|
||
user has the team-coordination problem those fields solve.
|
||
- One-file-per-decision + a mechanically-maintained index, always — including for small/client
|
||
projects. A monolithic single-file log is rejected outright for every project, not just large
|
||
ones: even a small client project's decisions log will bloat over time, and per-file+index
|
||
costs nothing extra at low decision counts (an index with 2 rows is fine).
|
||
|
||
## Location
|
||
|
||
**`docs/adr/`**, not a root-level `adr/`. Matches the actual industry convention (Nygard,
|
||
adr-tools, MADR, Log4brains, Backstage all default to `doc/adr/`/`docs/adr/`) and matches every
|
||
one of this user's own surveyed projects that already nests decision docs under `docs/`. Riding
|
||
the well-known convention matters here specifically because one goal is agent discoverability
|
||
*without* the plugin's help.
|
||
|
||
## Five requirements for the `os-adr` plugin
|
||
|
||
1. **As mechanical as possible.** Deterministic scripts/parsing/index maintenance; reserve LLM
|
||
calls for genuine judgment (classification, ambiguous field-mapping during migration,
|
||
"is this ADR-worthy" nudges). Same shape as the `os-doc-hygiene` plugin's deterministic
|
||
scanner + generative-only-where-needed split.
|
||
2. **SessionStart hook, existence-check only.** Deterministically checks whether the ADR system
|
||
already exists in the current project (path + index file check, no LLM). If present: inject
|
||
the smallest possible context note that the ADR system exists and is usable, plus how to use
|
||
it — no bloat. If absent: notify the user and suggest setting it up. Same shape as
|
||
`os-doc-hygiene`'s zero-token SessionStart reminder.
|
||
3. **Non-destructive migration, dual-existence until explicit go-ahead.** Build the new system
|
||
fresh, then convert every existing ADR (whatever shape/project it's in) into the new template
|
||
— best-guess fill-in for missing expected attributes, flagged where the guess is uncertain.
|
||
The old system stays in place, untouched, until the user explicitly approves deleting it.
|
||
Matches the build-first/migrate-incrementally precedent already set for the vault (ADR-013).
|
||
4. **Effective at *writing* — unprompted trigger recognition.** The AI should recognize on its
|
||
own, without being told directly, when a decision in progress warrants writing a new ADR.
|
||
5. **Effective at *retrieval* — unprompted, correct surfacing.** The AI should recognize on its
|
||
own, without being told directly, when an existing ADR is relevant to a task or question in
|
||
progress (including cases where the right move is "stop, this conflicts with a locked
|
||
decision, adjust the approach") — and retrieve the *correct* one, not merely *a* plausible one.
|
||
|
||
## Sequencing: eval is a distinct final stage, not folded into the build
|
||
|
||
Requirements 4 and 5 are an **evaluation methodology**, not a build task, and happen **after**
|
||
the plugin is built and the design is believed sound — not concurrently with initial design.
|
||
Sequence:
|
||
|
||
1. Build the plugin (template, hooks, migration tooling) against the requirements above.
|
||
2. Only once there's a working, believed-correct design: design held-out test scenarios —
|
||
prompts/tasks that are relevant to a written ADR but never name it or the exact constraint
|
||
directly — and check whether the AI (a) consults the ADR system unprompted at all, and
|
||
(b) retrieves the specific correct ADR, not just a plausible-looking one.
|
||
3. This eval stage uses the **`autoresearch` skill** (modify → verify → keep/discard against a
|
||
metric) to iterate on retrieval/trigger heuristics against that held-out test set.
|
||
|
||
Do not attempt to validate retrieval/write-trigger effectiveness informally during initial build
|
||
— it needs the dedicated held-out-scenario methodology above to mean anything.
|
||
|
||
## Implementation style
|
||
|
||
- **Object-oriented**, following **Sandi Metz's** approach to OOP (small classes/methods, single
|
||
responsibility, dependency injection over reaching for globals, tell-don't-ask, duck typing
|
||
over type-checking) — the user's standing preference, [[ruby-and-sandi-metz-oop-preference]].
|
||
- Language: **Ruby preferred**; **Python acceptable** where it's the more native fit for Claude
|
||
Code tooling (e.g. hook scripts invoked directly by `settings.json`, matching the existing
|
||
`os-vault`/`os-doc-hygiene` hook pattern in this repo, which are Python). Decide per-component,
|
||
not globally — a hook entry point can be a thin Python script that still delegates to an
|
||
OO-designed core, in either language, if that core is more naturally Ruby.
|