🧠 User Researcher Agent¶

🎯 Purpose¶

The User Researcher Agent is responsible for translating business goals and user-centered design principles into actionable user insights. These insights form the foundation for designing intuitive, efficient, and effective user experiences in the ConnectSoft ecosystem.

🏛️ Core Mission¶

The core mission of the User Researcher Agent is to gather and synthesize user feedback to ensure that business requirements and user needs are aligned.
This process includes:

User behavior analysis: Understanding how users interact with products.
Needs assessment: Identifying unmet user needs and pain points.
Persona development: Creating detailed user personas to guide product design.
Journey mapping: Outlining the user journey to identify improvement opportunities.

The outputs of the User Researcher Agent are critical for ensuring that the UX Designer Agent and UI Designer Agent can create experiences that are user-centered and business-aligned.

🎯 High-Level Objectives¶

Objective	Description
Align Design with Business Goals	Gather and synthesize user insights that directly contribute to business objectives (e.g., reducing churn, increasing engagement).
User-Centered Design	Ensure all user stories, design decisions, and product features are rooted in real user behavior and feedback.
Provide Actionable Insights	Convert raw user feedback into structured, digestible, and actionable insights that inform product design.
Ensure Cross-Department Collaboration	Work with Product Managers, UX/UI Designers, and other agents to ensure alignment between business objectives and user needs.

🏛️ Strategic Role in ConnectSoft AI Software Factory¶

The User Researcher Agent operates in the early stages of the product design process and plays a critical role in ensuring that all designs are user-centered.
It bridges the gap between user insights and design execution.

flowchart TD
    VisionArchitectAgent -->|VisionDocumentCreated| UserResearcherAgent
    UserResearcherAgent -->|UserInsightsReady| UXDesignerAgent
    UXDesignerAgent -->|DesignPrototypesReady| UIPrototyperAgent
    UIPrototyperAgent -->|UIReady| EventBus
    EventBus --> ProductOwnerAgent
    ProductOwnerAgent -->|BacklogReady| EventBus
    EventBus --> UXDesignOutput

Hold "Alt" / "Option" to enable pan & zoom

✅ User Researcher Agent is positioned before UX/UI designers in the flow, ensuring that the design phase is based on solid user insights.

🎯 Key Deliverables¶

Deliverable	Description
User Personas	Detailed representations of the different user types, their goals, challenges, and motivations.
Journey Maps	Visualizations of the user's steps, emotions, pain points, and opportunities within the product.
Usability Reports	Insights from usability testing sessions highlighting what works and what needs improvement.
User Interviews/Surveys	Raw data from user interviews or survey results, analyzed and synthesized into clear findings.
Competitive Analysis	Report on competitor products, identifying strengths, weaknesses, and potential areas for innovation.

🧠 Long-Term Vision¶

The User Researcher Agent ensures that product decisions are informed by user feedback and data, creating a virtuous cycle of continuous improvement in the user experience.

By generating consistent, data-driven insights, the User Researcher Agent:

Helps create a unified understanding of user needs across the product team.
Fosters a user-centered approach to product and UX design.
Contributes to building a product that truly meets user needs and delivers business value.

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Purpose Alignment
User-Centered Design	Directly aligned with the goal of ensuring that user feedback drives product decisions.
Event-Driven Workflow	The agent emits events such as `UserInsightsReady`, which trigger downstream tasks in the design and product phases.
Modular Outputs	Each insight, persona, and research artifact is modular, traceable, and reusable across product and UX design cycles.
Observability-First	Insights, interviews, and reports are fully traceable, logged, and visible for transparency.
Cloud-Native Flexibility	User insights are stored in flexible backends (Blob, Git, SQL, Docs) to ensure scalability and future access.

📋 Responsibilities¶

The User Researcher Agent plays a critical role in ensuring that user-centered research is integrated into the product design process.
It takes the high-level business vision and refines it into actionable insights that drive user experience and user interface design decisions.

🎯 Key Responsibilities¶

Responsibility	Description
User Research	Conduct primary research through methods like user interviews, surveys, usability testing, and focus groups to gather qualitative and quantitative insights.
Persona Development	Create and maintain user personas that represent key user types, their needs, behaviors, and pain points.
Journey Mapping	Map out the user journey to identify key moments, pain points, and opportunities for improvement in the product experience.
Usability Testing	Design and conduct usability tests to evaluate how users interact with the product, identifying issues and opportunities for improvement.
Data Synthesis	Analyze and synthesize user data (both qualitative and quantitative) into clear research reports with actionable insights.
Competitive Research	Conduct competitive analysis to understand user needs, behaviors, and product gaps in relation to competitors.
Report Generation	Create and present user research findings, personas, journey maps, and usability reports to the product, UX, and development teams.
Cross-Department Collaboration	Work closely with UX/UI Designers, Product Managers, and Developers to ensure that user research informs the design and product development decisions.
Knowledge Sharing	Ensure that research findings and user insights are shared across teams, helping to align all stakeholders on user needs and goals.

🧠 Example Deliverables¶

Deliverable	Description
User Personas	Detailed descriptions of user archetypes, including their goals, challenges, behaviors, and motivations.
Journey Maps	Visual diagrams outlining each step of the user's interaction with the product, highlighting pain points and opportunities.
Usability Reports	Findings from usability tests, including key insights on user interactions, pain points, and areas for improvement.
Research Findings	Reports summarizing key insights from user interviews, surveys, and other research activities.
Competitive Analysis	A comparative study of competitor products, identifying strengths, weaknesses, and opportunities for differentiation.
Research Presentations	Presentation decks that summarize research findings for stakeholders.

🎯 Collaboration with Other Agents¶

Agent	Collaboration Details
UX Designer Agent	Provide user insights to inform design decisions, including personas, pain points, and journey maps.
UI Designer Agent	Share findings on user interface preferences, needs, and potential usability improvements.
Product Manager Agent	Align research insights with product strategy, ensure user needs and business goals are aligned.
Product Owner Agent	Support the creation of user-centered stories and acceptance criteria based on research.

🧩 Example: User Research Process¶

Step 1: Research Planning¶

Task: Define the scope of research based on product vision and goals.
Input: Vision Document, strategic objectives, personas.
Output: Research plan with objectives, methodologies, and timelines.

Step 2: Conducting User Research¶

Task: Conduct interviews, surveys, and usability tests with target users.
Input: User personas, research plan.
Output: Raw user data (interviews, test recordings, survey responses).

Step 3: Data Synthesis¶

Task: Analyze and categorize qualitative and quantitative data.
Input: User data from research activities.
Output: Research reports, personas, journey maps.

Task: Generate and share reports with the team, aligning research insights with product design and development.
Input: Research findings, personas, maps.
Output: Presentations and documentation shared with stakeholders.

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Responsibility Alignment
User-Centered Design	Directly aligned with ensuring research insights drive user-centered product design decisions.
Event-Driven Workflow	Outputs (e.g., `UserResearchInsightsReady`, `PersonasReady`) are triggered and consumed by downstream agents.
Modular Outputs	User personas, journey maps, research findings, and reports are independently structured and reusable.
Observability-First	Every major research phase is observable through logs, metrics, and traces.
Cross-Department Collaboration	Collaboration with UX, Product, and Development teams ensures that user research informs every stage of design and development.

📥 Inputs¶

The User Researcher Agent needs a comprehensive set of inputs to generate meaningful, actionable user insights.
These inputs guide the agent in performing detailed user research, creating personas, mapping user journeys, and identifying usability issues.

The primary inputs for the User Researcher Agent are:

Vision Document (providing the strategic context for the research)
Strategic Objectives (ensuring research aligns with business goals)
Personas (existing or new user types that guide the research scope)
Feature List (ensuring research is aligned with planned features)
User Data (from previous research or usage analytics)
Stakeholder Context (business requirements, constraints, and goals)
Historical Data (previous research insights stored in memory)
Competitive Research (if available, used to enrich the current research)

📋 Primary Inputs Consumed by the User Researcher Agent¶

Input Type	Description	Example
Vision Document	High-level strategic document outlining product vision, goals, and initial user types.	"Build a SaaS platform to manage healthcare appointments."
Strategic Objectives	List of business goals tied to the product, guiding the research process.	"Reduce no-shows by 30%; Increase user engagement."
Personas	Pre-existing or newly created user personas representing target user groups.	"Patient: Needs an easy way to book appointments; Doctor: Needs a simple system to manage appointments."
Feature List	A list of planned or existing features that the research should focus on.	"Appointment Scheduling", "Notifications System", "Patient Profile Management."
User Data	Data from previous research, user analytics, or past usability studies.	Previous usability studies on appointment booking systems.
Stakeholder Context	Business goals, constraints, and requirements from key stakeholders.	"System must comply with HIPAA regulations in the US market."
Historical Research Data	Past research reports, user feedback, or data that can enrich the current research process.	"Past user feedback on appointment scheduling features in similar SaaS products."
Competitive Research	Research on competitors or similar products in the market, providing context for the current project.	"Competitive analysis on appointment booking systems in the healthcare industry."

🧠 Input Flow Overview¶

flowchart TD
    VisionDocumentIntake --> VisionParsing
    VisionParsing --> StrategicObjectiveParsing
    StrategicObjectiveParsing --> PersonaParsing
    PersonaParsing --> FeatureListParsing
    FeatureListParsing --> UserDataParsing
    UserDataParsing --> StakeholderContextParsing
    StakeholderContextParsing --> HistoricalDataParsing
    HistoricalDataParsing --> CompetitiveResearchParsing
    CompetitiveResearchParsing --> ContextAssembly
    ContextAssembly --> StructuredInputPrompt

Hold "Alt" / "Option" to enable pan & zoom

✅ All inputs are modularly parsed and assembled into a structured internal input prompt.

📚 Example Input Payloads¶

📄 Vision Document¶

# Vision Document: Healthcare Appointment Management SaaS

## Vision Summary
A SaaS platform to manage patient appointments, aimed at reducing no-shows and improving user engagement.

## Strategic Goals
- Reduce no-shows by 30% within the first 6 months.
- Increase user engagement through online appointment booking and reminders.

## Initial Personas
- Patient: Needs to book and manage appointments easily.
- Doctor: Needs an intuitive system for managing their calendar.

## Features
- Appointment Scheduling
- Notifications System
- Patient Profile Management

📄 Stakeholder Context (Business Constraints)¶

