promptkit/docs/policy/documentation.md

Documentation Policy

Base Policy Version: 1.1

Last Updated: 2026-09-23

Purpose

This policy assigns each Promptkit documentation topic to one canonical owner. Its goal is to keep documentation for this reusable Go library accurate, concise, discoverable, and resistant to drift for consumers, contributors, maintainers, integrators, and coding agents.

Core Rules

One Canonical Owner

Each authoritative fact belongs in one document or source form. A non-owning document may give a short, stable summary for orientation, but it must link to the canonical owner instead of repeating exact contracts.

Volatile details include exported declarations, accepted inputs, defaults, schemas, file names, paths, error identities, retry behavior, and runtime guarantees. If readers could reasonably treat a statement as a contract, maintain its exact definition only in the owning source.

Current State, Decisions, And Future Work

Outside docs/roadmap/, documentation describes implemented behavior only. Partial features may be described only to their implemented boundary.

An accepted architecture decision may describe an approved direction before it is implemented, but acceptance is not evidence that the behavior exists. Current-state documents change when the implementation lands. Temporary roadmaps own future work, sequencing, and implementation status; they do not replace durable policies or current contracts.

Audience And Detail

Write for the document's stated audience and include only the detail needed for its owned topic. Consumer guidance should not expose incidental implementation detail. Contributor documentation should link to public contracts and durable policies instead of restating them.

Links

Use descriptive link text and repository-relative links for repository documents. Link to the canonical owner rather than to a duplicate summary. Check every added or changed link and repair or remove links when their target moves or is retired.

Examples And Code Fences

Complete copyable files belong in examples/ when maintained examples exist. Documentation may use the smallest illustrative snippet needed for its owned topic, but should link to a maintained example instead of embedding a second complete copy.

Examples must be valid, secret-free, and tested where practical. Commands, imports, and Go snippets must match the implemented library. Use a language tag on fenced code blocks and make clear when a fragment is illustrative rather than directly runnable.

Security And Privacy

Documentation and examples must not contain real credentials, private keys, private environment dumps, sensitive source material, or private infrastructure details unless intentionally public. Document secret-handling mechanisms, not secret values.

Canonical Ownership

Topic	Canonical owner	Owned content	Content owned elsewhere
Project orientation	README.md	What Promptkit is, its current usability, module identity, license summary, a minimal successful quickstart, and links onward.	Exact API contracts, contributor procedures, architecture detail, and release steps.
Contributor workflow	docs/development.md	Task-oriented reading guide, local workflow, validation commands, and repository hygiene.	Architecture rules, API semantics, subsystem behavior, and release procedure.
Current architecture	docs/policy/architecture.md	System shape, normative ownership, dependency direction, package boundaries, invariants, and non-goals.	Concrete component inventory, implementation mechanics, contributor procedures, decision history, and future work.
Agent policy	docs/policy/agents.md	Agent implementation discipline, proportionality, idiomatic simplicity, local commit authorization and discipline, and rules against inventing restrictions, guarantees, or repository policy.	Public contracts, architecture, testing, and contributor procedures.
Documentation organization	docs/policy/documentation.md	Documentation ownership, audience boundaries, maintenance rules, and document lifecycle.	Library architecture or runtime behavior.
Testing policy	docs/policy/testing.md	Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression policy, and test maintenance.	Subsystem behavior, exact public contracts, subsystem-specific test inventories, and implementation plans.
Release policy	docs/policy/release.md	Versioning, compatibility, release-note requirements, validation obligations, immutability, recovery, and adoption scope.	Executable commands, publication mechanics, and historical release summaries.
Release procedure	docs/release.md	Maintainer prerequisites, candidate preparation, concrete publication guards and commands, verification, and recovery steps.	Release-policy requirements, public API semantics, and historical summaries.
Exact exported Go API	Go declarations and GoDoc, as APIs are implemented	Exported names, signatures, types, values, errors, and exact behavioral contracts.	Task-oriented consumer walkthroughs, implementation details, and future API proposals.
Framework file formats	docs/formats.md	Prompt-definition and profile YAML fields, schema references, defaults, validation modes, built-in profiles, credentials, and file-to-request precedence.	Exported Go declarations, outbound wire behavior, internal parsing mechanics, and application configuration.
Consumer guidance	docs/consumers/, when consumer workflows require dedicated guidance	Task-oriented use of implemented public APIs, minimal examples, and consumer responsibilities.	Exact exported declarations and internal mechanics.
Durable integration contracts	docs/integrations/, when integrations exist	External formats and protocols, compatibility behavior, and upstream or downstream responsibilities.	Internal transformations and public Go declarations.
Release-note history	docs/releases/	Mandatory version-matched historical summaries for releases made under the adopted release policy; the note at the immutable tag records that release.	Current APIs, behavior, formats, compatibility contracts, and release procedures.
Implemented component inventory	docs/internal/overview.md	Current packages and components, their implemented responsibilities, and links to focused internal documents.	Normative architecture, contributor workflow, external contracts, and proposed components.
Internal subsystem behavior	Other files under docs/internal/, when a subsystem needs durable detail	Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests.	Global architecture invariants, public API definitions, and future package plans.
Architectural decision history	docs/adr/, when repository-local decisions require records	Significant decisions, context, alternatives, rationale, consequences, and supersession history.	Current behavior reference, implementation status, and task sequencing.
Temporary feature roadmaps	docs/roadmap/, while planned work needs coordination	Proposed or accepted scope, sequencing, gates, and implementation status.	Implemented behavior reference and durable decision rationale.
Complete copyable artifacts	examples/	Valid inputs, Go programs, and other files intended to be copied or run.	Field-by-field reference, exact API declarations, and prose explanation.

