From 44fe854aab8a861580987553baa15056b4756e25 Mon Sep 17 00:00:00 2001
From: Shivam Mishra <scm.mymail@gmail.com>
Date: Mon, 13 Oct 2025 11:47:24 +0530
Subject: [PATCH] feat: include ARQ

---
 .../lib/captain/prompts/assistant.liquid      | 53 +++++++++++++++++++
 enterprise/lib/captain/response_schema.rb     |  7 +++
 2 files changed, 60 insertions(+)

diff --git a/enterprise/lib/captain/prompts/assistant.liquid b/enterprise/lib/captain/prompts/assistant.liquid
index 0dc7d8577..48178dc46 100644
--- a/enterprise/lib/captain/prompts/assistant.liquid
+++ b/enterprise/lib/captain/prompts/assistant.liquid
@@ -41,6 +41,59 @@ Always respect these boundaries:
 {% endfor %}
 {% endif -%}
 
+# Attentive Reasoning Blueprint
+Before composing the customer-facing `response`, fill the `arq_plan` object in your JSON output using the structure below. This ARQ keeps critical rules fresh and prevents guideline drift.
+
+```json
+{
+  "instructions_to_restate": [],
+  "response_compliance_checklist": [],
+  "ready_to_respond": true,
+  "notes": ""
+}
+```
+
+- **`instructions_to_restate`** must list the non-negotiable directives you need top-of-mind **in this order**. Restate them as concrete sentences, not shorthand.
+  1. Guardrails that must never be broken.
+  2. Response guidelines that drive tone, content, or format.
+  3. Mandatory tool usage rules (e.g., FAQ lookup before citing product facts, handoff requirements).
+  4. Scenario routing expectations that influence ownership of this turn.
+- **`response_compliance_checklist`** converts the above obligations into yes/no questions you can confirm before answering (e.g., "Did I verify every product statement via `captain--tools--faq_lookup`?").
+- **`ready_to_respond`** stays `false` until every checklist item would be satisfied by your drafted reply.
+- **`notes`** is ≤20 words summarizing how you will meet the checklist or what remains unresolved if `ready_to_respond` is `false`.
+
+Use the live configuration below when populating the arrays:
+
+{% if guardrails.size > 0 -%}
+- Guardrails:
+{% for guardrail in guardrails -%}
+  - {{ guardrail }}
+{% endfor -%}
+{% endif -%}
+
+{% if response_guidelines.size > 0 -%}
+- Response guidelines:
+{% for guideline in response_guidelines -%}
+  - {{ guideline }}
+{% endfor -%}
+{% endif -%}
+
+- Tool discipline reminders:
+  - Use `captain--tools--faq_lookup` before sharing product facts about {{product_name}}.
+  - Only call tools whose prerequisites are met and whose results will influence the reply.
+  - Summarize tool outputs so the customer can act on them.
+
+- Scenario routing expectations:
+  - Treat routing as a primary responsibility: hand off when any scenario agent is better suited.
+  - Evaluate enabled scenario agents before handling the request yourself.
+{% if scenarios.size > 0 -%}
+{% for scenario in scenarios -%}
+  - {{ scenario.title }} → trigger with `handoff_to_{{ scenario.key }}` when {{ scenario.description | downcase }} applies.
+{% endfor -%}
+{% endif -%}
+
+Once `ready_to_respond` would be `true`, draft the `response` and provide a concise, human-readable rationale in the `reasoning` field referencing how the checklist—including the handoff evaluation—was satisfied.
+
 # Decision Framework
 
 ## 1. Analyze the Request
diff --git a/enterprise/lib/captain/response_schema.rb b/enterprise/lib/captain/response_schema.rb
index 651eb7e23..a54f44861 100644
--- a/enterprise/lib/captain/response_schema.rb
+++ b/enterprise/lib/captain/response_schema.rb
@@ -3,4 +3,11 @@
 class Captain::ResponseSchema < RubyLLM::Schema
   string :response, description: 'The message to send to the user'
   string :reasoning, description: "Agent's thought process"
+  object :arq_plan, description: 'Attentive Reasoning Query plan used to prepare the response' do
+    array :instructions_to_restate, of: :string,
+                                    description: 'Ordered list of concrete guardrails, guidelines, tool rules, and routing expectations to repeat before responding'
+    array :response_compliance_checklist, of: :string, description: 'Yes/no questions confirming the response satisfies each critical obligation'
+    boolean :ready_to_respond, description: 'Indicates whether the checklist is fully satisfied prior to finalizing the response'
+    string :notes, description: 'Short justification (≤20 words) explaining how the checklist is or will be satisfied'
+  end
 end