# Business Constraints
- Must comply with HIPAA in the US market.
- MVP must be launched within 4 months, with basic appointment scheduling features.

📄 User Data (From Previous Research)¶

{
  "user_feedback": [
    {
      "user_id": "patient-001",
      "feedback": "Booking an appointment was confusing; I didn't know where to click."
    },
    {
      "user_id": "doctor-001",
      "feedback": "The system should let me view all my appointments at once."
    }
  ]
}

🧩 Knowledge Base and Semantic Memory¶

Scenario	Knowledge Behavior
Research Enrichment	The User Researcher Agent can query past user studies and competitive analysis stored in the semantic memory to enrich the current research.
Persona Enrichment	If new personas need to be created, the agent can pull in existing personas and user feedback from previous projects to build rich, realistic personas.
Journey Mapping	The agent can retrieve past user journey maps and usability test reports to inform its journey mapping process.

📋 Example Memory Retrieval¶

If the agent is tasked with researching "appointment scheduling systems," it might retrieve past research from similar projects:

{
  "previous_research": [
    {
      "project": "Healthcare SaaS Appointment Booking",
      "findings": "Users often fail to complete the scheduling process due to unclear flow."
    },
    {
      "project": "E-Commerce Booking System",
      "findings": "Users prefer appointment reminders via email/SMS."
    }
  ]
}

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Input Handling
Event-Driven Activation	Inputs are retrieved based on incoming events like `VisionDocumentCreated`.
Cloud-Native Integration	Inputs are stored in flexible cloud-native backends like Blob, Git, SQL, or semantic stores.
Modular Outputs	Each input is modular and can be processed independently (e.g., Personas, Features, Constraints).
Observability-First	All input parsing and task initiation steps are fully observable via logs, traces, and metrics.

📤 Outputs¶

The User Researcher Agent produces high-quality, actionable insights that inform user-centered design decisions and ensure the product meets user needs.
These outputs are critical for the next phases of UX Design, UI Design, and Product Planning.

Every output must be business-aligned, user-focused, and easily consumable by downstream agents.

📋 Primary Outputs Produced¶

Artifact	Description	Required Structure
User Personas	Detailed, actionable representations of key user archetypes.	Markdown + JSON
Journey Maps	Visual representation of user experiences and pain points at each step.	Markdown + Diagram (Mermaid or JSON)
Usability Reports	Findings from usability tests with key recommendations.	Markdown + JSON
Research Findings	Key insights from user interviews, surveys, and other research activities.	Markdown + JSON
Competitive Analysis	Comparative study of competitors, identifying strengths, weaknesses, and opportunities.	Markdown + JSON
Empathy Maps	Visual tool representing the user’s thoughts, feelings, pains, and gains during interactions with the product.	Markdown + Diagram (Mermaid or JSON)
Event Emissions	Event payloads indicating that research insights are ready for consumption by downstream agents.	JSON Event Payload

🏗️ Visual: Output Artifact Generation Flow¶

flowchart TD
    UserResearchPlanning --> UserInterviews
    UserInterviews --> DataSynthesis
    DataSynthesis --> UserPersonaCreation
    DataSynthesis --> JourneyMapping
    DataSynthesis --> UsabilityTesting
    UsabilityTesting --> UsabilityReport
    JourneyMapping --> JourneyMapGeneration
    UserPersonaCreation --> PersonaOutput
    JourneyMapGeneration --> EventEmission
    PersonaOutput --> EventEmission
    UsabilityReport --> EventEmission
    EventEmission --> EventBus

Hold "Alt" / "Option" to enable pan & zoom

✅ The agent emits modular research outputs (personas, reports, maps) and event emissions to trigger downstream consumption by other agents.

📚 Example Output Artifacts¶

📋 User Persona Example¶

# Persona: Patient

## Background
- Age: 35
- Occupation: Teacher
- Tech-savviness: Medium

## Goals
- Book appointments quickly and easily without calling.
- Manage health appointments with reminders and updates.

## Frustrations
- Appointment booking is time-consuming.
- Doesn't receive timely appointment confirmations.

## Behaviors
- Prefers to book appointments online.
- Values clear communication from healthcare providers.

## Needs
- Easy-to-use, accessible appointment system.
- Automated reminders and confirmations.

✅ Actionable and aligned with the user’s goals and pain points.

📋 Journey Map Example (Mermaid Diagram)¶

flowchart TD
    Patient -->|Visit Website| AppointmentBooking
    AppointmentBooking -->|Select Available Slot| AppointmentSelection
    AppointmentSelection -->|Confirm Appointment| ConfirmationPage
    ConfirmationPage -->|Receive Confirmation| Patient

    %% Pain points %%
    AppointmentBooking -->|Frustration: Slow Website| PainPoint
    ConfirmationPage -->|Frustration: No Confirmation Received| PainPoint

Hold "Alt" / "Option" to enable pan & zoom

✅ Clear depiction of user frustrations and opportunities for improvement.

📋 Usability Report Example¶

# Usability Testing Report

## Test Overview
- Test conducted with 10 users from different demographics.
- Task: Book an appointment via the web interface.

## Key Findings
- **75% of users** found the appointment booking process intuitive.
- **25% of users** struggled to find the "Book Appointment" button.
- **50% of users** reported confusion about confirmation emails.

## Recommendations
- Improve the visibility of the "Book Appointment" button.
- Simplify the confirmation email language.
- Ensure faster loading times for appointment booking page.

✅ Actionable insights that directly feed into UI Design and UX Improvements.

📋 Event Emission Example¶

{
  "event_type": "UserResearchInsightsReady",
  "trace_id": "user-research-2025-04-27-001",
  "artifact_uri": "https://storage.connectsoft.ai/research/personas/patient-persona-2025-04-27-001.json",
  "timestamp": "2025-04-28T05:00:00Z"
}

✅ Event emission indicates that the research insights are ready for consumption by downstream agents like UX/UI Designers.

📈 Observability Metrics for Output Generation¶

Metric Name	Purpose
`user_researcher_agent_personas_created_total`	Count of total user personas successfully created.
`user_researcher_agent_journey_maps_generated_total`	Count of total journey maps successfully generated.
`user_researcher_agent_usability_tests_conducted_total`	Total usability tests conducted.
`user_researcher_agent_event_emissions_total`	Count of events emitted for output readiness.

✅ These metrics help track output generation and research progress.

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Output Alignment
User-Centered Design	Outputs are user-driven and provide actionable insights for design decisions.
Event-Driven Workflow	Research findings trigger event emissions that activate downstream design and planning workflows.
Modular Outputs	Each output (persona, journey map, report) is atomic and reusable across multiple teams.
Observability-First	Full telemetry, including logs, metrics, and traces, ensures real-time monitoring of research activities.
Cloud-Native Integration	Outputs are stored in flexible cloud-native systems (Blob, Git, SQL, Documentation Systems).

📚 Knowledge Base Overview¶

The User Researcher Agent relies on a comprehensive knowledge base of research frameworks, methodologies, best practices, and tools to conduct effective and consistent user research.
This knowledge base ensures that the agent applies industry standards and proven techniques across various types of research, from user interviews to usability testing.

The knowledge base is dynamic, allowing the agent to expand its understanding as new research methods or domain-specific practices emerge.

📋 Core Knowledge Areas¶

Knowledge Area	Description	Example Tools/Methods
User Research Frameworks	Structured approaches for gathering, analyzing, and interpreting user feedback.	Design Thinking, Double Diamond Framework, Lean UX
User Interview Methodologies	Techniques for conducting in-depth interviews with users to understand their needs, behaviors, and motivations.	Semi-structured Interviews, Contextual Inquiry
Survey Design and Analysis	Creating effective surveys and analyzing quantitative user feedback.	Likert Scales, Multiple Choice Questions, Google Forms
Usability Testing	Conducting tests to evaluate the ease of use and user satisfaction of a product.	Moderated Usability Testing, Unmoderated Usability Testing, A/B Testing
Persona Development	Creating user personas based on qualitative and quantitative data to represent key user segments.	Persona Template (name, demographics, goals, frustrations)
Journey Mapping	Visualizing the user’s interactions, emotions, pain points, and opportunities within a product.	Customer Journey Maps, Experience Maps
Competitor and Market Research	Analyzing competitors and industry trends to understand how the product fits into the broader landscape.	SWOT Analysis, Competitive Matrix
Data Synthesis and Reporting	Analyzing and synthesizing qualitative and quantitative data into actionable research reports.	Affinity Diagrams, Thematic Analysis
Compliance and Ethical Standards	Ensuring that research methods comply with legal and ethical standards.	HIPAA Compliance (in healthcare), GDPR Compliance (in EU)
Historical Data	Previous user research insights and data stored for reuse.	Semantic Memory, Research Database

🧠 Knowledge Base Structure¶

The knowledge base is divided into core research methods, tools, and domain-specific resources.
These resources are utilized by the User Researcher Agent to ensure consistent output and scalable insights.

🧩 User Research Frameworks¶

Framework	Purpose	Example
Design Thinking	A human-centered design framework that emphasizes empathy and iterative problem-solving.	Empathize, Define, Ideate, Prototype, Test.
Double Diamond	A framework that emphasizes divergent and convergent thinking in design and research.	Discover, Define, Develop, Deliver.
Lean UX	A method focused on collaborative and iterative design through experimentation and rapid prototyping.	Build-Measure-Learn cycle for fast feedback loops.

🧩 User Interview Methodologies¶

Methodology	Purpose	Example
Semi-Structured Interviews	Combines both structured questions and open-ended prompts, allowing flexibility during the interview.	Use for detailed user insights on product usage, needs, and pain points.
Contextual Inquiry	Observing users in their natural environment while they use the product, capturing data on behavior and decision-making.	Use to observe and understand how users interact with existing systems.

🧩 Usability Testing Methods¶

Methodology	Purpose	Example
Moderated Usability Testing	Facilitated testing with real-time feedback from the researcher.	In-person or remote sessions where users complete tasks and discuss their experiences.
Unmoderated Usability Testing	Remote usability testing without a moderator, allowing for natural user behavior.	Use tools like Lookback.io or UserTesting to observe users on their own.
A/B Testing	Comparing two versions of a product feature to see which one performs better.	Used for testing design variations, copy changes, or user flow differences.

🧩 Persona Development¶

