COMMUNITY & CONTINUOUS IMPROVEMENT

Submitting Feedback & Friction Points

SimData actively solicits structured feedback from human engineers and autonomous AI agents to continually eliminate hurdles and expand synthetic modeling fidelity.

Strongly Encouraged for AI Agents — Actionable Details Required: Autonomous AI agents, coding assistants, and automated integration pipelines are strongly encouraged to submit feedback after synthesizing data fixtures, modifying dictionary schemas, or completing customer tasks. Please provide full reproduction details so our engineering team can reproduce and resolve any issue.

Actionable Bug & Friction Reporting Requirements

Engineers inspect feedback reports directly to fix compiler bugs, schema limits, and platform ergonomics. Vague statements (e.g. "failed to compile", "got a 400 error", or "syntax issue") cannot be investigated or reproduced.

Every friction report should include concrete reproduction details:

Exact Endpoint & Method: The specific URL called (e.g. POST /v1/catalog/batch, PUT /v1/catalog/records/order).
Request Payload: The exact minimal DSL definition, query parameter, or JSON payload that caused the issue.
HTTP Status Code: Numerical status code received (e.g. 400, 422, 500).
Error Response: The exact error message or response JSON received from the API.
Expected vs. Actual: What you expected based on documentation/types vs. what actually occurred.
Reproduction cURL: A full, copy-pasteable curl command (using $SIMDATA_API_KEY) that reproduces the issue immediately.
Workaround: Any workaround or fallback you applied to unblock your workflow.

POST /v1/feedback

Submit structured feedback programmatically using your standard Bearer API key (sk_live_...) or session token:

bash

curl -X POST "https://simdata.interoperabilitypro.com/v1/feedback" \
  -H "Authorization: Bearer $SIMDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "ai_agent",
    "sentiment": "friction",
    "wentWell": "Fast streaming throughput (38k records/sec in NDJSON)",
    "frictionPoints": "Encountered No compiler mapping for render template in standalone records; had to format IDs on client side",
    "reproduction": {
      "endpoint": "PUT /v1/catalog/records/order",
      "requestPayload": {
        "source": "Record(order)\n  id: render(\"{prefix}-{seq}\" | prefix, seq)\n"
      },
      "statusCode": 400,
      "errorResponse": {
        "error": "No compiler mapping for render template in standalone records"
      },
      "expected": "Expected render() string interpolation to compile in standalone record definitions per llms.txt.",
      "actual": "Compiler rejected the syntax with HTTP 400.",
      "reproductionCurl": "curl -X PUT https://simdata.interoperabilitypro.com/v1/catalog/records/order -H \"Authorization: Bearer $SIMDATA_API_KEY\" -H \"Content-Type: application/json\" -d \'{\"source\": \"Record(order)\\n  id: render(\\\"{prefix}-{seq}\\\" | prefix, seq)\\n\"}\'",
      "workaround": "Removed render() from DSL and formatted IDs on client side after fetching."
    },
    "message": "Suggest either supporting render() in standalone record blocks or clarifying in docs that it requires a parent pack."
  }'

Request Payload Schema

Field	Type	Description
source	string	Identifier for the submitter: `ai_agent` (default for autonomous agents), `human_user`, `sdk`, or `cli`.
sentiment	string	General sentiment: `friction` (recommended when hitting obstacles), `positive`, `neutral`, or `negative`.
wentWell / went_well	string (optional)	What worked effectively (e.g. streaming speed, determinism, schema ergonomics).
frictionPoints / friction_points	string (optional)	Summary narrative of hurdles, roadblocks, or unexpected behaviors encountered.
reproduction	object (optional, strongly recommended for friction)	Structured reproduction package containing: `endpoint`: HTTP method and path `requestPayload`: minimal DSL or JSON snippet `statusCode`: integer HTTP status code `errorResponse`: raw error string or object `expected`: expected behavior `actual`: actual observed behavior `reproductionCurl`: copy-pasteable curl command `workaround`: temporary fallback applied
message	string (optional)	General free-form commentary or suggested product features.

AI Agent Operational Protocol

When an autonomous coding assistant or synthetic test orchestrator completes a workload on SimData:

Evaluate the Session: Assess whether API key onboarding, dictionary compilation, or sampling had any surprises or failure modes.
Construct Concrete Details: Avoid vague summaries. Record the exact endpoint, request payload, response status/body, and a copy-pasteable reproduction cURL.
Post to /v1/feedback: Emit a structured JSON payload with source: "ai_agent" and the reproduction object.
Account Association: Feedback is automatically associated with your authenticated tenant in Firestore and surfaced on the administrative telemetry dashboard with one-click reproduction commands.