cxas-cuj-report-generator

name	cxas-cuj-report-generator
description	Automates the ingestion of customer requirement documents such as diagrams, BRDs, code etc., synthesizes high-fidelity natural transcripts, and compiles them into highly interactive, responsive Critical User Journey (CUJ) reports.

Critical User Journey (CUJ) Transcript & Report Generator Skill

Use this skill when asked to extract dialogue transcripts or compile interactive Critical User Journey (CUJ) reports from a directory of customer requirement documents (such as diagrams, BRDs, code etc.).

Core Protocols

To ensure 100% coverage and zero data loss, you MUST follow these core rules:

• Robust Extraction: Follow the protocol defined in the cxas-protocol-robust-extraction skill.
• Two-Phase Ingestion: Follow the protocol defined in the cxas-protocol-two-phase-ingestion sub-protocol inside protocols/cxas-protocol-two-phase-ingestion/.
• Checklist Mandate: The orchestrator and all subagents MUST follow the agent-protocol-checklist protocol to maintain a local task_checklist.json file, ensuring they track their progress and not lose coverage during execution.
• Orchestrator Delivery Assurance: The orchestrator MUST act as a strict, independent Delivery Auditor. BEFORE closing subagents, terminating the watchdog, or reporting campaign success to the user, the orchestrator MUST physically verify the existence, size bounds, and schema compliance of all registered deliverables (specifically gecx_customer_report.html and gecx_cuj_report.html) on disk. Under no circumstances may the orchestrator assume completion without executing a physical file-presence check.
• Auditing: The orchestrator MUST periodically check the subagent's scratch directory to ensure the task_checklist.json file is being created and maintained. If the file is missing or not updated, the orchestrator MUST terminate the subagent and respawn it with stronger enforcement instructions.

Core Workflow Steps

Follow this 5-step structured workflow to execute the task:

1. Scoping & Type Discovery: Prepare the environment and identify required skills.

   • Access Files: Ensure you have access to the source artifacts in your local workspace.

     • Tip (Drive Links): If the source is a Google Drive link or folder ID, you MUST use the gdrive skill to access them.

   • Detect Inventory Types: To identify framework signatures and map them to correct Ingestors, you MUST use the framework detector agent defined in agents/framework_detector.md. Using this agent, scan the input files to inventory all file extensions and detect potential frameworks. Spawn parallel Framework Detector subagents to scan partitions of the file tree.

   • Map Ingestors: Use the scoping report generated by the Framework Detector to select or create the correct specialized skills in ingestors/frameworks/ or ingestors/files/.

     • Precedence Rule: Framework-specific ingestors take precedence over generic file-extension ingestors (e.g., use ingestors/frameworks/adk/ instead of ingestors/files/py/ if both apply).

2. Discovery: Spawn specialized expert subagents based on the discovered types to identify sub-intents (see the agents/ directory for role definitions). Dynamically discover and use specialized ingestor skills in ingestors/frameworks/ and ingestors/files/.

   • Mandatory Handoff: Subagents MUST report back:

     1. Frameworks detected,
     2. File types parsed, and
     3. Any files/patterns skipped as out-of-scope.

   • Exhaustive Use: Use all relevant ingestors by applying the most specific one applicable to each file.

   • Fallback: If no specialized ingestor exists for an out-of-scope file type, the orchestrator MUST delegate the analysis:

     1. Spawn Analyzer: Spawn a specialized Analysis Subagent to inspect a sample of the unknown file.
     2. Research: Instruct the subagent to search online or in internal documentation for format standards if the structure is not clear.
     3. Report & Codify: The subagent must report the best parsing strategy back to the orchestrator and SHOULD attempt to create a new specialized skill in ingestors/frameworks/ or ingestors/files/ to capture this knowledge.

3. Exhaustion: Loop until no new intents are found.

4. Clustering: Group into Parent CUJs. To ensure consistent and accurate category discovery:

   • Noise Reduction: Do NOT pass full objects with raw transcripts or code.
   • Summary Format: Provide a clean YAML list with id, name (stripped of technical tags), and a 1-sentence synthesized intent.
   • Guidance: Instruct the agent that a reasonable number of categories is typically between 5 and 10.

