Domain Entities

The Research Module operates with three core entities that work together to provide a structured research experience.

Overview

• Template - Reusable blueprint defining research structure and AI behavior
• Research - Active project instance containing data and context
• Entry - Individual artifact or finding within a research

---

Template

Definition: A reusable blueprint that defines research structure, workflow phases, entry types, and AI behavior for a specific domain or methodology.

Purpose: Templates provide consistency, guide users through proven methodologies, and configure AI behavior for domain-specific consultation.

Template Structure

Templates are stored as YAML files in the .templates directory:

key: feature_discovery              # Unique identifier
name: Product Feature Discovery     # Human-readable name
description: Systematic feature discovery through customer needs analysis
tags:
  - product-management
  - discovery

categories: # Workflow phases
  - name: audience_research
    display_name: Target Audience Research
    entry_types:
      - persona
      - segment_analysis

  - name: needs_analysis
    display_name: Needs & Problems Analysis
    entry_types:
      - pain_point
      - job_to_be_done

  - name: feature_ideation
    display_name: Feature Ideation
    entry_types:
      - feature_concept
      - user_story

entry_types: # Artifact definitions
  persona:
    display_name: User Persona
    content_type: text/markdown
    default_status: draft
    statuses:
      - display_name: Draft
        value: draft
      - display_name: Validated
        value: validated
      - display_name: Published
        value: published

  pain_point:
    display_name: Pain Point
    content_type: text/markdown
    default_status: draft
    statuses:
      - display_name: Draft
        value: draft
      - display_name: Validated
        value: validated
      - display_name: Prioritized
        value: prioritized
      - display_name: Addressed
        value: addressed

  feature_concept:
    display_name: Feature Concept
    content_type: text/markdown
    default_status: idea
    statuses:
      - display_name: Idea
        value: idea
      - display_name: Evaluated
        value: evaluated
      - display_name: Approved
        value: approved
      - display_name: In Development
        value: in_development

prompt: |                           # AI system instructions
  You are a strategic product manager specializing in feature discovery.

  Your role is to guide users through systematic feature discovery by:
  1. Understanding their target audience deeply
  2. Uncovering real user problems and jobs-to-be-done
  3. Generating feature concepts that address genuine needs

  Conduct discovery sessions using strategic questioning:
  - Ask one thoughtful question at a time
  - Encourage detailed, specific answers
  - Use voice dictation for rich responses
  - Synthesize answers into structured entries

  For each category, follow this approach:

  ## Audience Research
  - Who are the primary users?
  - What are their technical backgrounds?
  - What tools do they currently use?
  - What frustrates them about existing solutions?

  ## Needs Analysis
  - What specific problems do they face?
  - What jobs are they trying to get done?
  - What's the impact of these problems?
  - How do they work around limitations today?

  ## Feature Ideation
  - What features would solve these problems?
  - How would features integrate with workflows?
  - What makes this better than alternatives?
  - What's the minimal viable version?

Key Components

Categories

Workflow phases that structure the research progression:

• Purpose: Organize research into logical stages
• Structure: Sequential phases like Research → Analysis → Planning
• Entry Types: Each category specifies which entry types are allowed
• Example: audience_research → needs_analysis → feature_ideation

Entry Types

Specific artifact types that can be created:

• Purpose: Define what kind of content can be captured
• Display Name: Human-readable name shown to users
• Content Type: MIME type (typically text/markdown)
• Default Status: Initial status for new entries
• Statuses: Lifecycle stages specific to this entry type
• Examples: User Persona, Pain Point, Feature Concept, Technical Decision

Statuses

Lifecycle stages for each entry type:

• Purpose: Track entry maturity and workflow progress
• Type-Specific: Each entry type has its own status progression
• Examples:
  • Pain Point: Draft → Validated → Prioritized → Addressed
  • Feature Concept: Idea → Evaluated → Approved → In Development
  • Persona: Draft → Validated → Published

Prompt

System instructions that define AI behavior:

• Purpose: Configure AI consultation methodology
• Content: Role definition, workflow guidance, question strategies
• Scope: Applies to all research sessions using this template
• Best Practice: Include domain frameworks and specific methodologies

Template File Location

.templates/
├── feature_discovery.yaml
├── market_research.yaml
├── architecture_design.yaml
└── strategic_planning.yaml

Creating Templates

Templates can be created:

1. Manually: Write YAML file following the structure above
2. With Template Generator: Use dedicated Claude project with template generation instructions
3. From Examples: Copy and modify existing templates

See: Generate Research Template for detailed instructions.

---

Research