Tool	Purpose	Example
Persona Template	A standardized format for creating user personas.	Name, Age, Occupation, Needs, Goals, Challenges.
Persona Workshops	Collaborative sessions with stakeholders to define and validate personas.	Gather data from interviews, surveys, and analytics to build detailed personas.

🧩 Journey Mapping¶

Tool	Purpose	Example
Customer Journey Map	A visual representation of the customer’s end-to-end experience with a product or service.	Identify touchpoints, pain points, and opportunities to enhance the experience.
Experience Map	A broader visualization that considers emotions and behaviors over time.	Used to capture the holistic user experience, including before and after product use.

🧩 Semantic Memory (Optional)¶

Usage	Example
Domain-Specific Memory Retrieval	Retrieve past research findings on specific topics (e.g., healthcare, education, e-commerce).
Previous Project Insights	Reuse insights, personas, and journey maps from similar projects.

📚 Example Knowledge Base Asset: Research Frameworks Template¶

# Design Thinking Framework

## Phases:
- **Empathize**: Understand the user's needs through research.
- **Define**: Clearly define the problem you're solving.
- **Ideate**: Brainstorm solutions.
- **Prototype**: Build simple, testable versions of the ideas.
- **Test**: Conduct usability tests and refine.

## Best Practices:
- Involve users throughout the design process.
- Iterate and refine solutions quickly based on user feedback.

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Knowledge Base Contribution
Domain-Driven Design	Research methods align with user behavior models and persona-driven design.
Modular and Scalable Outputs	Knowledge is structured to ensure reusability and scalability in various product contexts.
Event-Driven Workflow	Research insights trigger events (e.g., `UserInsightsReady`, `PersonasReady`) for downstream use.
Observability	Research insights are logged, traced, and monitored for transparency and quality assurance.
Cloud-Native Flexibility	Knowledge assets are stored in cloud-native systems, ensuring scalability and access across multiple products.

🔄 Process Flow Overview¶

The User Researcher Agent follows a structured process to conduct user research and generate actionable insights.
Each phase in this process is designed to ensure that the research is systematic, comprehensive, and aligned with the user needs and business goals.

The process flow includes:

Research Planning
Data Collection (e.g., user interviews, surveys)
Data Synthesis and Analysis
Insight Generation
Report Creation and Sharing

📋 User Researcher Agent Process Phases¶

Phase	Description
1. Research Planning	Define the scope, objectives, and methodologies for the user research project.
2. Data Collection	Collect qualitative and quantitative data via methods like interviews, surveys, usability testing, and analytics.
3. Data Synthesis	Analyze and categorize the collected data to identify patterns, trends, and key findings.
4. Insight Generation	Generate actionable insights from the data, focusing on user pain points, behaviors, and needs.
5. Report Creation	Organize and create research reports, personas, journey maps, and usability reports.
6. Insight Sharing	Share research findings with downstream agents (UX Designers, Product Managers, etc.) via events and reports.
7. Event Emission	Emit events to signal the completion of research and the readiness of insights for downstream use.

🧩 Detailed Process Flow¶

flowchart TD
    ResearchPlanning["1. Research Planning"]
    ResearchPlanning --> DataCollection["2. Data Collection"]
    DataCollection --> DataSynthesis["3. Data Synthesis"]
    DataSynthesis --> InsightGeneration["4. Insight Generation"]
    InsightGeneration --> ReportCreation["5. Report Creation"]
    ReportCreation --> InsightSharing["6. Insight Sharing"]
    InsightSharing --> EventEmission["7. Event Emission"]
    EventEmission --> EventBus
    EventBus --> UXDesignerAgent
    EventBus --> ProductManagerAgent
    EventBus --> UIPrototyperAgent

Hold "Alt" / "Option" to enable pan & zoom

✅ Clear, modular, event-driven process for effective user research and knowledge sharing.

📚 Example Workflow¶

Phase 1: Research Planning¶

Task: Define the objectives and scope of the research.
Input: Vision Document, strategic goals, personas.
Output: Research plan (objectives, methodologies, timeline).

Example: - Objective: Understand how users schedule appointments online. - Methodology: Conduct 10 user interviews, 5 usability tests, and a user survey.

Phase 2: Data Collection¶

Task: Collect data from users via interviews, surveys, and usability tests.
Input: Research plan, personas, and feature list.
Output: Raw user data (interview transcripts, survey responses, usability test results).

Example: - Interview: "Tell me about your experience when scheduling an appointment online." - Survey: 10 multiple choice questions about appointment scheduling challenges.

Phase 3: Data Synthesis¶

Task: Analyze the collected data and identify patterns and trends.
Input: Raw data (interviews, surveys, usability test results).
Output: Key findings, categorized insights, and themes.

Example: - Finding: 70% of users struggle to find available appointment times. - Pattern: Users prefer receiving appointment reminders via SMS.

Phase 4: Insight Generation¶

Task: Generate actionable insights based on the data.
Input: Categorized insights and user behavior patterns.
Output: Research findings and actionable recommendations.

Example: - Insight: "Simplify the appointment scheduling interface to make available slots more prominent." - Recommendation: "Introduce a new 'available slots' filter and implement SMS reminders for appointments."

Phase 5: Report Creation¶

Task: Create formal research reports (personas, journey maps, usability findings).
Input: Insights, research findings, journey maps, personas.
Output: Research report, personas, journey maps.

Example: - Persona: "Patient: Needs a quick and intuitive way to book appointments." - Journey Map: "Step 1: Visit Website ➔ Step 2: Choose Appointment ➔ Step 3: Confirm Appointment"

Task: Share research findings with downstream teams (UX/UI Designers, Product Managers).
Input: Research report, personas, usability findings.
Output: Research insights shared via events and documentation.

Example: - Event Emission: UserResearchInsightsReady - Share via Event: "Personas and journey maps are ready for UX/UI design."

Phase 7: Event Emission¶

Task: Emit events once research is complete and insights are ready for downstream consumption.
Input: Final research outputs (personas, reports, journey maps).
Output: Events such as UserResearchInsightsReady, PersonasReady.

Example:

{
  "event_type": "UserResearchInsightsReady",
  "trace_id": "user-research-2025-04-27-001",
  "artifact_uri": "https://storage.connectsoft.ai/research/personas/patient-persona-2025-04-27-001.json",
  "timestamp": "2025-04-28T06:00:00Z"
}

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Process Flow Reflection
Event-Driven Activation	Each research phase culminates in event emissions to trigger downstream actions.
Modular Outputs	Each output (persona, report, journey map) is modular, reusable, and easy to consume.
Observability-First	Full telemetry is emitted at every critical step (data collection, synthesis, insight generation, event emission).
Resilient Execution	Automatic retries and corrections in case of failures or missing insights.
User-Centered Design	All outputs are directly aligned with user needs and business goals.

🛠️ Technologies Overview¶

The User Researcher Agent is built using a cloud-native, modular, and event-driven technology stack
to ensure that it can scale, integrate, and work autonomously while conducting user research.

The stack is designed to handle the full user research lifecycle — from research planning to data collection, analysis, and output sharing.

📋 Core Technology Stack¶

Technology	Purpose	Example Usage
Semantic Kernel (.NET)	Orchestrates the modular skills of the agent (e.g., user interview synthesis, persona creation, journey mapping).	Use for chaining skills like user data extraction, synthesis, and persona creation.
OpenAI Models (Azure OpenAI, OpenAI API)	Provides LLM reasoning for user research tasks such as synthesizing user interview data, generating personas, or creating journey maps.	"Generate a user persona based on user feedback from the survey results."
Survey and Interview Tools	Collect qualitative and quantitative data from users (interviews, surveys, usability tests).	SurveyMonkey, Google Forms, Typeform, Lookback.io for live usability testing.
Event Bus (Azure Event Grid, Kafka)	Event-driven communication system that emits events like `UserResearchInsightsReady` and allows integration with downstream agents (UX/UI Designers, Product Managers).	Emit events when research findings are ready for consumption by other agents.
Cloud Storage (Blob Storage, SQL)	Stores raw data (interview transcripts, survey responses) and processed research artifacts (personas, reports, journey maps).	Use Azure Blob Storage for research reports and SQL Database for storing user feedback data.
Observability Tools (OpenTelemetry, Prometheus, Grafana)	Track agent performance and research progress through metrics, logs, and traces.	Use Prometheus to monitor research completion rates and Grafana for real-time dashboards.
User Data Storage (Optional)	Manage and query user data, historical research insights, and demographic information for enriched research analysis.	Use Azure SQL or NoSQL Databases for storing historical research insights.

🏗️ Component Diagram for User Researcher Agent Technologies¶

flowchart TD
    EventBus -->|UserResearchInsightsReady| UXDesignerAgent
    EventBus -->|UserResearchInsightsReady| ProductManagerAgent
    EventBus -->|UserResearchInsightsReady| UIPrototyperAgent
    EventBus -->|UserResearchInsightsReady| EventBus

    SemanticKernel -->|Skill Chaining| SurveyTools
    SurveyTools -->|Collect Data| UserResearchData
    UserResearchData -->|Store Data| BlobStorage
    UserResearchData -->|Store Data| SQLDatabase
    UserResearchData -->|Generate Insights| OpenAI
    UserResearchData -->|Generate Personas| OpenAI
    UserResearchData -->|Generate JourneyMaps| OpenAI
    UserResearchData -->|Generate Reports| EventBus
    OpenTelemetry -->|Logs, Metrics, Traces| ObservabilityTools
    Prometheus -->|Monitor Progress| Grafana

Hold "Alt" / "Option" to enable pan & zoom

✅ Modular stack, with event-driven output and observable processes.

📚 Example Tool Usage¶

Survey and Interview Tools¶

Tool	Purpose	Example Usage
SurveyMonkey	Collect user survey responses to identify patterns in user behaviors.	"Send out a survey to 100 users asking about appointment scheduling frustrations."
Google Forms	Create user surveys to quantify user pain points.	"Design a multiple-choice survey to understand which appointment features users find most useful."
Lookback.io	Conduct remote usability testing with live user feedback.	"Conduct live usability testing with 10 users interacting with the prototype and gather feedback."

Event Bus Integration¶

Event	Payload Example	Purpose
`UserResearchInsightsReady`	`{ "event_type": "UserResearchInsightsReady", "trace_id": "research-2025-04-27-001", "artifact_uri": "https://storage.connectsoft.ai/research/personas/patient-persona-2025-04-27-001.json", "timestamp": "2025-04-28T06:00:00Z" }`	Signals that the research findings are ready for downstream consumption by agents like UX Designers or Product Managers.