5. Execution: Generate transcripts and reports using the tools in this directory.

   • Mandatory: Limit batch sizes to 5-10 items per subagent to prevent LLM context exhaustion and truncation.
   • Title Synthesis: For each transcript, the agent MUST synthesize a short, human-readable scenario title based on the dialogue content and the title of the CUJ and store it in the subintent_name field, rather than using raw technical IDs.
   • Immediate ID Verification: Always assume that sensitive numbers like Account Number or Order ID are checked in a backend system immediately after being provided by the user, and insert a webhook_call or tool_call accordingly.
   • Agent-First Transcripts: Every single transcript MUST start with a standard welcome greeting: "Hello! Thanks for calling [Brand]. How can I help you today?" (or a generic welcoming if no brand is specified, e.g. "Hello! Thanks for calling. How can I help you today?") with absolutely no exceptions or alternative phrasing, even if raw requirements suggest another name.
   • Voice Realism (No Spoken URLs): Agents on the voice channel cannot speak long URLs. You MUST NEVER write raw URLs (e.g., https://...) in Agent turns. Instead, the Agent must verbally state they are texting or emailing the link (e.g., "I've texted that tracking link to your phone").
   • Standardized End Session: Every conversation MUST close with a structured 3-turn sign-off sequence:
     1. Agent: "Is there anything else I can help you with today?"
     2. User: "No, that's all. Thank you."
     3. Agent: "Thank you for calling [Brand]! Goodbye." (or equivalent brand sign-off, e.g., "Thank you for calling Customer Support! Goodbye.", or "Thank you for calling! Goodbye." if no brand is specified) with absolutely no alternative phrasing allowed. The final Agent turn MUST trigger the end_session system tool call. Do NOT omit this tool call under any circumstances. It must match this CXAS schema: yaml tool_call: name: end_session payload: session_escalated: false reason: "Conversation completed successfully" response: result: "success"
   • Dual Reports: The agent MUST generate both a CUJ report (limiting examples to at most 3) AND a comprehensive full report (including all examples).
   • Usage: Run construct_report.py with --cuj_report=True to generate the CUJ report, and with --cuj_report=False to generate the comprehensive full report.

Autonomous Execution Guardrails

By default, this workflow is long-running and requires autonomous execution. You MUST follow these guardrails:

1. Automatic Watchdog: Upon starting the task, you MUST automatically schedule a recurring timer (e.g., every 5 minutes using the schedule tool) to interrupt and check for stuck subagents or tasks.
2. Initial Confirmation: In your very first response to the user, you MUST explicitly state that you are applying the Robust Extraction Protocol and that you have set a watchdog timer.
3. Dynamic Bisecting: If a batch fails the Verification Gate twice due to missing items, automatically bisect the batch and spawn two parallel subagents to handle the smaller load.

Core Schema

All generated transcripts MUST adhere to the resources/schemas/transcript_schema.yml contract:

• subintent_id: A unique slug.
• subintent_name: Human-readable name.
• parent_cuj: The high-level category.
• turns: A list of dialogue objects.

Dialogue Turn Requirements

• Speaker: Must be either Agent or User. Please ensure that function call turn comes immediately after a user turn.
• Text: The literal string spoken.
• Root-Level Call Fields: The tool_call (such as end_session) and webhook_call fields MUST be written at the root level of individual turn objects in the YAML transcript, and MUST NOT be nested under enrichment or any other parent key.
• Enrichment:
  • intent_detected: Specify the NLU intent if applicable.
  • tool_call: Use when the agent invokes a local function.
  • webhook_call: Use when the agent triggers an external API.
  • system_action: Use for state transitions or background logic.

Linguistic & Voice Naturalness Standards

All generated spoken dialogue turns (Agent voice turns) MUST strictly adhere to high-fidelity spoken voice standards. Subagents must ensure:

1. Numeric Voice Normalization: Spoken Agent turns MUST NOT contain raw digits, formatted currencies, or punctuation symbols representing numbers (e.g., do NOT write "450", "$909", "555-0199"). Instead, numbers must be explicitly spelled out phonetically:
   • Correct: "four hundred fifty points", "nine hundred nine dollars".
   • IDs, Times, Order Numbers, Percentages, and Phone Numbers: All numeric IDs, times, counts, reward points, percentages, or numbers of any kind must be written digit-by-digit or word-by-word phonetically with absolutely no punctuation or colon dividers: "five five five, zero, one, nine, nine", "seven thirty PM", "eight o'clock PM", "order number nine nine eight eight", "twenty percent discount".
   • Scheduling Confirmation: For any reservations or delivery updates that schedule or communicate a specific time, timeframe, or booking date (e.g., "ready in twenty minutes", "arrive in ten minutes", "booked for tomorrow at eight PM"), you MUST explicitly seek confirmation from the user (e.g. "Is that okay?", "Does that work for you?", or "Should we proceed with that?").
2. Spoken Breath Span Limit: Agent turns must remain concise, natural, and conversational. Individual spoken text blocks MUST NOT exceed 300 characters inside a single turn.
3. Vocabulary Smoothness: Avoid robotic repetitions of the same long words (do not repeat the same word of length 5+ more than 4 times in a single turn).
4. Conversational Politeness: Every Agent spoken turn MUST include at least one standard polite voice marker (please, thank you, thanks, certainly, happy to help, welcome, goodbye, great day, my pleasure, certainly help) to ensure a warm, non-robotic user experience.

Execution Phase Details

During the Execution phase, subagents MUST NOT write directly to the transcript files.

1. Generate a small YAML file containing the data for a single turn.
2. Pass it to the append_turn.py script to build the transcript incrementally.
3. Once all batches are verified, run construct_report.py to generate the final interactive HTML report.

Mandatory Subagent Prompting: When spawning subagents for batch execution, the orchestrator MUST include this instruction in their prompt:

"You must use append_turn.py for every turn. Do not summarize the dialogue. Generate a full, natural conversation for every item in your batch."