Skip to content

Make <Syntax> find relevant component documentation from a question #787

Description

@taras

Story

As an XMD author or planning Agent, I want to describe the task I am trying to
perform when I inspect Syntax, so I receive documentation for the components
that are relevant without already knowing their names.

<Syntax query="Ask the user for structured input and save the answer to a file." />

The result contains the canonical Syntax entries for the components that help
with that task. It is small enough to use as working context and remains an
accurate account of the components available at the authored site.

Current gap

<Syntax /> lists the available vocabulary, and <Syntax names={...} />
renders selected component documentation. A caller that does not yet know the
right component names must inspect broader output and perform the relevance
selection itself. This is especially costly for an Agent requesting information
before it writes a document.

Contract

  • A natural-language question selects relevant components from the Syntax
    visible at that authored site.
  • Selection chooses component names; canonical <Syntax> renders those
    components' existing metadata and documentation. The selection step does not
    invent props, summarize away constraints, or author replacement documentation.
  • Availability remains truthful. Documentation may explain a component that is
    not executable in a narrowed evaluation, and reading it never grants authority
    to execute it.
  • A query with no relevant match reports that outcome instead of silently
    returning the complete documentation catalog.
  • Existing bare and names forms retain their behavior.
  • The selection mechanism, provider choice, and ranking policy are architecture
    decisions for this feature; they are not added to the Plan information-request
    work in Add read-only XMD information requests to xmd plan #762.

Acceptance

  • A caller can obtain useful component documentation from a task description
    without placing component names in the query.
  • Every returned entry is identical to the canonical documentation returned by
    the equivalent names request; a plausible but nonexistent component is never
    synthesized.
  • Narrowed evaluation marks selected components' real availability and does not
    acquire new execution authority.
  • No-match, malformed, cancelled, and failed selections do not fall back to the
    full catalog or return partially invented documentation.
  • Focused component tests cover query selection, exact canonical rendering,
    no-match behavior, existing-form compatibility, and the authority negative
    control.

Relationship to Plan

#762 can ship with explicit names lookup and no rendered-output size limit.
This story is an independent improvement to how an Agent discovers the names it
needs.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions