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 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. 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.

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.
Decide and test whether one Engine supports concurrent Prepare and Run calls.
Decide how repeated options of the same category behave, including prompt, profile, schema, model-client, and artifact-reader options.
Define which public values have supported JSON representations.
Define JSON time units and omission behavior, including the relationship between prepared-run and run-result durations.
Decide whether run IDs and exposed hashes have stable formats or must be treated as opaque values.
Confirm the intended transport-timeout default and its zero or negative configuration semantics.
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.

Add useful field-level GoDoc to configuration, request, profile, execution-target, result, artifact, validation, structured-output, and model client values.
Document required fields and nil, empty, and zero-value semantics.
Document override, replacement, profile-precedence, and copy-ownership behavior where it belongs to the exported API.
Document credential inputs, redaction, and the values intentionally excluded from serialization.
Give each public error sentinel an accurate comment and document the supported errors.Is relationships.
Document engine concurrency and option-composition behavior selected in Stage 1.
Document serialization, time, run-ID, and hash semantics selected in Stage 1.
Review constructor, option, extension-interface, Prepare, and Run GoDoc for complete failure and cancellation expectations.

Update the consumer guide 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.

The preparation and execution examples remain separate, self-contained workflows. Each keeps its own small prompt fixture so consumers can copy or run one example without depending on the other.

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 to durable boundaries, layers, dependency direction, invariants, and non-goals.
Keep the exact implemented package and component inventory solely in the internal component overview.
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, testing policy, and release procedure 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.

11 KiB Raw Blame History