OpenAI Models¶

Usage: The OpenAI models are used to synthesize qualitative user data from interviews or surveys and to create personas or journey maps.
Example Prompt:
"Generate a detailed user persona for a patient who needs to book medical appointments online. Include demographics, goals, challenges, behaviors, and motivations."

🧩 Observability Tools¶

The User Researcher Agent emits telemetry data at every stage of the research process, ensuring full visibility and traceability.

Tool	Purpose	Example
OpenTelemetry	Tracks all research activities (interviews, surveys, data synthesis).	"Track and report the completion time for each interview session and the number of surveys completed."
Prometheus	Monitors and stores real-time metrics related to research progress and agent health.	"Track the total number of research reports generated in the past 24 hours."
Grafana	Visualizes the metrics from Prometheus for real-time monitoring.	"Create a dashboard to display the total number of personas, journey maps, and usability reports generated."

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Technology Alignment
Event-Driven Architecture	The agent emits events like `UserResearchInsightsReady`, triggering downstream agents.
Cloud-Native Integration	The research outputs (reports, personas) are stored in flexible, cloud-native systems (Blob, SQL, Git).
Observability-First	OpenTelemetry, Prometheus, and Grafana are used to monitor and log every agent action for full visibility.
Resilient Execution	Built-in retry and correction flows ensure that research findings are accurate, complete, and aligned with user goals.
Modular Outputs	Research reports, personas, and journey maps are independent and actionable across departments (UX/UI, Product).

📝 System Prompt (Initialization Instruction)¶

The System Prompt is a foundational instruction that bootstraps the User Researcher Agent.
It defines the role, behavior, and operational scope of the agent, guiding its reasoning and task completion.

The prompt ensures that the agent:

Operates with user-centered design principles.
Aligns research insights with business goals.
Produces actionable outputs like personas, journey maps, and usability reports.

📋 Full System Prompt Text¶

🧠 You are a User Researcher Agent within the ConnectSoft AI Software Factory.
Your mission is to conduct user research, gather user feedback, and synthesize actionable insights to guide product and UX/UI design decisions.

You will: - Conduct user interviews, surveys, usability tests, and other research methods to gather data on user behaviors, goals, pain points, and motivations. - Analyze and synthesize qualitative and quantitative data to identify key patterns and insights. - Develop personas to represent different user types, their needs, behaviors, and challenges. - Create journey maps to visualize the user’s experience with the product, identifying pain points and opportunities for improvement. - Generate usability reports with actionable findings that inform the UX/UI design process. - Collaborate with UX Designers, UI Designers, and Product Managers to ensure that user insights are incorporated into the product development process. - Emit events such as UserResearchInsightsReady, PersonasReady, and JourneyMapsReady to trigger downstream actions.

📋 Rules and Expectations: - Your outputs must be aligned with the user’s needs, pain points, and business goals. - Ensure all research is comprehensive and objective, with clear recommendations. - Provide actionable insights that are usable by designers and product teams. - Embrace cloud-native standards for storing research findings (e.g., Blob, Git, SQL). - Observability-first: Log all key actions, research findings, and events for full traceability and transparency.

🎯 Purpose of the System Prompt¶

Objective	Why It’s Important
Define Role and Scope	Ensures the agent focuses on user-centered research and insight generation rather than tasks like design or development.
Align Research with Business Goals	Guarantees that user research is aligned with strategic objectives (e.g., reducing churn, increasing engagement).
Provide Actionable Outputs	All outputs (personas, reports, journey maps) must be usable by UX/UI Designers and Product Managers.
Ensure Consistency	The prompt enforces a consistent, structured approach to gathering, analyzing, and reporting user insights.
Guarantee Observability	The agent must log actions, metrics, and traces for transparency and troubleshooting.

🧠 Key Output Expectations Based on System Prompt¶

Output Type	Description
Personas	Detailed user profiles representing key user types, including behaviors, goals, and pain points.
Journey Maps	Visual diagrams illustrating the user’s path, emotions, and pain points during interaction with the product.
Usability Reports	Reports with insights from usability testing, highlighting areas for improvement.
Research Findings	Synthesized key insights from user interviews, surveys, and usability tests.
Event Emissions	Events such as `UserResearchInsightsReady`, `PersonasReady`, and `JourneyMapsReady` that signal downstream actions can proceed.

🧩 Example Behavioral Directives¶

Directive	Impact
User-Centered Research	Focus on understanding user behaviors, goals, and pain points — outputs must be user-driven.
Actionable Insight Generation	Ensure research findings lead to clear, implementable recommendations for design teams.
Cross-Department Collaboration	Collaborate with UX Designers, UI Designers, and Product Managers to ensure research insights directly influence product design decisions.
Modular and Reusable Outputs	Create modular research artifacts that can be reused across projects and teams.
Observability and Transparency	Track all research activities and insights through logs, metrics, and traces for real-time monitoring.

🧩 ConnectSoft Platform Principles Alignment¶

Principle	System Prompt Alignment
User-Centered Design	Directly aligned with ensuring the agent’s outputs represent user needs and behaviors.
Event-Driven Activation	The agent emits events such as `UserResearchInsightsReady`, which trigger downstream tasks in UX/UI design and product planning.
Modular Outputs	Research insights, personas, and reports are modular, reusable, and actionable.
Observability-First	The system prompt ensures that all key research activities and outputs are traceable and observable.
Cloud-Native Integration	Outputs are stored in flexible, cloud-native systems (Blob, Git, SQL) to ensure scalability and access across teams.

📥 Input Prompt Template¶

The Input Prompt Template defines how incoming tasks (e.g., research project initiation, vision updates) are transformed into a structured, actionable prompt for the User Researcher Agent.
It helps the agent process and interpret the information provided in the task, ensuring that it can efficiently conduct user research and produce actionable insights.

📋 Structure of the Input Prompt Template¶

Input Component	Description	Example
Vision Summary	A high-level summary of the product vision. Provides context for the research.	"A SaaS platform for healthcare appointment scheduling aimed at reducing no-shows."
Strategic Objectives	The business goals that the research aims to support (e.g., increasing engagement, reducing churn).	"Reduce no-shows by 30%, improve user engagement by 40%."
Personas Defined	A list of key user personas to consider during the research.	"Patient, Doctor, Admin Staff."
Feature List	List of features or areas that the research should focus on (e.g., appointment scheduling, reminders).	"Appointment Scheduling, Notifications, User Profiles."
User Data (Existing)	Data from previous research or user behavior data that will inform the research.	"Survey results on appointment scheduling frustrations."
Stakeholder Context	Business requirements, constraints, and goals provided by stakeholders.	"Must comply with HIPAA regulations, MVP deadline is 4 months."
Research Scope	The specific area of user experience the research will focus on (e.g., booking experience, notification system).	"Focus on the patient booking experience and appointment reminders."
Methodology	The specific methods to be used for data collection (e.g., surveys, interviews, usability testing).	"10 in-depth user interviews, 2 rounds of usability testing, 1 user survey."
Competitive Landscape (Optional)	Research on competitors and similar products that may inform the user research.	"Competitive analysis on appointment scheduling systems in healthcare."

🧠 Example Structured Input Prompt¶

## Input Information

**Vision Summary:**
A SaaS platform for healthcare appointment scheduling aimed at reducing no-shows.

**Strategic Objectives:**
- Reduce no-shows by 30%
- Increase user engagement by 40%

**Personas Defined:**
- Patient: Needs to easily book and manage appointments.
- Doctor: Needs an intuitive system to manage appointments.
- Admin Staff: Manages appointment schedules and updates.

**Feature List:**
- Appointment Scheduling
- Notifications (SMS/Email Reminders)
- User Profiles (patient and doctor)

**User Data (Existing):**
- Survey results show that 70% of patients find appointment scheduling confusing.
- Previous usability tests highlight frustration with not receiving reminders.

**Stakeholder Context:**
- Must comply with HIPAA regulations in the US.
- MVP must launch in 4 months, focusing on appointment scheduling and notifications.

**Research Scope:**
- Focus on the patient booking experience, especially the notification system.

**Methodology:**
- 10 user interviews, 2 rounds of usability testing, 1 user survey.

**Competitive Landscape (Optional):**
- Analyze competitors' appointment scheduling systems in the healthcare industry.

🧩 Process of Using the Input Prompt Template¶

Initial Task Received: The User Researcher Agent receives a task (e.g., "Research patient booking experience").
Parsing: The agent parses the Vision Document, strategic objectives, personas, feature list, and methodologies to understand the scope and requirements.
Context Assembly: The agent assembles the input information into a structured prompt for the task, which includes the methodology, user personas, and focus areas.
Execution: The agent uses the structured prompt to initiate data collection (e.g., interviews, surveys) and begin data synthesis.

🎯 Example Workflow Based on the Input Template¶

Step 1: Research Planning¶

Input: Vision summary, strategic goals, and user personas.
Output: Research plan, detailing objectives, methodology, and scope.

Step 2: Data Collection¶

Input: Research plan, methodology (user interviews, surveys, usability tests).
Output: Raw user data, including interview transcripts, survey responses, and usability test results.

Step 3: Data Synthesis and Analysis¶

Input: Raw user data.
Output: Categorized insights, key findings, user pain points.

Step 4: Report Generation¶

Input: Synthesized insights, persona data, journey maps.
Output: Research report, personas, journey maps, usability findings.

Step 5: Event Emission¶

Input: Research findings, completed personas, journey maps.
Output: Event emissions signaling research completion (UserResearchInsightsReady, PersonasReady, JourneyMapsReady).

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Input Handling
Event-Driven Workflow	The prompt triggers actions and workflows, and event emissions ensure smooth transitions.
Modular Inputs and Outputs	Each piece of data (e.g., personas, surveys, findings) is treated as an independent module that can be reused across multiple research tasks.
Observability-First	Every action is logged, traced, and tracked with metrics, logs, and traces.
Cloud-Native Flexibility	The structured prompt and outputs are compatible with cloud-native backends (Blob Storage, SQL, Git).

📤 Output Expectations¶

The User Researcher Agent is responsible for producing actionable insights that directly influence product design and user experience decisions.
The quality of these insights is paramount, as they guide UX/UI Designers, Product Managers, and other stakeholders in building user-centered products.

Each output must meet the following quality standards:

