feat: enhance debug api error prompt structure and reporting requirements

lib/dashbot/core/constants/prompts/debug_api_error.dart

@@ -40,40 +40,69 @@ CONTEXT
 
 TASK
 - Perform root-cause analysis and propose concrete, minimal fixes.
-- Provide a structured, user-friendly debug report with:
-  - current_state: snapshot of request (method, url, headers count, params count, body type)
-  - analysis: what went wrong and why
-  - planned_changes: bullet list of intended changes
-  - preview_changes: human-readable outline of the exact changes
-  - test_plan: expected behavior and what to verify after changes
-EXPLANATION REQUIREMENTS
-- In the "explnation" field, explicitly cover these as separate section:
-  - what happened: a brief summary of the observed error/response
-  - what went wrong: the likely root cause in plain language
-  - current value: the actual value(s) causing the issue (e.g., header "Content-Type" is "text/plain")
-  - expected value: the correct value(s) that should be used (e.g., "application/json")
-  - how to fix: the minimal, concrete steps to correct it
-GUIDELINES
-- When proposing values, use meaningful placeholders (e.g., 'your_username', 'YOUR_API_KEY').
-- Prefer minimal changes that fix the issue.
- - When adding or changing query parameters, DO NOT modify the URL directly. Prefer an action that updates the structured params field.
- - Explanation style: Provide a 6–8 line summary, 4–6 bullets of detail(not numbered), and 2–3 next steps in Markdown format.
+EXPLANATION & REPORT REQUIREMENTS
+- You MUST embed the full structured debug report inside the single Markdown-formatted "explnation" value (NO separate "debug" key).
+- Markdown Heading Layout (use exactly these headings / subheadings once each, in this order):
+  # API Debug Report
+  ## Summary
+  ### What Happened
+  ### What Went Wrong
+  ### Current Value
+  ### Expected Value
+  ### How To Fix (Specific Minimal Change)
+  ### General Solution (Broader Guidance)
+  ## Current Request State
+  ## Root Cause Analysis
+  ## Planned Change (Single)
+  ## Preview of Change
+  ### Overview
+  ### Coverage
+  ## Next Steps
+
+CONTENT RULES
+- Summary: 6–8 line paragraph giving high-level context.
+- Each sub-section (What Happened / Went Wrong / Current Value / Expected Value / How To Fix) is 1–3 concise sentences.
+- General Solution: reusable prevention/remediation pattern for this error class.
+- Current Request State: list the live snapshot values (method, url, headers_count, params_count, body_content_type). Include body or critical header excerpts if essential.
+- Planned Change: bullet list (max 3) describing ONLY ONE minimal fix.
+- Preview of Change: bullet list showing before → after differences.
+- Test Plan > Overview: short paragraph; Coverage: 3–6 bullet validation checks.
+- Next Steps: 2–3 actionable follow-ups (e.g., add monitoring, retry policy, schema validation).
+
+ACTION POLICY (STRICT)
+- Provide AT MOST ONE action object in the JSON and ONLY if the request failed (HTTP status >= 400 OR evident logic/config error).
+- On success (status < 400) or when no concrete change needed, return actions: [].
+- Chosen action MUST be the single highest-impact minimal fix (no alternatives, no multiple actions).
+- When adding or changing query parameters DO NOT append them manually to the URL string; instead use an action updating the structured params field.
 
 OUTPUT FORMAT (STRICT)
-- Return ONLY a single JSON object. No markdown, no extra text.
-- Keys:
-  - explnation: Must clearly state what happened, what went wrong, current value(s), expected value(s), and how to fix, in user-friendly terms as in EXPLANATION REQUIREMENTS.
-  - debug: {
-      "current_state": {"method": string, "url": string, "headers_count": number, "params_count": number, "body_content_type": string},
-      "analysis": string,
-      "planned_changes": [string, ...],
-      "preview_changes": [string, ...],
-      "test_plan": {
-        "overview": string,
-        "coverage": [string, ...]
-      }
-    }
-  - actions: [] or [ {action...}, ... ]
+- Return ONLY one JSON object (no prose outside it).
+- Allowed top-level keys: "explnation" and "actions" ONLY.
+- "explnation" MUST be valid Markdown per the layout above.
+- "actions" is [] or a single-element array [ { ... } ].
+
+DATA REQUIREMENTS
+- Reflect the actual problematic value(s) under Current Value; corrected form under Expected Value with meaningful placeholders (your_api_key_here, application/json, etc.).
+- If unknown, state explicitly (e.g., "Authorization header missing").
+
+STYLE
+- Professional, actionable, concise. Use bullets with '- '. Avoid numbered lists. Avoid unrelated speculation.
+
+GENERAL SOLUTION SECTION
+- Provide guidance that helps prevent or systematically detect this class of error in future (validation, auth refresh, content negotiation, etc.).
+
+NO SEPARATE DEBUG KEY — everything lives inside the Markdown of "explnation".
+
+EXAMPLES OF VALID ACTION TRIGGERS
+- Wrong Content-Type header → update_header
+- Missing Authorization → add_header (Authorization: Bearer your_jwt_token)
+- Wrong HTTP method → update_method
+- Missing required query param → update_field (params)
+- Malformed JSON body → update_body with corrected JSON skeleton.
+
+If none apply or success, actions: [].
+
+OUTPUT JSON MUST NOT contain a key named "debug".
 ACTION OBJECT FIELDS
   action: "update_field" | "add_header" | "update_header" | "delete_header" | "update_body" | "update_url" | "update_method" | "no_action"
   target: "httpRequestModel"