Definition: A project instance created from a template that contains actual research data, entries, and context.

Purpose: Research represents an active investigation or analysis project with its own context, memory, and collection of findings.

Research Structure

Research is stored as research.yaml file in the research directory:

id: research_abc123
name: CTX Feature Discovery Q1 2025
description: Identifying next major features for CTX context generator
template: feature_discovery
status: active
tags:
  - ctx
  - product
  - q1-2025
  - developer-tools
entry_dirs:
  - audience_research
  - needs_analysis
  - feature_ideation
memory:
  - Conduct sessions in Russian for natural conversation flow
  - Focus on PHP developer audience, specifically Laravel users
  - Target users already work with AI tools (Claude, Cursor, GitHub Copilot)
  - Priority on developer productivity and context management features
  - Document findings in English for team accessibility

Key Attributes

Template

• Purpose: Links research to its methodology blueprint
• Value: Template key (e.g., feature_discovery)
• Immutable: Cannot be changed after research creation
• Effect: Determines available categories, entry types, and AI behavior

Memory Blocks

Critical for context restoration. Project-specific AI instructions that supplement the template prompt:

Language Preferences:

- Conduct discovery sessions in Russian for natural conversation
- Document all findings in English for team accessibility

Domain Constraints:

- Focus on PHP developer audience, especially those using Laravel
- Consider integration with existing IDE workflows
- Target users already using AI coding assistants

Methodology Preferences:

- Prioritize strategic questioning over rapid entry creation
- Aim for depth over breadth in initial discovery
- Use voice dictation for detailed responses

Context Specifics:

- This is for CTX context generator tool
- Product serves developers who work with large codebases
- Key differentiator is intelligent context selection

Entry Directories

• Purpose: Map to template categories, organize findings
• Structure: One directory per category
• Creation: Automatically created when research is initialized
• Content: Contains entry markdown files

Status

Tracks research lifecycle:

• draft - Initial creation, still defining scope
• active - Actively conducting research
• published - Research completed, findings available
• archived - Historical reference, no longer active

Tags

Enable filtering and organization:

• Purpose: Cross-cutting categorization
• Usage: Filter research lists, group related projects
• Examples: q1-2025, high-priority, customer-facing, technical

Research File Location

.researches/
└── research_abc123_ctx-feature-discovery/
    ├── research.yaml                 # Research metadata
    ├── audience_research/            # Category directory
    │   ├── entry_001.md
    │   ├── entry_002.md
    │   └── .gitkeep
    ├── needs_analysis/
    │   ├── entry_003.md
    │   ├── entry_004.md
    │   └── .gitkeep
    └── feature_ideation/
        ├── entry_005.md
        └── .gitkeep

Creating Research

Research is created using MCP tools:

Tool: research-create
Parameters:
  - templateId: feature_discovery
  - title: CTX Feature Discovery Q1 2025
  - description: Identifying next major features
  - tags: [ctx, product, q1-2025]
  - memory: [<memory entries>]

See: Create Research for detailed instructions.

---

Entry

Definition: An individual artifact, document, or finding captured during research. Entries are categorized, typed, and contain both structured metadata and content.

Purpose: Entries are the fundamental units of research output - they capture specific insights, analyses, or work products in an organized, retrievable format.

Entry Structure

Entries are stored as Markdown files with YAML frontmatter:

---
entry_id: entry_xyz789
title: Developer Pain - Manual Context Gathering
description: Analysis of time wasted on manual context preparation for AI tools
entry_type: pain_point
category: needs_analysis
status: validated
created_at: 2025-01-15T10:30:00Z
updated_at: 2025-01-15T14:20:00Z
tags:
  - context-management
  - productivity
  - high-priority
---

# Developer Pain Point: Manual Context Gathering

## Problem Statement

Developers spend 15+ minutes per AI session manually gathering files, copying code snippets, and explaining project
context to tools like Claude or Cursor. This creates significant friction and reduces the value of AI assistance.

## Impact Analysis

- **Time Lost**: 15-30 minutes per session × 5-10 sessions per day = 2-5 hours daily
- **Context Quality**: Often incomplete due to time constraints, leading to suboptimal AI suggestions
- **Flow Disruption**: Breaks concentration and momentum during development
- **Inconsistency**: Different context each session leads to inconsistent AI responses

## Root Causes

1. No persistent memory of project structure
2. Manual file selection process
3. No automatic relevance detection
4. Copy-paste workflow interrupts coding flow

## User Quotes

> "Every time I want Claude's help, I spend more time copy-pasting files than actually getting answers. It's frustrating
because I know the AI could help, but the setup overhead makes me think twice." - Senior PHP Developer, Interview #7