Conditional owners do not require placeholder files or directories. Create a consumer, integration, release, subsystem, ADR, roadmap, or example document only when the corresponding implemented interface, release, decision, planned effort, or maintained artifact exists.

Boundary Rules

Orientation

The README owns project orientation. The development guide routes contributors. Architecture owns normative structure. The internal overview owns the current concrete component map. These documents may link to one another but must not maintain parallel package or behavior descriptions.

Public Contracts And Implementation

Go declarations and GoDoc own exact exported API contracts once those APIs exist. Consumer and integration documents explain how to use those contracts for a task. Internal documents explain how Promptkit implements them. Internal documentation may identify a public type or external format as a dependency, but must link to its canonical definition rather than restate it.

The framework format reference owns exact prompt, profile, and schema-file contracts. Integration documents own external wire formats.

Release Documentation

The release policy owns release requirements; the repository release procedure owns their concrete execution. Version-matched checked-in notes are required for future releases under that policy. The source tag is the release identity, and the note in its immutable tree is the historical summary; annotated tag messages complement that record.

Release notes do not own current API or behavior contracts. Link to the canonical owners for details instead of reproducing those contracts. Published notes are not disposable guidance and must not be replaced under the same version. Corrections belong in a subsequent release.

Adoption is prospective. Previously published tags and historical notes retain their original records and are not reformatted or rewritten to satisfy the new requirements.

Security Topics

This policy owns what documentation and examples may contain. Architecture owns library security boundaries and invariants. Public declarations and integration documents own consumer-visible security contracts. Internal documents own implementation mechanisms only.

Architecture Decision Records

Use sequentially numbered ADR filenames such as 0001-record-architecture-decisions.md. Follow the lightweight Nygard format:

1. title;
2. status;
3. date;
4. context;
5. decision;
6. alternatives considered;
7. consequences.

Use one of these statuses:

• Proposed: the decision is under consideration and may change;
• Accepted: the decision is approved, whether or not implementation is complete;
• Rejected: the proposed decision was considered and not adopted;
• Superseded: a later accepted ADR replaces the accepted decision.

A proposed ADR transitions to Accepted or Rejected. An Accepted ADR transitions to Superseded only when a later Accepted ADR replaces it. An ADR may be created as Accepted when the decision has already been made.

Treat the decision content of an Accepted ADR as immutable. A changed decision requires a later ADR rather than a rewrite of the accepted record. A Superseded ADR must link to its replacement, and the replacement must link back. Rejected architectural alternatives belong in the ADR; rejected feature ideas belong in a roadmap when they need to be retained.

Document Lifecycle

Create durable current-state documentation with the implementation it describes. Update its canonical owner in the same change when behavior changes. If ownership moves, remove the old definition and leave a link where navigation remains useful.

Roadmaps are temporary coordination documents. When their work is complete, record completion, move any still-useful decisions or contracts to their durable owners, update incoming links, and archive or remove the roadmap according to repository practice. Do not preserve completed roadmaps as a second current-state reference.

Retain release notes as historical records under the release policy. Do not apply temporary-roadmap retirement rules to published release notes.

Before completing documentation work:

• verify affected behavior and examples;
• check commands, imports, declarations, defaults, schemas, and paths against their implementation;
• keep unimplemented behavior in a roadmap, subject to the ADR exception;
• validate links and fenced examples;
• confirm non-owning documents summarize and link rather than redefine;
• remove stale or unsupported claims; and
• confirm that no secrets or sensitive private data were added.