Business Relevance: Align with business goals and product strategy.
User Focused: Rooted in real user behaviors, pain points, and needs.
Clarity and Structure: Organized and easy to digest for non-research stakeholders.
Actionable: Provide clear, implementable recommendations or insights.
Traceability: Ensure outputs link back to user research goals, strategic objectives, and personas.

📋 Expected Output Artifacts¶

Artifact	Description	Required Structure
User Personas	Detailed, actionable representations of user archetypes, including their goals, behaviors, pain points, and motivations.	Markdown + JSON
Journey Maps	Visual representations of the user's interaction with the product, highlighting pain points and opportunities.	Mermaid Diagrams + Markdown
Usability Reports	Insights from usability tests with clear findings on user interaction issues.	Markdown + JSON
Research Findings	Synthesized key insights from user interviews, surveys, and tests.	Markdown + JSON
Competitive Analysis	A comparative study of competitor products with insights into user needs, behavior, and gaps.	Markdown + JSON
Empathy Maps	Visual tool representing users’ thoughts, feelings, pains, and gains during interactions with the product.	Mermaid Diagrams + Markdown
Event Emissions	Event payloads indicating that user research insights are ready for downstream consumption.	JSON Event Payload

🧩 Output Validation¶

Each output produced by the User Researcher Agent must be validated for:

Business Alignment: Does it align with the product vision, business goals, and stakeholder needs?
User-Centered Design: Is the insight rooted in real user behavior, needs, and pain points?
Completeness: Are all the required fields populated (e.g., user needs, behaviors, journey steps)?
Testability: Are findings actionable, with clear, measurable recommendations or improvements?
Clarity and Structure: Is the output easy to read and understand by both researchers and stakeholders (UX Designers, Product Managers)?

🧠 Example Output Validation Criteria¶

Persona Validation Criteria¶

Criteria	Requirement
User-Centered	The persona must be based on real user data (e.g., interview feedback, survey results).
Actionable	The persona must provide clear, specific insights into user goals, challenges, and motivation.
Complete	The persona must include key sections: demographics, goals, pain points, behaviors, motivations.
Traceability	The persona must link to the Vision Document and strategic goals (e.g., reducing churn, improving engagement).

Journey Map Validation Criteria¶

Criteria	Requirement
User-Centered	The journey map must reflect the actual user experience, based on data collected through usability testing or interviews.
Complete	The journey map must include all relevant touchpoints, pain points, and user emotions throughout the process.
Actionable	The map should clearly highlight areas for improvement and design opportunities.
Clarity	The map must be easy to read, with a clear flow and no ambiguity in the user’s journey.

🧩 Example of Valid Output: Persona¶

# Persona: Patient (Primary User)

## Background
- **Age**: 35
- **Occupation**: Teacher
- **Tech-savviness**: Medium

## Goals
- **Book appointments quickly and easily** without calling the office.
- **Receive appointment reminders** so they don't forget about appointments.

## Pain Points
- **Appointment scheduling is confusing**, with unclear steps and processes.
- **Doesn’t receive timely reminders**, leading to missed appointments.

## Behaviors
- **Uses smartphone** for most tasks.
- **Prefers digital solutions** over manual (calling the clinic).

## Motivations
- Wants to **manage healthcare appointments efficiently** without taking too much time.
- **Values convenience** in all aspects of life, including healthcare.

## Technology Use
- **Device**: iPhone
- **Apps**: Google Calendar, healthcare apps, social media

## Quotes
- "I wish I could book appointments without calling, it takes too much time."
- "I always forget my appointments unless I get a reminder on my phone."

## Recommendations
- Simplify the **appointment scheduling** process (less manual effort).
- Implement **appointment reminders** via SMS or mobile notifications.

✅ Actionable, user-centered, aligned with business goals.

🧩 Example of Valid Output: Journey Map (Mermaid Syntax)¶

flowchart TD
    Patient -->|Visit Website| AppointmentBooking
    AppointmentBooking -->|Select Available Slot| AppointmentSelection
    AppointmentSelection -->|Confirm Appointment| ConfirmationPage
    ConfirmationPage -->|Receive Confirmation| Patient

    %% Pain points %%
    AppointmentBooking -->|Frustration: Slow Website| PainPoint
    ConfirmationPage -->|Frustration: No Confirmation Received| PainPoint

Hold "Alt" / "Option" to enable pan & zoom

✅ User-centered, clear representation of the user journey with pain points.

🧠 Event Emission Example¶

{
  "event_type": "UserResearchInsightsReady",
  "trace_id": "user-research-2025-04-27-001",
  "artifact_uri": "https://storage.connectsoft.ai/research/personas/patient-persona-2025-04-27-001.json",
  "timestamp": "2025-04-28T06:00:00Z"
}

✅ Event emission signals that research insights are ready for consumption by downstream agents like UX/UI Designers.

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Output Expectations Alignment
User-Centered Design	All outputs (personas, journey maps, usability reports) are user-centered and actionable.
Event-Driven Workflow	Outputs trigger downstream actions, ensuring smooth handoff to UX/UI Design and Product Planning.
Modular Outputs	Research findings, personas, and reports are atomic, traceable, and reusable across teams.
Observability-First	Every output is logged, monitored, and tracked for transparency.
Cloud-Native Flexibility	Outputs are stored in flexible systems (Blob, SQL, Git) for scalability and easy access.

🧠 Memory Management Overview¶

The User Researcher Agent uses dual-memory management to handle short-term and long-term research data efficiently. This enables the agent to:

Operate autonomously on a per-task basis (short-term memory).
Learn and build upon previous research insights (long-term memory).
Continuously improve the quality and relevance of its outputs across research cycles.

Both short-term memory and long-term semantic memory contribute to user-centered research by ensuring that the agent can reuse existing knowledge, adapt to new insights, and provide real-time actionable findings.

📋 Short-Term Memory (STM)¶

Aspect	Description
Scope	Focused on the current task context — specific research sessions, tasks, and immediate research outputs (e.g., persona creation, interview results).
Stored Content	Research session data such as interview transcripts, survey responses, usability test findings, and research objectives.
Purpose	To ensure the agent can process and synthesize user data during the current research cycle.
Storage	In-memory storage, temporary for active sessions.
Lifetime	Cleared once the task is completed, and artifacts (e.g., personas, reports) are emitted or stored.

✅ Short-term memory ensures the User Researcher Agent remains focused on the current research task, avoiding overload from older data.

📂 Long-Term Semantic Memory (LTM)¶

Aspect	Description
Scope	Encompasses historical research insights from past projects and research sessions.
Stored Content	User research reports, personas, journey maps, usability tests, competitive analysis data, domain-specific knowledge.
Purpose	To enable the agent to revisit past research, ensuring continuity and learning across projects.
Storage	External memory stores such as semantic vector databases or cloud-native storage (e.g., Azure Cognitive Search, Pinecone).
Lifetime	Persistent and updated throughout the agent's operation; enriched as new insights are collected.

✅ Long-term memory allows the User Researcher Agent to learn from previous research projects, providing a knowledge base to enrich new tasks.

🧠 Memory Integration Flow¶

flowchart TD
    TaskIntake["1. Research Task Intake"] -->|Store in STM| ShortTermMemory
    ShortTermMemory -->|Research Data (Interviews, Surveys)| DataSynthesis
    DataSynthesis -->|Persona Creation, Journey Mapping| ShortTermMemory
    ShortTermMemory -->|Emit Research Insights| EventEmission
    EventEmission -->|Store in LTM| LongTermMemory

    LongTermMemory -->|Retrieve Past Insights| DataEnrichment
    DataEnrichment -->|Enhance New Task| ShortTermMemory

Hold "Alt" / "Option" to enable pan & zoom

✅ Seamless flow of user research data from short-term memory to long-term storage, enabling knowledge enrichment.

📚 Example Use of Memory¶

Short-Term Memory Use Case¶

During a user interview, the agent collects raw data (e.g., interview transcript). The agent stores this in short-term memory while conducting the synthesis and analysis. Once the analysis is complete and the insights are generated (e.g., personas, journey maps), they are emitted as events (e.g., UserResearchInsightsReady) and stored in long-term memory for future reference.

Example: - Short-Term Memory: The agent collects interview responses during a usability test and analyzes the user behavior related to appointment scheduling. - Long-Term Memory: The persona and journey maps created from this session are stored in long-term memory for use in future research cycles.

Long-Term Memory Use Case¶

In subsequent research cycles, the User Researcher Agent can retrieve past insights, like a persona or journey map, from long-term memory to enrich new research tasks. For example, it might use an existing persona to explore how that user archetype would respond to a new feature.

Example: - Long-Term Memory: Retrieve the Persona of a patient from a previous healthcare appointment system. - Short-Term Memory: Use the persona to analyze new user feedback for a new feature in the appointment scheduling process.

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Memory Management Alignment
Event-Driven Workflow	Short-term memory is used for immediate tasks, while long-term memory stores enriched insights for future use.
Resilient Execution	Long-term memory ensures that the User Researcher Agent can reuse past insights and avoid redundant work.
Observability-First	All memory interactions (task context, insights, events) are logged, traced, and monitored for visibility.
Cloud-Native Scalability	Memory is stored in cloud-native systems that scale with the agent’s research tasks and historical data (e.g., Blob Storage, Azure Cognitive Search).
Modular Memory	Short-term and long-term memory modules are separate and designed for scalability and data freshness.

✅ Validation Strategy¶

The User Researcher Agent must validate its outputs to ensure that they are accurate, complete, user-centered, and aligned with business goals.
Each research artifact—whether it be personas, journey maps, usability reports, or research findings—must meet certain criteria before it is shared with downstream agents like UX Designers or Product Managers.

The validation strategy also ensures that all outputs are actionable, clear, and aligned with the overall product strategy.

📋 Key Validation Areas¶

Validation Type	Description
Business Relevance	Ensures all research outputs align with the strategic business goals and user needs.
Completeness	Confirms that all required information is captured (e.g., persona details, journey map stages, usability test findings).
User-Centered Design	Validates that all findings and recommendations are rooted in real user data and user pain points.
Actionability	Ensures that insights and recommendations can be translated into design decisions and development tasks.
Traceability	Ensures that all outputs can be traced back to the Vision Document, personas, and user research goals.
Ethical and Compliance Validation	Ensures that all research outputs comply with ethical standards (e.g., GDPR, HIPAA in healthcare).

🎯 Example Validation Criteria¶

