219 lines
11 KiB
Markdown
219 lines
11 KiB
Markdown
# Documentation Hardening Roadmap
|
|
|
|
## Purpose
|
|
|
|
This roadmap coordinates a focused pass over Promptkit's documentation and
|
|
public contract. The work should close the gaps identified by the documentation
|
|
audit, strengthen canonical ownership, and leave consumers and contributors
|
|
with guidance that is accurate, navigable, and proportionate to their needs.
|
|
|
|
This is planning material, not a description of implemented behavior. Follow
|
|
the [documentation policy](../policy/documentation.md) throughout the work and
|
|
update current-state documents only when their claims are supported by the
|
|
implementation and tests.
|
|
|
|
## Scope And Principles
|
|
|
|
The work covers public GoDoc, consumer guidance, maintained examples, format
|
|
and integration references, architecture ownership, roadmap lifecycle, and
|
|
documentation validation.
|
|
|
|
- Resolve ambiguous behavior before documenting it as a contract.
|
|
- Keep exact exported API semantics in Go declarations and GoDoc.
|
|
- Keep task-oriented guidance in consumer documents and complete runnable
|
|
artifacts in `examples/`.
|
|
- Put security-relevant consumer responsibilities at the public boundary, not
|
|
only in internal contributor documents.
|
|
- Remove duplicated ownership instead of synchronizing parallel references.
|
|
- Make documentation checks reproducible where practical.
|
|
- Preserve existing behavior unless a stage explicitly selects and tests an
|
|
API change.
|
|
|
|
The roadmap does not add new Promptkit features, redesign framework formats,
|
|
or implement ideas from [the future feature catalog](future.md). If resolving
|
|
an ambiguity requires a behavioral change, treat that change as a separately
|
|
reviewable implementation unit and update its canonical documentation in the
|
|
same unit.
|
|
|
|
## Stage 1: Resolve Public Contract Questions
|
|
|
|
Before expanding prose, decide the intended contract for exported behavior
|
|
that is currently ambiguous.
|
|
|
|
- [x] Decide whether `RunRequest.Metadata` has a supported observable purpose.
|
|
Define its propagation and ownership, or remove or deprecate it through an
|
|
intentional public API change.
|
|
- [x] Decide and test whether one `Engine` supports concurrent `Prepare` and
|
|
`Run` calls.
|
|
- [x] Decide how repeated options of the same category behave, including
|
|
prompt, profile, schema, model-client, and artifact-reader options.
|
|
- [x] Define which public values have supported JSON representations.
|
|
- [x] Define JSON time units and omission behavior, including the relationship
|
|
between prepared-run and run-result durations.
|
|
- [x] Decide whether run IDs and exposed hashes have stable formats or must be
|
|
treated as opaque values.
|
|
- [x] Confirm the intended transport-timeout default and its zero or negative
|
|
configuration semantics.
|
|
- [x] Confirm the supported JSON Schema dialect and reference boundaries,
|
|
including whether remote references are allowed.
|
|
|
|
The selected exported API contracts are implemented and tested. Their durable
|
|
definitions now belong to the root package declarations and GoDoc.
|
|
|
|
One format-level decision remains here until Stage 5 moves it to the framework
|
|
format reference: JSON Schema uses Draft 2020-12, with that dialect selected
|
|
when `$schema` is omitted. Same-document fragments and relative references
|
|
contained by a directory or `fs.FS` schema root are supported. A single-file
|
|
source supports only references contained in that document. Absolute,
|
|
escaping, and remote references are rejected.
|
|
|
|
**Gate:** Each question has an explicit answer backed by existing behavior or
|
|
by an accepted implementation change and proportionate tests. No later stage
|
|
should invent a contract merely to fill a documentation gap.
|
|
|
|
## Stage 2: Make GoDoc The Canonical Public Contract
|
|
|
|
Strengthen the root package declarations so `go doc` is sufficient to
|
|
understand exact public behavior without relying on internal documents.
|
|
|
|
- [x] Add useful field-level GoDoc to configuration, request, profile,
|
|
execution-target, result, artifact, validation, structured-output, and model
|
|
client values.
|
|
- [x] Document required fields and nil, empty, and zero-value semantics.
|
|
- [x] Document override, replacement, profile-precedence, and copy-ownership
|
|
behavior where it belongs to the exported API.
|
|
- [x] Document credential inputs, redaction, and the values intentionally
|
|
excluded from serialization.
|
|
- [x] Give each public error sentinel an accurate comment and document the
|
|
supported `errors.Is` relationships.
|
|
- [x] Document engine concurrency and option-composition behavior selected in
|
|
Stage 1.
|
|
- [x] Document serialization, time, run-ID, and hash semantics selected in
|
|
Stage 1.
|
|
- [x] Review constructor, option, extension-interface, `Prepare`, and `Run`
|
|
GoDoc for complete failure and cancellation expectations.
|
|
|
|
Update the [consumer guide](../consumers/pkg-promptkit.md) to summarize and link
|
|
to these contracts instead of maintaining exhaustive copies of exported names
|
|
or exact semantics.
|
|
|
|
**Gate:** `go doc -all .` presents a coherent public contract, exported
|
|
declarations have accurate comments, and contract tests protect every newly
|
|
documented behavior whose compatibility risk warrants durable coverage.
|
|
|
|
## Stage 3: Improve Consumer Safety And Executable Guidance
|
|
|
|
Move consumer-relevant security boundaries to the places where consumers will
|
|
encounter them and add one representative execution workflow.
|
|
|
|
- [ ] Explain in public GoDoc and the consumer guide that the default file
|
|
artifact reader accepts unrestricted caller-selected paths.
|
|
- [ ] Make clear that Promptkit does not impose an application root, inbound
|
|
request-size policy, or untrusted-input security boundary.
|
|
- [ ] Explain that rendered messages, artifact bodies, raw model output, and
|
|
validation details may be sensitive even when credentials are redacted.
|
|
- [ ] Clarify the responsibilities of injected artifact readers and model
|
|
clients for cancellation, copying, logging, and secret handling.
|
|
- [ ] Add a maintained offline `Run` example using an injected deterministic
|
|
model client, without credentials, live network access, or paid calls.
|
|
- [ ] Link the consumer guide to the execution example and keep embedded
|
|
snippets smaller than the maintained artifact.
|
|
- [ ] Decide whether the existing preparation example should remain separate
|
|
or share reusable fixtures without obscuring either workflow.
|
|
|
|
**Gate:** Both preparation and execution have complete, secret-free,
|
|
deterministic consumer examples, and the consumer guide exposes the important
|
|
filesystem and data-sensitivity boundaries without leaking internal mechanics.
|
|
|
|
## Stage 4: Restore Canonical Ownership
|
|
|
|
Remove parallel definitions and make navigation follow the ownership model in
|
|
the documentation policy.
|
|
|
|
- [ ] Reduce the [architecture policy](../policy/architecture.md) to durable
|
|
boundaries, layers, dependency direction, invariants, and non-goals.
|
|
- [ ] Keep the exact implemented package and component inventory solely in the
|
|
[internal component overview](../internal/overview.md).
|
|
- [ ] Review the consumer guide's public error and option lists so they remain
|
|
task-oriented summaries rather than duplicate API references.
|
|
- [ ] Review internal documents for public-contract statements that should be
|
|
links to GoDoc or the format and integration owners.
|
|
- [ ] Reconcile the documentation policy's temporary-roadmap lifecycle with
|
|
the continuing idea-catalog role of `docs/roadmap/future.md`.
|
|
- [ ] Rephrase or link roadmap statements that depend on exact current API
|
|
behavior, particularly the runtime reasoning entry.
|
|
- [ ] Confirm that every document states its audience or purpose and links to
|
|
the canonical owner of adjacent topics.
|
|
|
|
**Gate:** Every authoritative fact has one clear owner, package inventory
|
|
changes no longer require edits to the architecture policy, and roadmaps
|
|
cannot be mistaken for current-state references.
|
|
|
|
## Stage 5: Refine Format And Integration References
|
|
|
|
Close compatibility gaps in the documents that own file formats and outbound
|
|
wire behavior.
|
|
|
|
- [ ] State or canonically link the exact session-ID limit enforced by the
|
|
OpenAI-compatible client.
|
|
- [ ] State the configured and default transport-timeout behavior without
|
|
referring to an unnamed internal default.
|
|
- [ ] Document the JSON Schema dialect and local, contained, and remote
|
|
reference behavior selected in Stage 1.
|
|
- [ ] Clarify structured-output naming and strictness when those values are
|
|
part of the public or integration contract.
|
|
- [ ] Add a caveat that built-in profiles are maintained configurations, not a
|
|
guarantee of continuing third-party model availability.
|
|
- [ ] Recheck every prompt, profile, schema, credential, request-body, response,
|
|
timeout, and precedence statement against its owning implementation and
|
|
tests.
|
|
|
|
**Gate:** A consumer can determine the supported file and wire compatibility
|
|
boundaries without consulting internal source code or relying on unspecified
|
|
defaults.
|
|
|
|
## Stage 6: Make Documentation Validation Reproducible
|
|
|
|
Align contributor and release procedures around a small, consistent set of
|
|
checks.
|
|
|
|
- [ ] Use one robust command for checking every tracked Go file with `gofmt`.
|
|
- [ ] Provide a repository-local or clearly documented command that validates
|
|
local Markdown targets and heading fragments.
|
|
- [ ] Decide how published external links are checked without making ordinary
|
|
validation depend on mutable network services.
|
|
- [ ] Reconcile the validation descriptions in the
|
|
[development guide](../development.md),
|
|
[testing policy](../policy/testing.md), and
|
|
[release procedure](../release.md) so one document owns each requirement.
|
|
- [ ] Ensure example validation covers every maintained example added by this
|
|
roadmap.
|
|
- [ ] Keep documentation-only validation proportionate while requiring full Go
|
|
validation when commands, examples, generated output, or checked behavior
|
|
changes.
|
|
|
|
**Gate:** A maintainer can run the documented formatting, link, example, Go,
|
|
and repository-hygiene checks exactly as written, with no hidden manual
|
|
procedure for local documentation.
|
|
|
|
## Completion Criteria
|
|
|
|
The roadmap is complete when:
|
|
|
|
- all Stage 1 contract questions are resolved;
|
|
- GoDoc is the authoritative and sufficient exported API reference;
|
|
- consumer guidance covers unrestricted file access and sensitive generated
|
|
data;
|
|
- maintained offline examples cover both `Prepare` and `Run`;
|
|
- architecture, inventory, consumer, internal, format, integration, and
|
|
roadmap documents follow their assigned ownership boundaries;
|
|
- schema, session, timeout, structured-output, and built-in-profile
|
|
compatibility statements are explicit;
|
|
- documentation validation is reproducible and consistent across contributor
|
|
and release workflows; and
|
|
- the complete maintainer validation passes.
|
|
|
|
After completion, move any durable decisions to GoDoc, policy, format,
|
|
integration, or ADR owners as appropriate. Remove this roadmap after incoming
|
|
links are updated; do not retain it as a second current-state reference.
|