> "I often skip using AI for quick questions because gathering context takes longer than just solving the problem
myself." - Laravel Developer, Survey Response #23

## Potential Solutions

1. **Automated Context Collection**: Tool that automatically identifies and includes relevant files based on:
    - Current working file
    - Recent git changes
    - Import/require statements
    - Project structure analysis

2. **Project-Aware Context Loading**: Persistent project understanding that remembers:
    - Architecture patterns
    - Key files and their purposes
    - Common workflows
    - Team conventions

3. **Intelligent Context Selection**: Smart algorithms that:
    - Prioritize recently modified files
    - Include dependencies automatically
    - Respect context size limits
    - Learn from user selections

## Priority Assessment

- **Impact**: High (affects daily workflow)
- **Frequency**: Very High (multiple times per day)
- **User Segment**: All developers using AI tools
- **Competitive Advantage**: Significant differentiator

## Next Steps

1. Validate with larger user sample
2. Prototype automatic context detection
3. Test with real Laravel projects
4. Measure time savings in pilot study

Key Attributes

Entry ID

• Format: Unique identifier (e.g., entry_xyz789)
• Generation: Automatic on creation
• Purpose: Reference entries across research

Title

• Source: User-provided or auto-generated from content first line
• Purpose: Quick identification of entry content
• Length: Recommended 50-100 characters
• Example: "Developer Pain: Manual Context Gathering"

Description

• Purpose: Short summary for LLM understanding
• Length: Maximum 200 characters
• Usage: Quick scanning without reading full content
• Generation: User-provided or auto-generated from content
• Example: "Analysis of time wasted on manual context preparation for AI tools"

Entry Type

• Purpose: Defines what kind of artifact this is
• Validation: Must match template's defined entry types
• Examples: persona, pain_point, feature_concept, technical_decision
• Effect: Determines available statuses

Category

• Purpose: Places entry within research workflow phase
• Validation: Must match template categories
• Constraint: Entry type must be allowed in this category
• Examples: audience_research, needs_analysis, feature_ideation

Status

• Purpose: Tracks entry lifecycle within its type
• Values: Type-specific (e.g., Draft → Validated → Prioritized)
• Validation: Must be valid status for the entry type
• Workflow: Progresses as entry is refined and validated

Tags

• Purpose: Cross-cutting organization beyond category structure
• Usage: Filter entries, group related findings
• Examples: high-priority, quick-win, technical-debt, customer-request
• Flexibility: Can be added or removed at any time

Content

• Format: Markdown
• Location: Below YAML frontmatter
• Structure: Freeform, but follows entry type conventions
• Best Practice: Use clear sections, quotes, data, and actionable insights

Entry File Location

.researches/research_abc123_ctx-feature-discovery/
└── needs_analysis/
    └── entry_xyz789.md

File naming: entry_<entry_id>.md

Creating Entries

Entries are created using MCP tools during research sessions:

Tool: research-entry-create
Parameters:
  - researchId: research_abc123
  - category: needs_analysis
  - entryType: pain_point
  - content: <markdown content>
  - title: <optional>
  - description: <optional>
  - tags: [<optional>]

See: Conduct Research for detailed instructions.

Entry Generation Pattern

1. AI asks strategic questions during session
2. User provides detailed answers (preferably via voice dictation)
3. AI synthesizes answers into structured entries
4. Entries are automatically saved as Markdown files with frontmatter
5. Entries become reference material for future sessions

Entry Lifecycle

Create (draft) 
    ↓
Work In Progress
    ↓
Review & Validate
    ↓
Complete
    ↓
Published/Archived

Specific lifecycle depends on entry type status definitions in template.

---

Relationships

Template → Research

• One to Many: One template can create multiple research projects
• Immutable: Research template cannot be changed after creation
• Inheritance: Research inherits categories, entry types, and AI behavior from template

Research → Entries

• One to Many: One research contains multiple entries
• Organization: Entries organized into categories (directories)
• Validation: Entry types must match template definitions
• Context: Entries share research memory and context

Template → Entry Types

• Definition: Template defines available entry types
• Constraints: Entry types specify allowed statuses
• Validation: Entries must use defined types and statuses

Category → Entry Types

• Allowlist: Categories specify which entry types are allowed
• Validation: System enforces category-type compatibility
• Organization: Logical grouping of related entry types

---

Next Steps

• Getting Started Guide - Step-by-step instructions to create and use research
• MCP Integration - Technical details and tool reference
• Best Practices - Recommended patterns and workflows