Persona Validation Criteria¶

Validation Area	Requirement
Business Relevance	The persona must reflect real user behaviors, goals, and pain points that align with the Vision.
Completeness	The persona must include key elements: name, demographics, goals, frustrations, motivations, technology use.
User-Centered	The persona must be based on real user data from interviews, surveys, or usability tests.
Actionability	The persona must provide actionable insights that can guide UX/UI design decisions.

Journey Map Validation Criteria¶

Validation Area	Requirement
Business Relevance	The journey map must reflect the user’s actual experience with the product.
Completeness	The map must cover all stages of the user journey, from initial contact to final interaction, including pain points and opportunities.
User-Centered	The journey map must highlight real user emotions, pain points, and motivations at each stage.
Actionability	The map must identify key pain points and improvement opportunities for design teams.

Usability Report Validation Criteria¶

Validation Area	Requirement
Business Relevance	Usability findings must focus on critical user flows and interactions that align with product goals.
Completeness	All usability test sessions must be documented, including tasks, user feedback, and issues.
Actionability	The report must contain clear, actionable recommendations for improving the user experience.

📈 Example of Output Validation Process¶

Step 1: Persona Validation
Input: Raw persona data from user interviews, survey responses.
Validation: Check if persona contains essential details (e.g., demographics, goals, frustrations).
Outcome: Validated persona ready for consumption.
Step 2: Journey Map Validation
Input: User journey stages, touchpoints, pain points.
Validation: Check if journey map aligns with real user data, highlights pain points, and offers actionable insights.
Outcome: Validated journey map for UX improvement.
Step 3: Usability Test Report Validation
Input: Usability testing sessions with users.
Validation: Ensure test findings include clear user feedback and recommended improvements.
Outcome: Usability test report with actionable suggestions.

🧠 Validation Workflow¶

flowchart TD
    PersonaCreation --> PersonaValidation
    PersonaValidation -->|Valid| JourneyMapping
    PersonaValidation -->|Invalid| PersonaCorrection
    JourneyMapping --> JourneyValidation
    JourneyValidation -->|Valid| UsabilityTesting
    JourneyValidation -->|Invalid| JourneyCorrection
    UsabilityTesting --> UsabilityValidation
    UsabilityValidation -->|Valid| EventEmission
    UsabilityValidation -->|Invalid| UsabilityCorrection
    EventEmission --> EventBus
    EventBus --> UXDesignerAgent
    EventBus --> ProductManagerAgent
    EventBus --> UIPrototyperAgent

Hold "Alt" / "Option" to enable pan & zoom

✅ Step-by-step validation for all key user research outputs before they are emitted for downstream consumption.

📋 Validation Example¶

Persona Validation Example¶

# Persona: Patient (Primary User)

## Background
- **Age**: 35
- **Occupation**: Teacher
- **Tech-savviness**: Medium

## Goals
- **Book appointments quickly** without calling the office.
- **Receive appointment reminders** so they don’t forget about appointments.

## Pain Points
- **Appointment scheduling is confusing**.
- **No timely reminders** for appointments.

## Behaviors
- **Uses smartphone** for scheduling and reminders.
- **Prefers digital solutions** over phone calls.

## Motivations
- Wants to **manage healthcare appointments efficiently** without taking too much time.
- **Values convenience** in all aspects of life, including healthcare.

## Validation
- **Business Relevance**: Aligns with the strategic goal of improving user engagement and reducing no-shows.
- **Completeness**: Covers **goals**, **frustrations**, and **motivations**.
- **User-Centered**: Based on real user interviews and surveys.
- **Actionability**: Provides clear insights for designing an appointment scheduling system that **reduces friction**.

Journey Map Validation Example¶

flowchart TD
    Patient -->|Visit Website| AppointmentBooking
    AppointmentBooking -->|Select Available Slot| AppointmentSelection
    AppointmentSelection -->|Confirm Appointment| ConfirmationPage
    ConfirmationPage -->|Receive Confirmation| Patient

    %% Pain points %%
    AppointmentBooking -->|Frustration: Slow Website| PainPoint
    ConfirmationPage -->|Frustration: No Confirmation Received| PainPoint

    %% Opportunities %%
    AppointmentBooking -->|Opportunity: Highlight Available Slots| Opportunity
    ConfirmationPage -->|Opportunity: Send Instant Confirmation Email| Opportunity

Hold "Alt" / "Option" to enable pan & zoom

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Validation Alignment
User-Centered Design	All research outputs must be based on real user data and provide actionable insights.
Modular Outputs	Each output (persona, journey map, usability report) is independent, traceable, and reusable across teams.
Event-Driven Activation	Outputs trigger events to notify downstream agents (e.g., UX Designers, Product Managers) that research insights are ready for action.
Observability-First	Every validation and output is logged and traced to ensure transparency and accountability.

🔁 Retry and Correction Flow¶

The User Researcher Agent is designed to auto-correct errors, retry failed processes, and self-heal when outputs (e.g., personas, research reports, journey maps) do not meet the expected validation criteria.

The retry and correction flow ensures that the agent can continue working autonomously, minimizing manual intervention. This enhances the resilience, scalability, and efficiency of the agent within the ConnectSoft AI Software Factory.

📋 Key Correction Mechanisms¶

Error Type	Correction Strategy	Retry Behavior
Missing Data	Automatically fill missing fields using default templates or previous context.	Retry validation after auto-filling missing information.
Format Errors	Reformat the output to comply with the required structure (e.g., Markdown, JSON).	Retry after reformatting the output.
Incomplete Research Outputs	Regenerate missing or incomplete outputs (e.g., missing personas or journey steps).	Retry after regenerating the missing output.
Invalid Insight	Use a fallback strategy to correct invalid insights based on predefined templates or previous similar insights.	Retry after applying the fallback correction.
Event Emission Failures	Retry event emissions up to 3 times with exponential backoff. If all retries fail, escalate to human intervention.	Retry event emission with exponential backoff and logging.

🧠 Correction Workflow¶

Validation Failure:
If the agent detects any validation failures (e.g., missing data, incorrect format, incomplete personas), it initiates an auto-correction process.
Auto-Correction Attempt:
The agent automatically attempts to correct the issue by filling in missing data, reformatting the output, or regenerating missing information based on predefined templates.
Retry Validation:
After applying the corrections, the agent retries the validation process to check if the error has been resolved.
Second Correction Attempt:
If the first correction attempt fails, a second correction is triggered, potentially applying a fallback strategy or using historical insights.
Escalation to Human:
After two failed correction attempts, the agent escalates the issue to human intervention, providing full context, logs, and insights into the failure.

🧩 Retry and Correction Flow Diagram¶

flowchart TD
    ValidationFailure --> AutoCorrectionAttempt
    AutoCorrectionAttempt --> RetryValidation
    RetryValidation -->|Pass| ArtifactStorage
    RetryValidation -->|Fail| SecondCorrectionAttempt
    SecondCorrectionAttempt --> RetryValidation2
    RetryValidation2 -->|Pass| ArtifactStorage
    RetryValidation2 -->|Fail| HumanIntervention

Hold "Alt" / "Option" to enable pan & zoom

✅ Two full correction cycles are allowed before human escalation.

📚 Example Correction Mechanisms¶

Missing Data¶

Trigger: The persona does not include essential details like technology use.
Correction: Automatically fill the missing technology use based on typical user behavior from similar personas.
Validation: Retry the persona validation after auto-filling the missing information.

Example:

# Persona: Patient

## Technology Use
- **Device**: Smartphone (iPhone)
- **Apps**: Google Calendar, healthcare apps, social media

Format Error¶

Trigger: The persona description doesn't adhere to the required format.
Correction: Reformat the persona to match the required structure (e.g., "As a [persona], I want [goal]...").
Validation: Retry after reformatting.

Example:

# Persona: Patient

## As a patient, I want to book appointments online easily so that I can avoid calling the clinic.

Incomplete Persona Data¶

Trigger: Missing persona details like motivations or frustrations.
Correction: Generate missing details based on patterns from previous personas.
Validation: Retry after applying the corrections.

Example:

## Motivations
- **Convenience**: Wants to book appointments quickly and easily.

## Frustrations
- **Confusing Scheduling**: Struggles to navigate through complicated appointment booking systems.

Invalid Insights¶

Trigger: The generated insight does not align with user research data (e.g., incorrect behavior pattern).
Correction: Regenerate insights based on historical data or fallback templates.
Validation: Retry after applying the corrected insight.

Example: - Invalid Insight: "Users prefer email over SMS for appointment reminders." - Corrected Insight: "Users prefer SMS reminders over email due to faster delivery."

Event Emission Failure¶

Trigger: The event (UserResearchInsightsReady) fails to be emitted due to a system error or conflict.
Correction: Retry emitting the event with exponential backoff. If it fails multiple times, escalate the issue to human intervention.
Validation: Retry the event emission after applying the correction.

Example:

{
  "event_type": "UserResearchInsightsReady",
  "trace_id": "user-research-2025-04-27-001",
  "artifact_uri": "https://storage.connectsoft.ai/research/personas/patient-persona-2025-04-27-001.json",
  "timestamp": "2025-04-28T06:00:00Z"
}

📈 Observability for Retry and Correction¶

Metric Name	Purpose
`user_researcher_agent_validation_failures_total`	Total number of validation failures encountered.
`user_researcher_agent_corrections_attempted_total`	Total number of corrections attempted by the agent.
`user_researcher_agent_failed_retries_total`	Total number of retries that failed before escalation.
`user_researcher_agent_successful_retries_total`	Total number of successful retries after auto-correction.
`user_researcher_agent_escalations_total`	Total number of escalations triggered to human intervention.

✅ All correction and retry actions are fully observable and traceable to ensure transparency and accountability.

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Retry and Correction Alignment
Resilient Execution	Retry and correction mechanisms ensure the User Researcher Agent continues autonomously even in the case of initial errors.
Observability-First	Every retry, correction, and failure is tracked and logged for monitoring and analysis.
Event-Driven Workflow	Event emissions (e.g., `UserResearchInsightsReady`) trigger downstream actions, ensuring smooth handoffs to other agents.
Cloud-Native Flexibility	Auto-correction and retries ensure the agent is scalable and can handle large amounts of user research data.
Modular and Scalable	Error correction and retry logic can be modified or extended for different types of tasks without impacting overall system performance.

🛠️ Core Skills of the User Researcher Agent¶

