Research: File-Based researches management for CTX

[butschster]

Research bridges the gap between traditional project management tools and AI-assisted development workflows.

Unlike database-driven project management systems, the Research system stores everything as plain text files that are:

• Version controllable with Git
• Human readable without special tools
• AI friendly for Claude integration
• Portable across different environments
• Searchable with standard text tools

Core Purpose

The Research system solves the friction between structured project management and flexible, AI-assisted workflows by providing:

1. Template-Driven Organization: Define research structures once, reuse across teams
2. Contextual AI Integration: Claude can directly read, create, and modify research data
3. Distributed Collaboration: No central database - everything lives with your code
4. Structured Flexibility: Organize work without rigid tool constraints

How It Works

Template System

Templates define the structure of your researches - what categories of work exist, what types of entries you track, and what statuses are available.

Example Template (feature_discovery.yaml):

key: feature_discovery
name: Product Feature Discovery
description: Systematic feature discovery through customer needs analysis

categories:
  - name: audience_research
    display_name: Audience Research
    entry_types: ["target_segment", "persona_profile"]

entry_types:
  target_segment:
    display_name: Target Segment
    default_status: identifying
    statuses:
      - value: identifying
        display_name: Identifying
        color: yellow
      - value: identified
        display_name: Identified  
        color: green

Research Structure

Researches are instances of templates with their own entries organized in directories:

.researches/
├── customer-research/
│   ├── research.yaml              # Research configuration
│   ├── audience_research/         # Category directory
│   │   ├── enterprise-saas.md    # Individual entries
│   │   └── small-business.md
│   └── needs_analysis/
│       └── jobs-to-be-done.md

Entry Format

Each entry is a Markdown file with YAML frontmatter:

---
entry_id: "entry_123"
title: "Enterprise SaaS Segment"
entry_type: "target_segment"
category: "audience_research"
status: "identified"
created_at: "2025-01-20T10:30:00Z"
tags: ["enterprise", "saas", "b2b"]
---

# Enterprise SaaS Target Segment

## Key Characteristics
- Company size: 1000+ employees
- Budget: $100K+ annual software spend
- Decision process: Committee-based with 6-month cycles

## Pain Points
- Integration complexity with existing systems
- Security and compliance requirements
- Long procurement cycles

Usage Examples

For Product Teams

Scenario: Product team doing customer research for Q1 features

# Claude creates a new research
> Create a customer research using the feature_discovery template

# Claude adds research entries
> Add a target segment entry for "Enterprise SaaS" in audience research

# Team collaborates via Git
git add .researches/customer-research/
git commit -m "Add enterprise SaaS research findings"

# Claude generates insights
> Analyze all target segments and suggest feature priorities

For Development Teams

Scenario: Technical discovery for architecture decisions

# Template: technical_discovery.yaml
categories:
  - name: architecture_analysis
    entry_types: ["system_design", "performance_study"]
  - name: implementation_options  
    entry_types: ["proof_of_concept", "trade_off_analysis"]

# Claude tracks technical decisions
> Create a new architecture analysis entry for "Database scaling options"
> Update the Redis POC status to "complete" with performance results

For Consulting Teams

Scenario: Client engagement with multiple workstreams

# .researches/client-engagement/strategy/market-analysis.md
---
entry_type: "market_analysis"
status: "in_progress"
client: "TechCorp Inc"
deadline: "2025-02-15"
---

# Market Positioning Analysis

## Competitive Landscape
Current analysis of TechCorp's position...

For Research Teams

Scenario: Academic or UX research project

# Claude organizes research data
> Create entries for interview findings from our user research sessions
> Generate a summary document from all usability testing entries
> What themes emerge from our research tagged with "mobile_users"?

Integration with CTX

MCP Tools for Claude

The Research system provides Claude with comprehensive research management capabilities:

AI-Powered Workflows

# Claude can work with research data naturally
> What are our highest priority customer segments based on the research?
> Create a feature roadmap based on completed needs analysis entries
> Generate a client presentation from our strategy entries

Benefits

For Teams

• Shared Structure: Templates ensure consistent organization across researches
• Version Control: Full history of research evolution with Git
• No Vendor Lock-in: Plain text files work with any tool
• Offline Capable: No network dependency for research access

for AI Integration

• Rich Context: Structured metadata enables intelligent filtering and analysis
• Natural Language: Claude can read and write research data conversationally
• Template Awareness: AI understands research structure and constraints
• Real-time Updates: Changes are immediately available to AI tools

For Organizations

• Process Standardization: Templates encode institutional knowledge
• Knowledge Preservation: Research data lives with code, not in isolated tools
• Tool Independence: Switch between editors, IDEs, and AI assistants seamlessly
• Audit Trail: Complete history of decisions and changes

[codecov]

Codecov Report

❌ Patch coverage is 18.55346% with 2072 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/Research/Service/EntryService.php	0.00%	244 Missing ⚠️
...Research/Storage/FileStorage/FileStorageDriver.php	0.00%	188 Missing ⚠️
...search/Storage/FileStorage/FileEntryRepository.php	0.00%	158 Missing ⚠️
...rch/Storage/FileStorage/FileResearchRepository.php	0.00%	99 Missing ⚠️
...rch/Storage/FileStorage/FileTemplateRepository.php	0.00%	99 Missing ⚠️
src/Research/Console/ResearchInfoCommand.php	0.00%	95 Missing ⚠️
src/Research/Service/TemplateService.php	0.00%	84 Missing ⚠️
src/Research/MCP/Tools/UpdateEntryToolAction.php	0.00%	77 Missing ⚠️
src/Research/MCP/Tools/ListEntriesToolAction.php	0.00%	68 Missing ⚠️
src/Research/MCP/DTO/EntryUpdateRequest.php	0.00%	60 Missing ⚠️
... and 52 more

📢 Thoughts on this report? Let us know!