Skip to content

adr-schema-guided-reasoning

Decision

Conditionally adopt Schema-Guided Reasoning to enforce structured JSON Schema contracts directly into prompt templates and model invocation parameters.

Context

  • Source: governance-flow
  • Pattern: schema-guided-reasoning
  • Promotion Recommendation: recommendation-schema-guided-reasoning
  • Scope Classification: global
  • Scope Classification Artifact: pattern-scope-classification

Unstructured LLM completions require complex downstream text parsing and risk unpredictable schema drift. Schema-Guided Reasoning pairs prompt execution with explicit JSON Schemas (via ReasoningExecutionContract in src/cas_runner/orchestration/reasoning.py), validating that generated outputs strictly adhere to declared schemas prior to returning control to workflow runners.

Scope

Applicability: Mandatory for all reasoning engine steps producing structured domain outputs.

Governs prompt metadata, schema registration in src/cas_runner/schemas/, and structured reasoning response parsing.

Consequences

Governance

Ensures that every reasoning step is contractually bound to an explicit schema registered under src/cas_runner/schemas/. Provides auditable, schema-validated artifacts for all architecture workflows.

Execution

Prompt execution contracts automatically inject and validate schema definitions, raising actionable schema validation errors early during pipeline execution.

System Behaviour

Dramatically reduces reasoning failure rates and prevents malformed LLM responses from propagating to downstream synthesis steps.

Evidence Summary

Promotion Evidence

  • Concrete implementation in src/cas_runner/orchestration/reasoning.py (ReasoningExecutionContract)
  • Centralized JSON schema repository in src/cas_runner/schemas/
  • Proven across forensic diagnostic, AEM generation, and AID synthesis steps

Promotion Criteria

Significance, reusability, recurrence, evidence quality, governance maturity, and strategic alignment are fully met.

Governance Risks

Risk of schema drift or mismatch between evolving prompt specifications and registered JSON Schemas.

Traceability

Pattern Proposal

schema-guided-reasoning

Scope Classification

Artifact: pattern-scope-classification

Classification: global

Promotion Recommendation

recommendation-schema-guided-reasoning

Promotion Decision

promotion-decision-schema-guided-reasoning

Next Step

  • Satisfy ArchGov conditional review requirements: verify schema drift detection in CI/CD pipeline.
  • Maintain schema mappings within src/cas_runner/orchestration/reasoning.py.