Skip to content
Almathal Handbook

ADR-0011: Hybrid Form Plus Conversation Input

Accepted

Date: 2026-06-10

Context

Three input models for the Resolver are possible:

  • Declarative form. User picks Archetype, fills structured fields. Closest to JHipster’s JDL flow. Rigid; long forms become exhausting.
  • Natural-language conversation. User describes intent; an LLM translates. Closest to Cursor’s flow. Unpredictable for enterprise buyers who want to know what they’re getting.
  • Hybrid. Form for known structured fields, conversation for everything else, merged into the Spec.

Decision

Use the hybrid model. The form is auto-generated from the Archetype’s typed Variation Points (ADR-0007). The user fills the form. The user can also add free-text descriptions of additional requirements; an LLM interprets these and either fits them to existing Variation Points or surfaces them as items that don’t fit (potentially triggering the fallback path).

Rationale

  • The form gives enterprise users predictability: they can see what they’re authorizing.
  • Conversation handles the parts users don’t know in advance — variation reveals through dialogue.
  • Auto-generated forms stay in sync with Archetype evolution.
  • The Build Approval step (ADR-0012) gives the user a final review before generation runs.

Consequences

  • Each Archetype declares Variation Points knowing the form will be auto-generated.
  • The Resolver includes both deterministic form processing and LLM-driven conversational interpretation.
  • Free-text inputs that can’t be fit to existing Variation Points become a signal for new Archetypes (logged for product evolution).

References