278 lines
11 KiB
Markdown
278 lines
11 KiB
Markdown
# D&D Shared Helper Refactor Implementation Plan
|
|
|
|
## Summary
|
|
|
|
Implement the target state defined in
|
|
[D&D Shared Module Helper Roadmap](dnd.md). This is an internal refactor: do not
|
|
change module keys, prompt IDs, prompt versions, Scriptorium-visible message
|
|
order, response schema IDs or names, CLI/config semantics, manifest shape,
|
|
diagnostics redaction policy, or D&D scene/spell interpretation behavior.
|
|
|
|
The intended package split is:
|
|
|
|
- `internal/modules/sharedassets`: generic prompt filesystem composition and
|
|
non-domain-specific asset plumbing only;
|
|
- `internal/modules/sharedassets/dnd`: reusable D&D prompt assets, prompt input
|
|
helpers, reference slot helpers, reference rendering, and D&D shared prompt
|
|
hash parts;
|
|
- concrete D&D modules: stage contracts, module registration, module-local
|
|
prompt definitions, response schemas, validators, and response
|
|
interpretation.
|
|
|
|
## Stage 1: Add Generic Defensive-Copy Helper
|
|
|
|
- Add `CloneReferenceSlots` to `internal/framework/contracts`.
|
|
- The helper must:
|
|
- return `nil` for an empty input slice;
|
|
- allocate a new slot slice;
|
|
- deep-copy each `AcceptedMediaTypes` slice;
|
|
- preserve all other `ReferenceSlot` fields exactly.
|
|
- Add focused tests in `internal/framework/contracts` proving nil/empty
|
|
behavior, deep-copy behavior, and full field preservation.
|
|
- Do not import any concrete module package from `contracts`.
|
|
|
|
## Stage 2: Make Shared Prompt FS Composition Domain-Neutral
|
|
|
|
- Refactor `internal/modules/sharedassets.ModulePromptFS` so the parent package
|
|
no longer knows about D&D prompt filenames or embedded D&D assets.
|
|
- Add a generic shared prompt file descriptor:
|
|
|
|
```go
|
|
type SharedPromptFile struct {
|
|
Name string
|
|
FS fs.FS
|
|
Path string
|
|
}
|
|
```
|
|
|
|
- Change `ModulePromptFS` to this shape:
|
|
|
|
```go
|
|
func ModulePromptFS(
|
|
moduleDir string,
|
|
moduleFS fs.FS,
|
|
files []ModulePromptFile,
|
|
sharedFiles ...SharedPromptFile,
|
|
) (fs.FS, error)
|
|
```
|
|
|
|
- Keep existing `ModulePromptFile` semantics:
|
|
- `Name` is mounted directly under `assets/prompts/<moduleDir>/`;
|
|
- `Path` is read from the module embedded filesystem.
|
|
- Mount each `SharedPromptFile` under
|
|
`assets/prompts/<moduleDir>/sharedassets/<Name>`.
|
|
- Validate all names and paths with contextual errors:
|
|
- `moduleDir` must be a valid non-root fs path;
|
|
- module prompt `Name` must be a single filename with no path separators;
|
|
- shared prompt `Name` must be a single filename with no path separators;
|
|
- `moduleFS` and each shared file `FS` must be non-nil;
|
|
- missing module or shared files must return errors naming the source path.
|
|
- Preserve the in-memory FS behavior currently covered by tests, including
|
|
readable intermediate directories and root `.` support.
|
|
- Update `internal/modules/sharedassets` tests so they use test-owned shared
|
|
prompt files from `fstest.MapFS`, not production D&D prompt assets.
|
|
- Remove D&D-specific helpers, constants, and embedded asset dependencies from
|
|
the parent `sharedassets` package.
|
|
|
|
## Stage 3: Create `sharedassets/dnd`
|
|
|
|
- Create `internal/modules/sharedassets/dnd` with package name `dnd`.
|
|
- Move the current D&D shared prompt files into:
|
|
|
|
```text
|
|
internal/modules/sharedassets/dnd/assets/prompts/common-dnd-system.md
|
|
internal/modules/sharedassets/dnd/assets/prompts/common-dnd-transcript.md
|
|
internal/modules/sharedassets/dnd/assets/prompts/common-dnd-references.md
|
|
```
|
|
|
|
- Add `assets.go` in the D&D package with `go:embed assets/prompts/*.md`.
|
|
- Expose D&D shared asset helpers:
|
|
|
|
```go
|
|
func SharedPromptFiles() []sharedassets.SharedPromptFile
|
|
func CommonHashParts() []llm.AssetHashPart
|
|
func ReferenceHashParts() []llm.AssetHashPart
|
|
func ModulePromptFS(moduleDir string, moduleFS fs.FS, files []sharedassets.ModulePromptFile) (fs.FS, error)
|
|
```
|
|
|
|
- `SharedPromptFiles` must return a new slice each call.
|
|
- `CommonHashParts` must include `common-dnd-system.md` and
|
|
`common-dnd-transcript.md`.
|
|
- `ReferenceHashParts` must include `common-dnd-references.md`.
|
|
- `ModulePromptFS` must call `sharedassets.ModulePromptFS` with
|
|
`SharedPromptFiles()...`.
|
|
- Do not expose a D&D package registration function unless a concrete caller
|
|
needs top-level D&D shared prompt files outside module-local prompt
|
|
composition. The D&D prompt definitions should continue to load shared files
|
|
through `./sharedassets/...` inside each module prompt directory.
|
|
|
|
## Stage 4: Add D&D Reference And Prompt Input Helpers
|
|
|
|
- In `internal/modules/sharedassets/dnd`, add D&D reference helpers:
|
|
|
|
```go
|
|
type ReferenceSlotDescriptions struct {
|
|
Glossary string
|
|
Party string
|
|
Players string
|
|
Roster string
|
|
}
|
|
|
|
func ReferenceMediaTypes() []string
|
|
func ReferenceSlots(descriptions ReferenceSlotDescriptions) []contracts.ReferenceSlot
|
|
```
|
|
|
|
- `ReferenceMediaTypes` must return a defensive copy of:
|
|
- `application/json`
|
|
- `application/x-yaml`
|
|
- `application/yaml`
|
|
- `text/markdown`
|
|
- `text/plain`
|
|
- `ReferenceSlots` must return slots in the same order currently exposed by
|
|
both D&D modules: `glossary`, `party`, `players`, `roster`.
|
|
- Slot names and alias semantics must remain unchanged.
|
|
- Slot descriptions should be supplied by each concrete module through
|
|
`ReferenceSlotDescriptions` so current module metadata text can be preserved.
|
|
- `ReferenceSlots` must use `contracts.CloneReferenceSlots` or equivalent
|
|
defensive-copy behavior before returning.
|
|
|
|
- Add prompt input helpers:
|
|
|
|
```go
|
|
func PromptInputs(sourceInput contracts.LLMInputMaterial, references contracts.ReferenceSet) contracts.LLMInputSet
|
|
func TranscriptPromptMaterial(material contracts.LLMInputMaterial) contracts.LLMInputMaterial
|
|
func ReferencePromptMaterial(name string, slot contracts.ResolvedReferenceSlot) contracts.LLMInputMaterial
|
|
func ReferencePromptInput(slot contracts.ResolvedReferenceSlot) []byte
|
|
```
|
|
|
|
- `PromptInputs` must return inputs named `transcript`, `players`, `party`, and
|
|
`glossary`.
|
|
- If `party` has no items and `roster` has items, `PromptInputs` must use the
|
|
`roster` slot content for the `party` input.
|
|
- `PromptInputs` must not include a `roster` prompt input.
|
|
- `TranscriptPromptMaterial` must clone the source input and set `Name` to
|
|
`transcript`.
|
|
- `ReferencePromptMaterial` must use media type `text/plain`; for a single
|
|
reference item it must propagate that item's digest and origin URI.
|
|
- `ReferencePromptInput` behavior must match current D&D module behavior:
|
|
- empty slot renders as a single space;
|
|
- one item renders as raw item content;
|
|
- multiple items are copied, sorted deterministically by origin URI, digest,
|
|
then content, and rendered with the same heading/metadata format currently
|
|
used by `dnd/scenes` and `dnd/spells`.
|
|
|
|
- Add focused tests under `internal/modules/sharedassets/dnd` for all helper
|
|
behavior. These tests may assert rendering of helper-owned fixture inputs, but
|
|
must not assert exact production embedded prompt prose.
|
|
|
|
## Stage 5: Update D&D Modules To Use Shared Helpers
|
|
|
|
- Update `internal/modules/chunk/dnd/scenes`:
|
|
- import `internal/modules/sharedassets/dnd`;
|
|
- replace local accepted media type and slot cloning logic with
|
|
`dnd.ReferenceSlots`;
|
|
- preserve existing scene-specific slot descriptions;
|
|
- replace local prompt input/reference rendering helpers with
|
|
`dnd.PromptInputs`;
|
|
- replace `sharedassets.ModulePromptFS` with `dnd.ModulePromptFS`;
|
|
- replace `sharedassets.CommonHashParts` and `ReferenceHashParts` with the
|
|
D&D package equivalents.
|
|
- Update `internal/modules/extract/dnd/spells` the same way, preserving current
|
|
extractor-specific slot descriptions.
|
|
- Delete local duplicated helper functions that become unused:
|
|
- `acceptedReferenceMediaTypes`;
|
|
- `cloneReferenceSlots`;
|
|
- `transcriptPromptInput`;
|
|
- `referencePromptMaterial`;
|
|
- `referencePromptInput`.
|
|
- Keep module-local schema loading, prompt IDs, prompt versions, validators,
|
|
request validation, response conversion, and manifest metadata ownership in
|
|
each concrete module.
|
|
|
|
## Stage 6: Update Asset Registration And Tests
|
|
|
|
- Update production prompt asset registration in `internal/cli` as needed:
|
|
- remove any call that registers D&D shared prompt files from the generic
|
|
`sharedassets` package;
|
|
- ensure `dnd/scenes` and `dnd/spells` prompt registration still makes their
|
|
module-local `./sharedassets/common-dnd-*.md` files available.
|
|
- Update production prompt asset tests so they assert module-local shared asset
|
|
paths such as:
|
|
- `dnd.scenes/sharedassets/common-dnd-system.md`
|
|
- `dnd.spells/sharedassets/common-dnd-system.md`
|
|
- Remove expectations for top-level `common-dnd-*.md` prompt files unless a
|
|
genuine top-level registration remains necessary.
|
|
- Move reference rendering tests from concrete D&D modules into
|
|
`internal/modules/sharedassets/dnd`.
|
|
- Keep concrete D&D module tests focused on:
|
|
- module specs and registry behavior;
|
|
- LLM request prompt ID/version/profile/session fields;
|
|
- transcript and reference input propagation;
|
|
- Scriptorium prompt preparation;
|
|
- diagnostics redaction;
|
|
- manifest metadata;
|
|
- scene/spell response interpretation.
|
|
- Follow the prompt asset testing policy in `docs/policy/development.md`: do
|
|
not assert exact production embedded prompt prose.
|
|
|
|
## Stage 7: Update Documentation
|
|
|
|
- Update canonical internal docs for implemented behavior:
|
|
- `docs/internal/modules.md`: mention that common D&D prompt/reference helper
|
|
behavior lives under `internal/modules/sharedassets/dnd`;
|
|
- `docs/internal/overview.md`: mention the package only if the overview lists
|
|
shared module-support packages.
|
|
- Do not add user-facing documentation unless visible behavior changes.
|
|
- Update `docs/roadmap/dnd.md` after implementation so it no longer presents
|
|
this refactor as future work.
|
|
- Replace this file with a concise completed-note document once the work is
|
|
implemented.
|
|
|
|
## Validation
|
|
|
|
Run focused tests after each meaningful stage:
|
|
|
|
```sh
|
|
go test ./internal/framework/contracts
|
|
go test ./internal/modules/sharedassets
|
|
go test ./internal/modules/sharedassets/dnd
|
|
go test ./internal/modules/chunk/dnd/scenes
|
|
go test ./internal/modules/extract/dnd/spells
|
|
go test ./internal/cli
|
|
```
|
|
|
|
Run full validation before completion:
|
|
|
|
```sh
|
|
go test ./...
|
|
go vet ./...
|
|
go build ./cmd/notarius
|
|
```
|
|
|
|
Run inspection searches:
|
|
|
|
```sh
|
|
rg -n "common-dnd|CommonHashParts|ReferenceHashParts|referencePromptInput|cloneReferenceSlots|acceptedReferenceMediaTypes" internal/modules internal/framework
|
|
rg -n "Divide the provided transcript|Extract Dungeons & Dragons spell-cast artifacts|A transcript of a Dungeons & Dragons gameplay session|Roster reference|Glossary reference" internal/**/*_test.go
|
|
```
|
|
|
|
Expected inspection outcomes:
|
|
|
|
- D&D shared prompt files and hash helpers are owned by
|
|
`internal/modules/sharedassets/dnd`;
|
|
- parent `sharedassets` has no hard-coded `common-dnd-*` knowledge;
|
|
- concrete D&D modules no longer carry duplicated reference rendering logic;
|
|
- tests do not assert exact production embedded prompt prose.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not change D&D prompt wording except for file moves required by this
|
|
refactor.
|
|
- Do not change prompt IDs, prompt versions, profile defaults, Scriptorium
|
|
message order, schema files, schema metadata, module keys, capabilities,
|
|
manifest shapes, or diagnostics policy.
|
|
- Do not move scene boundary logic, spell artifact logic, validators, or schema
|
|
loading into the shared D&D package.
|
|
- Do not make framework, core, or CLI packages depend on
|
|
`internal/modules/sharedassets/dnd`.
|