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)

Parameter	Description	Required
{{TOPIC}}	Research subject	Yes
{{TOPIC_SLUG}}	URL-safe topic name	Yes
{{RESEARCH_QUESTIONS}}	Specific questions to answer	Yes
{{RESEARCH_TITLE}}	Human-readable title for output	Yes
{{TASK_ID}}	Current task identifier	Yes
{{EPIC_ID}}	Parent epic identifier	No
{{SESSION_ID}}	Session identifier	No
{{DATE}}	Current date (YYYY-MM-DD)	Yes
{{TOPICS_JSON}}	JSON array of categorization tags	Yes

---

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. Record output: cleo docs add {{TASK_ID}} --content - --type research --slug {{TOPIC_SLUG}}
5. Record the manifest entry: cleo manifest append --task {{TASK_ID}} --type research --content "<one-paragraph summary>"
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 record findings with cleo docs add {{TASK_ID}} --content - --type research --slug {{TOPIC_SLUG}} (never a raw file under .cleo/agent-outputs/)
2. MUST record ONE manifest entry: cleo manifest append --entry '<entry JSON>' (the flat manifest file is retired, ADR-027)
3. MUST return ONLY: "Research complete. Manifest appended to pipeline_manifest."
4. MUST NOT return research content in response

---

Output File Format

Record it with cleo docs add {{TASK_ID}} --content - --type research --slug {{TOPIC_SLUG}}, using this body:

# {{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 --entry '<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

Field	Guideline
key_findings	3-7 one-sentence findings, action-oriented
actionable	true if findings require implementation work
needs_followup	Task IDs requiring attention based on findings
topics	2-5 categorization tags for discoverability

---

Completion Checklist

• Task details read via {{TASK_SHOW_CMD}}
• Research conducted across multiple sources
• Findings synthesized with recommendations
• Output recorded with cleo docs add (slug in the return message)
• 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