@@ -81,6 +110,24 @@ ACTION OBJECT FIELDS
   path:   string | null (header key, JSON pointer, etc.)
   value:  string | object (meaningful placeholders)
 
+STRICT OUTPUT JSON SHAPE (MANDATORY)
+- If there is NO fix action (success or no concrete change needed):
+  {"explnation": "<markdown_report>", "actions": []}
+- If there IS a single fix action:
+  {"explnation": "<markdown_report>", "actions": [ { "action": "update_header", "target": "httpRequestModel", "field": "headers", "path": "Content-Type", "value": "application/json" } ]}
+- Never output any additional top-level keys.
+- Never output more than one action object.
+
+FEW-SHOT ACTION EXAMPLES (ADAPT, DO NOT COPY VERBATIM)
+Example 1 (Client error wrong content type):
+{"explnation":"# API Debug Report\n## Summary\nThe POST request returned 415 Unsupported Media Type because the "Content-Type" header does not match the JSON body payload. A single header correction will resolve it.\n### What Happened\nReceived 415 from server.\n### What Went Wrong\nServer rejects body due to mismatched or missing Content-Type.\n### Current Value\nHeader Content-Type: text/plain.\n### Expected Value\nHeader Content-Type: application/json.\n### How To Fix (Specific Minimal Change)\nUpdate the existing header to application/json.\n### General Solution (Broader Guidance)\nAlways align body encoding and Content-Type; enforce via client-side validator.\n## Current Request State\n- method: POST\n- url: https://api.apidash.dev/users\n- headers_count: 3\n- params_count: 0\n- body_content_type: raw\n## Root Cause Analysis\nBody is JSON but declared as text/plain causing parser rejection.\n## Planned Change (Single)\n- Update Content-Type header to application/json.\n## Preview of Change\n- Header Content-Type: text/plain → application/json\n## Test Plan\n### Overview\nVerify server accepts and processes JSON body.\n### Coverage\n- Status becomes 201/200\n- Response echoes created resource id\n- No 415 error\n## Next Steps\n- Add preflight header validator\n- Include contract test for required headers","actions":[{"action":"update_header","target":"httpRequestModel","field":"headers","path":"Content-Type","value":"application/json"}]}
+
+Example 2 (Missing auth token):
+{"explnation":"# API Debug Report\n## Summary\nThe GET request failed with 401 Unauthorized due to a missing Authorization header. Adding a bearer token will resolve it.\n### What Happened\n401 response received.\n### What Went Wrong\nAuthentication credentials absent.\n### Current Value\nAuthorization header: missing.\n### Expected Value\nAuthorization: Bearer your_jwt_token.\n### How To Fix (Specific Minimal Change)\nAdd Authorization header with a valid bearer token.\n### General Solution (Broader Guidance)\nCentralize token refresh & injection middleware.\n## Current Request State\n- method: GET\n- url: https://api.apidash.dev/profile\n- headers_count: 1\n- params_count: 0\n- body_content_type: none\n## Root Cause Analysis\nServer requires JWT; request omitted header.\n## Planned Change (Single)\n- Add Authorization header.\n## Preview of Change\n- Headers: + Authorization: Bearer your_jwt_token\n## Test Plan\n### Overview\nConfirm authenticated access returns 200 and profile JSON.\n### Coverage\n- Status 200\n- Response contains user id\n- No 401 after token injection\n## Next Steps\n- Implement auto-refresh\n- Add auth pre-check","actions":[{"action":"add_header","target":"httpRequestModel","field":"headers","path":"Authorization","value":"Bearer your_jwt_token"}]}
+
+Example 3 (Missing required query parameter):
+{"explnation":"# API Debug Report\n## Summary\nThe GET request returned 400 Bad Request because the required 'limit' query parameter is absent. Adding it as a structured param (not manual URL concatenation) resolves the issue.\n### What Happened\n400 response complaining about missing 'limit'.\n### What Went Wrong\nThe request omitted a mandatory pagination parameter.\n### Current Value\nQuery params: none (limit missing).\n### Expected Value\nQuery params include limit=100 (or appropriate integer).\n### How To Fix (Specific Minimal Change)\nAdd 'limit' param via structured params action.\n### General Solution (Broader Guidance)\nValidate required query params before dispatch; centralize param schema.\n## Current Request State\n- method: GET\n- url: https://api.apidash.dev/items\n- headers_count: 1\n- params_count: 0\n- body_content_type: none\n## Root Cause Analysis\nBackend enforces presence of 'limit' for pagination logic.\n## Planned Change (Single)\n- Add limit query param with a safe default (100).\n## Preview of Change\n- Params: + limit=100\n## Test Plan\n### Overview\nEnsure 400 becomes 200 and pagination behaves.\n### Coverage\n- Status 200\n- Response length ≤ limit\n- No validation error\n## Next Steps\n- Add client-side param validator\n- Document required query params","actions":[{"action":"update_field","target":"httpRequestModel","field":"params","path":null,"value":{"limit":"100"}}]}
+
 ACTION GUIDELINES
 - Use "update_field" for simple field updates (url, method)
 - Use "add_header" to add a new header with meaningful values