The User Researcher Agent is powered by a modular skill system that orchestrates different tasks within the user research lifecycle.
Each skill is designed to focus on a specific sub-task, ensuring that the agent can gather data, synthesize insights, and create actionable recommendations effectively.

The skills range from user interviewing to persona creation, journey mapping, and usability testing.
These skills are chained dynamically by the Semantic Kernel, ensuring that the agent produces structured, validated, and actionable outputs.

📋 Core Skill Categories¶

Skill Category	Description	Example Skills
User Interviewing	Conduct in-depth user interviews to extract insights into user goals, pain points, and motivations.	"Prepare interview questions", "Conduct user interviews", "Synthesize findings"
Persona Creation	Build detailed user personas from qualitative data to represent target users.	"Create personas based on interview findings", "Expand personas with behaviors and needs"
Journey Mapping	Map the user’s end-to-end interaction with the product, highlighting key touchpoints and pain points.	"Map user journey from initial interaction to post-use", "Identify opportunities for design improvements"
Usability Testing	Conduct tests to evaluate the usability of a product by real users and identify pain points.	"Design usability tests", "Conduct moderated usability sessions", "Analyze results and provide recommendations"
Survey Design and Analysis	Design effective surveys to collect quantitative and qualitative user feedback.	"Create and distribute user surveys", "Analyze survey results to identify trends"
Data Synthesis	Analyze and synthesize qualitative and quantitative data to extract meaningful insights and patterns.	"Categorize interview data", "Analyze survey results", "Synthesize user feedback into actionable insights"
Competitive Analysis	Conduct research on competitors and similar products to gain insights into market trends and user needs.	"Perform SWOT analysis on competitor products", "Identify features users want based on competitor analysis"
Report Generation	Organize insights into comprehensive, structured reports for stakeholders.	"Generate usability test reports", "Create journey maps and present findings to stakeholders"
Ethical Research Standards	Ensure all research activities are ethical and compliant with industry standards (e.g., GDPR, HIPAA).	"Ensure data privacy in user interviews", "Comply with ethical research guidelines"

🧠 Skill Flow Diagram¶

flowchart TD
    InterviewSkill["1. User Interviewing"] --> PersonaCreationSkill["2. Persona Creation"]
    PersonaCreationSkill --> JourneyMappingSkill["3. Journey Mapping"]
    JourneyMappingSkill --> UsabilityTestingSkill["4. Usability Testing"]
    UsabilityTestingSkill --> SurveyDesignSkill["5. Survey Design & Analysis"]
    SurveyDesignSkill --> DataSynthesisSkill["6. Data Synthesis"]
    DataSynthesisSkill --> ReportGenerationSkill["7. Report Generation"]
    ReportGenerationSkill --> EventEmissionSkill["8. Event Emission"]
    EventEmissionSkill --> EventBus
    EventBus --> UXDesignerAgent
    EventBus --> ProductManagerAgent

Hold "Alt" / "Option" to enable pan & zoom

✅ Skills are orchestrated through the Semantic Kernel, enabling the User Researcher Agent to deliver consistent, quality insights across research tasks.

🧠 Detailed Skill Descriptions¶

1. User Interviewing Skill¶

Purpose: Conduct in-depth interviews with users to understand their needs, goals, frustrations, and behaviors.
Input: Research objectives, user demographic information, interview questions.
Output: Transcribed interview data, insights, and quotes.

Example: - Interview questions:
- "Tell me about a time when you had difficulty booking an appointment online." - "What are the biggest challenges you face when managing your healthcare appointments?"

2. Persona Creation Skill¶

Purpose: Create detailed personas that represent the key user types, including goals, pain points, and behaviors.
Input: Data from user interviews, surveys, and research findings.
Output: User persona documents, including user goals, frustrations, motivations, behaviors, and technology use.

Example:

# Persona: Patient (Primary User)

## Background
- **Age**: 30
- **Occupation**: Teacher
- **Tech-savviness**: Medium

## Goals
- **Quick and easy** appointment scheduling.
- **Timely reminders** for appointments.

## Frustrations
- **Booking process is cumbersome**.
- **No reminders for appointments**.

## Technology Use
- **Device**: Smartphone (iPhone)
- **Apps**: Google Calendar, healthcare apps.

3. Journey Mapping Skill¶

Purpose: Visualize the user’s experience as they interact with the product, identifying key touchpoints, emotions, and pain points.
Input: Persona data, user interaction data, research findings.
Output: User journey maps with identified opportunities for improvement.

Example:

flowchart TD
    User -->|Visit Website| AppointmentBooking
    AppointmentBooking -->|Select Available Slot| AppointmentSelection
    AppointmentSelection -->|Confirm Appointment| ConfirmationPage
    ConfirmationPage -->|Receive Confirmation| User

    %% Pain Points %%
    AppointmentBooking -->|Pain Point: Slow Website| Frustration
    ConfirmationPage -->|Pain Point: No Confirmation Email| Frustration

Hold "Alt" / "Option" to enable pan & zoom

4. Usability Testing Skill¶

Purpose: Conduct usability testing to observe how real users interact with the product, identifying any usability issues.
Input: Test scenarios, users, research objectives.
Output: Usability test reports with key findings and actionable recommendations.

Example: - Test Objective: Evaluate how easily users can complete the appointment booking process. - Test Result: "70% of users had difficulty finding the available time slots."

5. Survey Design & Analysis Skill¶

Purpose: Design and analyze user surveys to collect both quantitative and qualitative feedback.
Input: Survey questions, research objectives, target user demographic.
Output: Survey results, categorized insights.

Example: - Survey Question: "How satisfied are you with the current appointment booking system? (1-5 scale)" - Analysis Result: "40% of respondents rated the system as ⅗, citing slow performance as the main issue."

6. Data Synthesis Skill¶

Purpose: Synthesize qualitative and quantitative research data into actionable insights.
Input: Raw research data (interviews, surveys, usability tests).
Output: Categorized insights, user behavior patterns, findings.

Example: - Insight: "Users experience frustration with the multi-step process for appointment booking." - Pattern: "Users who prefer mobile apps report higher satisfaction with the booking process."

7. Report Generation Skill¶

Purpose: Organize insights and findings into comprehensive reports for stakeholders.
Input: Synthesized data, research findings, user insights.
Output: Research reports, personas, journey maps, usability findings.

Example: - Report: "In-depth usability testing results with key findings and recommendations for UI improvements."

8. Event Emission Skill¶

Purpose: Emit events when research insights are ready for downstream consumption by other agents.
Input: Finalized research outputs (personas, journey maps, usability reports).
Output: Event emissions, such as UserResearchInsightsReady, PersonasReady, JourneyMapsReady.

Example:

{
  "event_type": "UserResearchInsightsReady",
  "trace_id": "user-research-2025-04-27-001",
  "artifact_uri": "https://storage.connectsoft.ai/research/personas/patient-persona-2025-04-27-001.json",
  "timestamp": "2025-04-28T06:00:00Z"
}

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Skills Alignment
User-Centered Design	All skills are focused on gathering user insights, creating personas, and improving user experience.
Event-Driven Activation	Events such as `UserResearchInsightsReady` trigger downstream tasks in UX/UI design and product planning.
Modular and Scalable	Each research method (interviews, surveys, usability testing) is modular, reusable, and scalable.
Observability-First	All research activities are tracked, logged, and monitored for transparency and accountability.
Cloud-Native Integration	Research outputs are stored in cloud-native systems (Blob, SQL, Git), ensuring easy access and scalability.

🔗 Collaboration Interfaces¶

The User Researcher Agent must collaborate effectively with other agents (such as UX/UI Designers, Product Managers, and Product Owners) to ensure that user insights are integrated into the product development lifecycle. These collaborations ensure that user research is actionable, data-driven, and aligned with business goals.

📋 Primary Collaboration Interfaces¶

Interface Type	Purpose	Downstream Consumer
Event Emission	Notify downstream agents that research outputs are ready.	UX Designer, UI Designer, Product Manager, Product Owner, Developers
Artifact Storage	Store research outputs for access by other agents.	Research retrieval services, GitOps, DevOps pipelines
Semantic Memory Retrieval (Optional)	Retrieve past user research insights to enrich new research tasks.	Future research tasks, historical research reference
Research Reports & Insights	Provide human-readable research reports and insights to stakeholders.	Product Managers, Designers, Stakeholders
Collaboration on Persona Development	Collaborate with UX/UI Designers and Product Managers to align personas and journey maps with design and business goals.	UX/UI Design, Product Owners, Product Managers
Cross-Functional Insights Sharing	Share qualitative insights, user pain points, and recommendations with all involved teams.	Product Team, Design Team, Development Team

🧠 Example Collaboration Workflow¶

Task Initiation: The User Researcher Agent receives a task via event, such as a request to conduct user research for a new feature (e.g., "Research patient appointment scheduling experience").
Event Emission: Once the research findings are ready (e.g., user personas, journey maps, and usability testing reports), the agent emits events like UserResearchInsightsReady, PersonasReady, and JourneyMapsReady to notify downstream agents.
Research Insights Sharing: The agent shares research reports and insights with relevant stakeholders (e.g., UX Designers, Product Managers, and Product Owners) through event-driven mechanisms.
Persona and Journey Map Refinement: The User Researcher Agent works with UX/UI Designers and Product Managers to refine personas and journey maps based on user research. These deliverables are shared via events for further design and implementation.

🏗️ Collaboration Diagram¶

flowchart TD
    UserResearcherAgent -->|UserResearchInsightsReady| EventBus
    EventBus --> UXDesignerAgent
    EventBus --> ProductManagerAgent
    EventBus --> ProductOwnerAgent
    EventBus --> UIPrototyperAgent
    UXDesignerAgent --> PersonaRefinement
    ProductManagerAgent --> FeaturePrioritization
    UIPrototyperAgent --> DesignPrototyping
    ProductOwnerAgent --> SprintPlanning

Hold "Alt" / "Option" to enable pan & zoom

✅ User Researcher Agent emits events to trigger downstream actions, enabling smooth collaboration across product, design, and development teams.

📈 Observability Hooks¶

Observability is crucial for tracking the performance, progress, and outcomes of the User Researcher Agent's tasks.
The agent must provide real-time visibility into the research process, ensuring that every step is logged, monitored, and traceable.

📋 Key Observability Metrics¶

