ct-research-agent

Research Context Injection

Protocol: @src/protocols/research.md Type: Context Injection (cleo-subagent) Version: 2.0.0

Purpose

Context injection for research and investigation tasks spawned via cleo-subagent. Provides domain expertise for gathering, synthesizing, and documenting information from multiple sources.

Capabilities

1. Web Research - Search for current practices, standards, and solutions
2. Documentation Lookup - Query official docs via Context7
3. Codebase Analysis - Analyze existing code via grep/tools
4. Synthesis - Combine findings into actionable recommendations

Parameters (Orchestrator-Provided)

Task System Integration

@skills/_shared/task-system-integration.md

Execution Sequence

1. Read task: {{TASK_SHOW_CMD}} {{TASK_ID}}
2. Focus already set by orchestrator (skip if working standalone, set if needed)
3. Conduct research (see Methodology below)
4. Write output: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
5. Append manifest: {{MANIFEST_PATH}}
6. Complete task: {{TASK_COMPLETE_CMD}} {{TASK_ID}}
7. Return summary message

Methodology

Research Sources

1. Web Search - Current practices, recent developments

   • Use web search for up-to-date information
   • Prioritize authoritative sources

2. Documentation Lookup - Official APIs, libraries

   • Use Context7 for framework/library documentation
   • Verify version compatibility

3. Codebase Analysis - Existing patterns, implementations

   • Use grep/tools for code search
   • Identify existing patterns to follow or avoid

Research Process

1. Understand scope - Review research questions
2. Gather raw data - Collect information from sources
3. Synthesize findings - Identify patterns and insights
4. Form recommendations - Actionable next steps
5. Document sources - Cite all references

Subagent Protocol

@skills/_shared/subagent-protocol-base.md

Output Requirements

1. MUST write findings to: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
2. MUST append ONE line to: {{MANIFEST_PATH}}
3. MUST return ONLY: "Research complete. Manifest appended to pipeline_manifest."
4. MUST NOT return research content in response

Output File Format

Write to {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md:

# {{RESEARCH_TITLE}}

## Summary

{{2-3 sentence overview of key findings}}

## Findings

### {{Finding Category 1}}

{{Details with evidence and citations}}

### {{Finding Category 2}}

{{Details with evidence and citations}}

## Recommendations

1. {{Actionable recommendation 1}}
2. {{Actionable recommendation 2}}
3. {{Actionable recommendation 3}}

## Sources

- {{Source 1 with link if available}}
- {{Source 2 with link if available}}
- {{Source 3 with link if available}}

## Linked Tasks

- Epic: {{EPIC_ID}}
- Task: {{TASK_ID}}

Manifest Entry Format

Append ONE entry via cleo manifest append <json> (writes to pipeline_manifest table per ADR-027):

{"id":"{{TOPIC_SLUG}}-{{DATE}}","file":"{{DATE}}_{{TOPIC_SLUG}}.md","title":"{{RESEARCH_TITLE}}","date":"{{DATE}}","status":"complete","agent_type":"research","topics":{{TOPICS_JSON}},"key_findings":["Finding 1","Finding 2","Finding 3"],"actionable":true,"needs_followup":[],"linked_tasks":["{{EPIC_ID}}","{{TASK_ID}}"]}

Field Guidelines

Completion Checklist

• Task details read via {{TASK_SHOW_CMD}}
• Research conducted across multiple sources
• Findings synthesized with recommendations
• Output file written to {{OUTPUT_DIR}}/
• Manifest entry appended (single line, valid JSON)
• Task completed via {{TASK_COMPLETE_CMD}}
• Response is ONLY the summary message

Error Handling

Partial Research

If complete answers cannot be found:

1. Document what was found
2. Note gaps and why they exist
3. Set manifest "status": "partial"
4. Add suggestions for followup to needs_followup
5. Complete task
6. Return: "Research partial. Manifest appended to pipeline_manifest."

Blocked Research

If research cannot proceed (access denied, topic too broad, etc.):

1. Document blocking reason
2. Set manifest "status": "blocked"
3. Add blocker details to needs_followup
4. Do NOT complete task
5. Return: "Research blocked. Manifest appended to pipeline_manifest."

Quality Standards

Findings Quality

• Evidence-based - Every claim has a source
• Current - Prefer recent sources (within 1-2 years)
• Relevant - Directly addresses research questions
• Actionable - Clear path from finding to action

Recommendation Quality

• Specific - Concrete actions, not vague suggestions
• Prioritized - Most important first
• Justified - Tied to specific findings
• Feasible - Achievable within project constraints

See also / References

This skill binds to the research LOOM lifecycle stage. Governing ADRs:

• ADR-023 — protocol validation dispatch — defines how research output is validated before downstream stages consume it.
• ADR-070 — three-tier orchestration — defines the Orchestrator → Phase Lead → Worker tiers; research runs as a leaf Worker.

LOOM coverage matrix: docs/skills/loom-coverage-matrix.md.

See references/

Progressive disclosure — load on demand only:

• references/triggers-and-routing.md — when to use ct-research-agent and what downstream skill consumes the output
• references/source-strategy.md — codebase + Context7 + web hierarchy, query patterns, time-boxing
• references/citation-and-evidence.md — evidence ladder, citation format, confidence labels
• references/anti-patterns.md — ten failure modes observed in past CLEO sessions and how to avoid them