promptkit/docs/roadmap/inspection.md

# Effective Prompt Requirement Inspection

Status: Implementation planned; the feature is not implemented. The
[implementation plan](implementation.md) owns the ordered implementation steps.
This document owns the purpose, scope, and target end state.

## Purpose

Let consumers enumerate a selected prompt's inputs and caller variables before
its input artifacts exist, with each name classified as required, conditional,
or optional for the supplied context. Scriptorium can present that inventory
to operators and Narratio can compare planned bindings with exact input names
before undertaking expensive pipeline work.

The originating request is [Scriptorium's feature request](scriptorium-feature-request.md).
Promptkit supplies application-neutral inspection; consumers own presentation,
binding checks, and their own workflows.

## Current Baseline

At review baseline `b595dca`:

- [InspectPrompt](../consumers/pkg-promptkit.md#inspect-a-prompt-before-preparation)
  selects a captured prompt and reports declared inputs and output metadata,
  without analyzing templates or resolving an execution profile.
- [InspectProfile](../consumers/pkg-promptkit.md#inspect-a-profile-before-prompt-work)
  reports a captured profile's effective target separately.
- [Prepare](../consumers/pkg-promptkit.md#prepare-without-model-execution)
  selects an execution context, loads artifacts and applicable schemas, and
  renders messages. It needs actual input data.
- Engine construction captures final definitions and compiled message/session
  templates. Rendering uses Go templates, string-valued caller variables, and
  the `input` helper. Required input declarations are checked independently of
  branches; an executed helper also needs its named input.
- Declared content types and descriptions currently use string fields. The
  new inspection needs declaration information and effective metadata presence,
  including the difference between an absent field and an explicitly empty one.

The [format reference](../formats.md#messages-and-templates), existing GoDoc,
and [internal source document](../internal/sources.md) own current behavior.

## Target Public Operation

Add `Engine.InspectRequirements` with dedicated public request/result values.
Preserve `InspectPrompt`, `InspectProfile`, preparation, and execution.

The request supplies a prompt ID, optional version and profile selectors,
caller variables, and an optional direct session ID. It needs no artifact
references or contents, output path, or credentials.

Use execution's selection semantics: exact identities, omitted-version
ambiguity, request profile or prompt default, and normalized direct session-ID
bypass. Report the selected prompt ID/version and effective profile ID.
Selecting a profile establishes identity, not generation readiness; partial
profiles remain inspectable.

Use the configured engine's captured definitions. Source selection remains a
consumer choice. Results describe that captured context, not a later engine or
execution with different variables.

## Result And Classification

Return an inventory of inputs and a separate inventory of caller variables.
Each entry has one of three requirement classifications:

- **Required:** A declaration or recognized definite access establishes that
  the caller must supply it.
- **Conditional:** Its necessity remains unresolved, including references on
  paths whose applicability the supported analysis cannot determine.
- **Optional:** It is known not to be required, including recognizable references
  used only on known inactive paths and nonrequired declarations or lookups.

A required declaration stays required even in an inactive branch. A definite
helper use promotes an optional input declaration to required. Aggregate repeated
occurrences by exact name: required takes precedence over conditional, which
takes precedence over optional. Conservative conditional classification is
acceptable where analysis cannot establish necessity; inspection need not prove
equivalence between alternative execution paths.

Input entries distinguish declarations from discovered undeclared references
and preserve available descriptions/content types. They do not infer input
schemas or introduce format enforcement. Variables identify caller-map keys,
not template-local symbol names, and report whether each key was supplied.
An empty supplied string is present; absence is separate from classification.

Include recognizable references on known inactive paths in both inventories
as optional entries with an inactive-use explanation. Keep explanations separate
from declared input descriptions. An applicable required or conditional use
elsewhere overrides the optional classification. Any applicable occurrence,
including an optional lookup, removes an inactive-only explanation. Known
inactivity introduces neither an execution requirement nor discovery uncertainty.

Deduplicate names and provide predictable ordering. Results also identify the
selected context and provide discovery completeness with machine-readable
limitation categories and safe explanations. Exact public spellings belong in
the implementation plan and, once implemented, GoDoc. No Promptkit JSON wire
schema is part of this feature.

## Simple Discovery Boundary

Use parsed template syntax, not raw-text matching or rendering with placeholder
artifacts. The intended algorithm is straightforward:

1. Seed the inventory from input declarations and their effective metadata.
2. Visit the selected message templates and applicable session template,
   collecting recognizable input and caller-variable references.
3. Classify occurrences using their surrounding path and a small amount of
   supplied-context evaluation.
4. Aggregate entries and report any unresolved discovery.

The source inventory is finite and ordinarily small. Direct traversal and
name-indexed aggregation are sufficient; no size caps, analysis budgets,
branch-combination enumeration, or global analysis cache are needed.

Recognize literal input names, direct caller-variable access, literal-key root
lookups, direct variable-derived input names, and ordinary `if`/`with` branches.
Use simple truthiness, negation, and equality/inequality where straightforward.
Empty strings and the nonempty string `"false"` follow actual Go truthiness.
The implementation plan defines this small initial coverage precisely.

Retain enough lexical/dot scope awareness to distinguish caller variables from
locals. Complicated assignments, pipelines, computed names, ranges, or invoked
named templates can remain outside complete analysis. Preserve identifiable
references and report limitations rather than implementing a general template
interpreter, joining assignment environments, or propagating possible-name sets.
No cross-branch proof of a common required dependency is necessary.

On a known inactive path, collect names visible in syntax without evaluating
its expressions. Literal input names and recognizable caller keys remain in
the inventory; skipped dynamic input names need not be resolved. Unsupported
skipped expressions do not themselves make discovery incomplete.

A direct nonblank session ID excludes the bypassed session template from both
inventories. Never-invoked template definitions do not create requirements.
Declarations and references in selected messages remain relevant.

Complex computed names may be missed by the inventory. That is an accepted
analysis limitation, not a reason to reject an otherwise valid prompt.
Inspection must expose potential incompleteness rather than imply that unknown
names are absent. Template authors benefit from keeping dependency expressions
simple, but this feature adds no template-authoring prohibition.

## Completeness And Limitations

Completeness describes discovery, not satisfaction or readiness. A missing
variable used only for direct text substitution can be a known required entry
with complete discovery. A missing value used to select a branch or name can
leave dependencies unresolved.

When unavailable input content, unresolved names, missing decision values, or
unsupported analysis affect discovery, return known entries with successful
incomplete status and structured reasons. Conservative incompleteness is
acceptable; inspection need not prove an exact requirement set through complex
expressions. Unsupported pure text with no effect on dependencies need not
introduce uncertainty.

Unresolved names can potentially refer to existing optional entries. Account
for that possibility in classification, while leaving established required
entries required. Do not label a potentially needed entry definitively optional.

An empty complete input inventory, or a complete input inventory containing
only optional entries, establishes that no artifact bindings are needed.
An empty incomplete inventory does not. Consumers must use classifications,
not inventory length, to identify bindings that need preparation.

## Effects, Errors, And Disclosure

Inspection uses captured resources without future artifact reads, schema
preparation, credential lookup, model calls, capacity admission, observations,
run IDs, or execution artifact creation. Necessary configuration/resource
failures can still prevent engine construction or inspection.

Preserve publicly classifiable selection errors and ordinary context
cancellation. Discovery uncertainty is a successful result, not an operational
error or a new definition-validity rule. A complete result does not promise
successful rendering, generation, future artifact validity, or provider
availability.

Results and diagnostics exclude credential values, artifact payloads,
raw/rendered prompt content, and unrelated supplied values. Selected identities,
input/variable names, and declared descriptions are intentional operator
metadata. A directly resolved input identifier may equal a supplied variable
value; reporting that binding name is necessary, without echoing its originating
expression or variable map.

## Work Needed From The Baseline

Add request/result values and the engine method through the root facade.
Keep selection coordination internal and place syntax discovery with the
existing prompt-template component. Reuse captured templates and selection
helpers rather than creating another preparation path.

Capture required metadata presence at the final ConfigKit handoff and retain it
alongside inspection snapshots. Apply [ADR 0001](../adr/0001-configuration-boundary.md):
interpret final effective definitions, not raw/intermediate configuration or
history. Operator provenance remains a separate explicit API.

Implement a small syntax walker, simple context tests, classification
aggregation, and safe limitation reporting. Keep request-specific state separate
from captured definitions. Focus tests on representative enumeration,
classifications, scope mistakes, selection, capture/ownership, and absence of
execution effects, under the [testing policy](../policy/testing.md). Do not test
a general interpreter or repeat ConfigKit's source-loading matrix.

When implementation lands, update GoDoc, the consumer guide, relevant format
cross-references, internal documents, and a maintained example. Canonical owners
document the implemented boundary; release notes summarize rather than own it.

## Acceptance Outcomes

- Required `transcript` is reported exactly before its artifact exists.
- Literal undeclared helper names are discoverable without definition rejection.
- Input and variable references are classified as required, conditional, or
  optional, including recognizable inactive references in both inventories.
- Required declarations stay required; definite uses promote optional entries;
  other occurrences never erase an established required use.
- Simple supplied-context branches and direct dynamic names follow execution;
  complicated or content-dependent cases preserve known entries and limitations.
- Caller keys remain distinct from template locals, and supplied empty values
  remain distinct from absent keys.
- Selection and session bypass follow execution without readiness checks.
- Complete artifact-free inventories remain distinguishable from empty partial
  discovery; completeness remains separate from supplied-variable presence.
- Results/errors preserve the disclosure and public classification boundaries.
- Existing inspection/execution contracts remain intact. Application APIs,
  pipeline planning, binding validation, presentation, provider preflight, input
  schemas, and a general-purpose template evaluator remain outside this scope.