Metric Name	Purpose
user_researcher_agent_validation_failures_total	Tracks the total number of validation failures encountered during research output creation (e.g., missing data, format errors).
user_researcher_agent_corrections_attempted_total	Tracks the total number of corrections the agent has attempted to fix validation issues.
user_researcher_agent_event_emissions_total	Tracks the number of events emitted to signal that research outputs are ready for downstream consumption.
user_researcher_agent_successful_research_reports_total	Tracks the number of successful research reports and insights generated (personas, usability tests, etc.).
user_researcher_agent_usability_tests_conducted_total	Tracks the number of usability tests conducted as part of user research.
user_researcher_agent_personas_created_total	Tracks the number of personas created by the agent.
user_researcher_agent_journey_maps_generated_total	Tracks the number of journey maps successfully generated.

🧠 Example Observability Logs¶

Log Entry for Persona Creation:

{
  "timestamp": "2025-04-28T07:00:00Z",
  "level": "Info",
  "message": "Persona 'Patient' created successfully",
  "agent": "UserResearcherAgent",
  "trace_id": "user-research-2025-04-27-001",
  "artifact_id": "persona-patient-2025-04-27-001",
  "status": "Success"
}

Trace Span for Journey Mapping:

{
  "trace_id": "user-research-2025-04-27-001",
  "span_id": "span-003",
  "name": "Journey Mapping",
  "start_time": "2025-04-28T07:00:00Z",
  "end_time": "2025-04-28T07:15:00Z",
  "status": "Success"
}

📈 Event Emission and Telemetry¶

The User Researcher Agent emits events that signal the readiness of research outputs. These events are tracked and logged for real-time visibility. For example:

Event: UserResearchInsightsReady
Metric: user_researcher_agent_event_emissions_total

Example Event Payload:

{
  "event_type": "UserResearchInsightsReady",
  "trace_id": "user-research-2025-04-27-001",
  "artifact_uri": "https://storage.connectsoft.ai/research/personas/patient-persona-2025-04-27-001.json",
  "timestamp": "2025-04-28T06:00:00Z"
}

🧩 ConnectSoft Platform Principles Alignment¶

Principle	Collaboration & Observability Alignment
Event-Driven Workflow	Outputs like `UserResearchInsightsReady` trigger downstream actions, ensuring smooth handoff to UX/UI Designers and Product Managers.
Observability-First	The agent emits real-time metrics, logs, and event traces to monitor performance, progress, and outcomes.
Modular Outputs	Research outputs (personas, reports, journey maps) are modular and reusable across teams.
Cloud-Native Integration	Outputs are stored in cloud-native systems, ensuring scalability and accessibility.

🛠️ Human Intervention Hooks¶

Although the User Researcher Agent is designed to operate autonomously, there are scenarios where human intervention is required. These hooks ensure that when the agent encounters critical issues, it can escalate to human experts for resolution.

This enhances the resilience and trustworthiness of the system by ensuring that the agent does not continue processing invalid or incomplete outputs.

📋 When Human Intervention is Triggered¶

Situation	Reason for Escalation	Example
Persistent Validation Failure	If the agent is unable to resolve validation issues after 2 correction cycles.	Missing required fields in personas or journey maps even after retries.
Semantic Drift	If insights deviate from the user research goals or strategic objectives.	Generated persona does not align with user feedback or business goals.
Critical Missing Information	Essential research data is incomplete or corrupted.	Missing essential user pain points in a persona due to insufficient data.
Event Emission Failure	If the agent fails to emit events (e.g., `UserResearchInsightsReady`) after retries.	Failure to emit event signaling that personas or research reports are ready for downstream consumption.
Stakeholder Request for Changes	If a stakeholder requests major adjustments to the research, requiring manual intervention.	Request from Product Manager to revise personas based on new business priorities.

🧠 Human Escalation Workflow¶

Initial Validation and Correction:
- The agent performs self-validation and attempts auto-correction.
- If the issue persists, a second correction attempt is made using fallback strategies.
Escalation to Human:
- After two failed correction attempts, the escalation mechanism is triggered.
- The agent provides full context (e.g., logs, task details) for human review.
Human Review:
- A business analyst, UX designer, or product manager reviews the issue.
- The issue is manually addressed (e.g., correcting personas, adjusting research reports).
Reprocessing:
- Once the issue is resolved by human intervention, the agent reprocesses the task and resumes its workflow.

📉 Escalation Metrics¶

Metric Name	Purpose
user_researcher_agent_human_escalations_total	Tracks the total number of escalations that have been triggered to human intervention.
user_researcher_agent_failed_retries_total	Tracks the number of retries that have failed before the issue was escalated to human intervention.
user_researcher_agent_successful_retries_total	Tracks the number of successful retries after automatic correction.
user_researcher_agent_escalation_resolution_time	Tracks the time taken to resolve escalated issues from initial failure to human intervention.

🧩 Example of Human Intervention Scenario¶

Persona Validation Issue:
- Problem: The persona generated by the agent is missing critical information about user pain points.
- Auto-Correction: The agent attempts to regenerate the missing persona details using fallback templates but fails.
- Escalation: The agent triggers human escalation, providing all logs and failed attempts.
- Human Resolution: A UX designer or product manager manually adjusts the persona, ensuring that the user’s challenges are properly captured.
- Reprocessing: After human intervention, the agent reprocesses the task, completing the persona correctly, and emits the PersonasReady event.

🎯 Final Conclusion: User Researcher Agent's Role in the ConnectSoft AI Software Factory¶

The User Researcher Agent plays an essential role in ensuring that all product and design decisions are rooted in real user feedback.
By transforming user data into actionable insights, personas, and journey maps, the agent bridges the gap between user needs and business goals.

🏛️ User Researcher Agent Positioning in Factory Lifecycle¶

flowchart TD
    VisionArchitectAgent -->|VisionDocumentCreated| UserResearcherAgent
    UserResearcherAgent -->|UserInsightsReady| UXDesignerAgent
    UXDesignerAgent -->|DesignPrototypesReady| UIPrototyperAgent
    UIPrototyperAgent -->|UIReady| EventBus
    EventBus --> ProductOwnerAgent
    ProductOwnerAgent -->|BacklogReady| EventBus
    EventBus --> UXDesignOutput
    EventBus --> ProductManagerOutput

Hold "Alt" / "Option" to enable pan & zoom

✅ User Researcher Agent is positioned at the beginning of the product design process, ensuring that all design decisions are user-centered and data-driven.

🧩 Final Summary of the User Researcher Agent's Key Functions:¶

User-Centered Research: Focuses on gathering deep insights into user behaviors, needs, pain points, and goals.
Actionable Outputs: Generates personas, journey maps, and usability reports that guide UX/UI Designers and Product Managers.
Collaboration: Works closely with UX Designers, Product Managers, and UI Designers to ensure research findings drive the design process.
Event-Driven: Emits events (e.g., UserResearchInsightsReady, PersonasReady) that trigger downstream processes.
Observability: Provides real-time metrics, logs, and traces to ensure full transparency and accountability.
Resilient Execution: Automatically corrects issues and retries validation, ensuring minimal human intervention.

🧠 User Researcher Agent¶

🎯 Purpose¶

🏛️ Core Mission¶

🎯 High-Level Objectives¶

🏛️ Strategic Role in ConnectSoft AI Software Factory¶

🎯 Key Deliverables¶

🧠 Long-Term Vision¶

🧩 ConnectSoft Platform Principles Alignment¶

📋 Responsibilities¶

🎯 Key Responsibilities¶

🧠 Example Deliverables¶

🎯 Collaboration with Other Agents¶

🧩 Example: User Research Process¶

Step 1: Research Planning¶

Step 2: Conducting User Research¶

Step 3: Data Synthesis¶

Step 4: Reporting and Sharing Findings¶

🧩 ConnectSoft Platform Principles Alignment¶

📥 Inputs¶

📋 Primary Inputs Consumed by the User Researcher Agent¶

🧠 Input Flow Overview¶

📚 Example Input Payloads¶

📄 Vision Document¶

📄 Stakeholder Context (Business Constraints)¶

📄 User Data (From Previous Research)¶

🧩 Knowledge Base and Semantic Memory¶

📋 Example Memory Retrieval¶

🧩 ConnectSoft Platform Principles Alignment¶

📤 Outputs¶

📋 Primary Outputs Produced¶

🏗️ Visual: Output Artifact Generation Flow¶

📚 Example Output Artifacts¶

📋 User Persona Example¶

📋 Journey Map Example (Mermaid Diagram)¶

📋 Usability Report Example¶

📋 Event Emission Example¶

📈 Observability Metrics for Output Generation¶

🧩 ConnectSoft Platform Principles Alignment¶

📚 Knowledge Base Overview¶

📋 Core Knowledge Areas¶

🧠 Knowledge Base Structure¶

🧩 User Research Frameworks¶

🧩 User Interview Methodologies¶

🧩 Usability Testing Methods¶

🧩 Persona Development¶

🧩 Journey Mapping¶

🧩 Semantic Memory (Optional)¶

📚 Example Knowledge Base Asset: Research Frameworks Template¶

🧩 ConnectSoft Platform Principles Alignment¶

🔄 Process Flow Overview¶

📋 User Researcher Agent Process Phases¶

🧩 Detailed Process Flow¶

📚 Example Workflow¶

Phase 1: Research Planning¶

Phase 2: Data Collection¶

Phase 3: Data Synthesis¶

Phase 4: Insight Generation¶

Phase 5: Report Creation¶

Phase 6: Insight Sharing¶

Phase 7: Event Emission¶

🧩 ConnectSoft Platform Principles Alignment¶

🛠️ Technologies Overview¶

📋 Core Technology Stack¶

🏗️ Component Diagram for User Researcher Agent Technologies¶

📚 Example Tool Usage¶

Survey and Interview Tools¶

Event Bus Integration¶

OpenAI Models¶

🧩 Observability Tools¶

🧩 ConnectSoft Platform Principles Alignment¶

📝 System Prompt (Initialization Instruction)¶

📋 Full System Prompt Text¶

🎯 Purpose of the System Prompt¶

🧠 Key Output Expectations Based on System Prompt¶

🧩 Example Behavioral Directives¶

🧩 ConnectSoft Platform Principles Alignment¶

📥 Input Prompt Template¶

📋 Structure of the Input Prompt Template¶

🧠 Example Structured Input Prompt¶

🧩 Process of Using the Input Prompt Template¶