Skip to content

docs: add guidance for intentional ask_user pauses - #159

Open
PayalVerma1 wants to merge 1 commit into
openprose:mainfrom
PayalVerma1:docs/interactive-authoring
Open

docs: add guidance for intentional ask_user pauses#159
PayalVerma1 wants to merge 1 commit into
openprose:mainfrom
PayalVerma1:docs/interactive-authoring

Conversation

@PayalVerma1

Copy link
Copy Markdown

Summary

  • Added author-facing guidance explaining how to intentionally pause execution for user input using ask_user.
  • Clarified that interactive services are authored by leaving required inputs unbound, not by introducing a ### Runtime: interactive: true field.
  • Added a complete interactive example demonstrating bind-time ask_user behavior and linked it from the examples index.

Fixes #105


Why

The existing documentation describes ask_user only as an automatic VM input-binding mechanism. It does not clearly explain how authors intentionally build interactive services, making this behavior difficult to discover.

As a result, contributors inferred a non-existent ### Runtime: interactive: true option because there was no author-facing guidance or interactive example to follow.

This PR closes that documentation gap without changing language semantics or runtime behavior.


What Changed

Documentation

  • Added an Interactive Authoring section to skills/open-prose/guidance/authoring.md explaining:

    • how to intentionally pause for user input,
    • when ask_user should be used,
    • expected behavior for non-interactive hosts (unresolved-intent rather than fabricated input).
  • Added Intentional ask_user Pauses to skills/open-prose/prose.md, documenting the recommended authoring pattern:

    1. Declare the required input.
    2. Leave it unbound.
    3. Allow the VM to invoke ask_user, bind the response, and resume execution.

    The section also explicitly clarifies that ### Runtime: interactive: true is not part of the language.

Examples

  • Added a new interactive-grill example showing an intentionally interactive responsibility that pauses for user input.
  • Added supporting documentation explaining bind-time pauses and non-interactive fallback behavior.
  • Linked the new example from the examples index as the interactive counterpart to the existing non-interactive examples.

Design Boundary

This PR is documentation and examples only.

It does not modify:

  • language semantics,
  • VM behavior,
  • runtime execution,
  • parser/compiler logic,
  • host adapters.

Testing

  • pnpm build
  • pnpm test:skill

Results:

  • 27 test files passed
  • 411 tests passed

Follow-ups

This PR intentionally addresses only the documentation/discoverability gap described in #105.

The host-specific interaction behavior (structured vs. plain-chat questioning) and the potential run-log improvements mentioned in the issue remain separate concerns and are better addressed in future issues or PRs.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs don't show how to author a service that intentionally pauses for user input

1 participant