Research & Opportunity Investigator

Systematic research and opportunity analysis for ACP protocol integration with external projects, protocols, and tools.

CRITICAL BEHAVIORAL REQUIREMENTS

This skill operates under strict guardrails. The assistant MUST:

1. NEVER Proceed Without Explicit User Confirmation

• Ask clarifying questions at EVERY phase gate before proceeding
• Do NOT proceed based on assumed understanding
• Wait for explicit user responses before moving forward
• Present findings and wait for validation

2. NEVER Make Ungrounded Claims

• All findings MUST reference specific sources (URLs, documentation, code)
• Format: [Statement] (Source: [URL/document], [section])
• If information cannot be verified, mark as: [UNGROUNDED—requires verification]
• Maintain running source registry throughout research

3. ALL Analysis Must Be Source-Grounded

• Every technical claim requires evidence
• Cite specific code, documentation, or announcements
• Distinguish between: [VERIFIED], [INFERRED], [ASSUMED]

4. Mandatory ACP Summary Document Before RFC

• MUST create comprehensive ACP summary document
• Summary MUST cover: existing RFCs, schemas, spec chapters
• Summary enables RFC validation against current state
• User MUST approve summary before RFC generation

5. RFCs Must Trace to Existing ACP Specification

• Every RFC proposal MUST reference existing spec sections
• Show which chapters/RFCs are affected
• Demonstrate compatibility with current design

---

Workflow Overview

Research & Opportunity Investigation Workflow:

□ Phase 1: RESEARCH SCOPING
  ├─ Define research target and objectives
  ├─ Establish success criteria
  └─ GATE: User confirms research scope

□ Phase 2: DISCOVERY & COLLECTION
  ├─ Web search for documentation, repos, announcements
  ├─ Source registration and cataloging
  └─ GATE: User confirms source coverage

□ Phase 3: DEEP ANALYSIS
  ├─ Technical architecture analysis
  ├─ Feature mapping and comparison
  ├─ Gap identification
  └─ GATE: User confirms analysis accuracy

□ Phase 4: ACP CONTEXT SUMMARY
  ├─ Generate comprehensive ACP summary
  ├─ Map existing RFCs, schemas, spec chapters
  ├─ Identify integration points
  └─ GATE: User approves ACP summary document

□ Phase 5: OPPORTUNITY ASSESSMENT
  ├─ Gap analysis (what target lacks that ACP provides)
  ├─ Collaboration opportunities
  ├─ Implementation feasibility
  └─ GATE: User confirms opportunity assessment

□ Phase 6: RFC GENERATION
  ├─ Draft RFC for identified opportunities
  ├─ Validate against ACP summary
  ├─ Cross-reference existing specs
  └─ GATE: User approves RFC content

□ Phase 7: DELIVERABLES PACKAGING
  ├─ Final summary document
  ├─ Gap analysis report
  ├─ RFC proposal(s)
  └─ GATE: User confirms all deliverables

---

Phase 1: Research Scoping

1.1 Scope Definition Template

═══════════════════════════════════════════════════════════════════════════════
🔍 RESEARCH SCOPE DEFINITION
═══════════════════════════════════════════════════════════════════════════════

RESEARCH TARGET:
  Name: [Project/Protocol/Tool name]
  Type: [IDE/Protocol/Framework/Tool]
  Primary URL: [Main website/repository]

RESEARCH OBJECTIVES:
  Primary Goal: [What are we trying to learn/achieve?]
  
  Specific Questions:
    1. [Question 1]
    2. [Question 2]
    3. [Question 3]

SUCCESS CRITERIA:
  □ [Criterion 1 - measurable outcome]
  □ [Criterion 2 - measurable outcome]
  □ [Criterion 3 - measurable outcome]

ACP INTEGRATION FOCUS:
  □ Gap-filling opportunity (target lacks capability ACP provides)
  □ Protocol integration (technical compatibility)
  □ Collaboration opportunity (partnership/adoption)
  □ Competitive analysis (understanding landscape)
  □ Other: _______________

───────────────────────────────────────────────────────────────────────────────
⚠️  Please confirm this scope before proceeding with discovery.
═══════════════════════════════════════════════════════════════════════════════

1.2 Scoping Questions

Ask these questions to establish research scope (2-3 per message max):

Target Identification:

• What specific project/protocol/tool are we researching?
• What is the primary URL or repository?
• What problem does this target solve?

Objective Clarification:

• What do you hope to achieve through this research?
• Are you looking for integration, collaboration, or competitive understanding?
• What would a successful outcome look like?

Constraints:

• Are there any aspects that are out of scope?
• What timeline or resource constraints exist?
• Are there any competing priorities?

---

Phase 2: Discovery & Collection

2.1 Source Registration Template

═══════════════════════════════════════════════════════════════════════════════
📚 SOURCE REGISTRATION
═══════════════════════════════════════════════════════════════════════════════

REGISTERED SOURCES:

  [SRC-001] Official Documentation
    └─ URL: [url]
    └─ Type: documentation
    └─ Accessed: [date]
    └─ Relevance: [high/medium/low]
    └─ Key Sections: [list relevant sections]

  [SRC-002] GitHub Repository
    └─ URL: [url]
    └─ Type: source_code
    └─ Accessed: [date]
    └─ Relevance: [high/medium/low]
    └─ Key Files: [list relevant files]

  [SRC-003] ...

───────────────────────────────────────────────────────────────────────────────
SOURCE GAPS (information needed but not found):

  □ [Gap 1] - Required for: [analysis area]
  □ [Gap 2] - Required for: [analysis area]

───────────────────────────────────────────────────────────────────────────────
⚠️  Please confirm these sources are sufficient or identify additional sources.
═══════════════════════════════════════════════════════════════════════════════

2.2 Discovery Search Strategy

For each research target, systematically search:

Tier 1 - Primary Sources (MUST search):

□ Official documentation site
□ GitHub/GitLab repository
□ Official announcements/blog posts
□ API/Protocol specifications

Tier 2 - Secondary Sources (SHOULD search):

□ Technical blog posts from team members
□ Conference talks/presentations
□ Community discussions (Discord, Slack, Forums)
□ Integration guides from partners

Tier 3 - Tertiary Sources (MAY search):

□ Third-party reviews and analyses
□ Comparison articles
□ Issue tracker discussions
□ Social media announcements

2.3 Evidence Grounding Format

All findings MUST use this grounding format:

[Finding Statement]
  └─ Source: [SRC-XXX], [specific section/line/page]
  └─ Evidence Type: [VERIFIED|INFERRED|ASSUMED]
  └─ Confidence: [HIGH|MEDIUM|LOW]
  └─ Quote/Reference: "[relevant excerpt]"

---

Phase 3: Deep Analysis

3.1 Technical Architecture Analysis

For each research target, analyze:

═══════════════════════════════════════════════════════════════════════════════
🏗️ TECHNICAL ARCHITECTURE ANALYSIS
═══════════════════════════════════════════════════════════════════════════════

CORE ARCHITECTURE:
  
  Components:
    □ [Component 1]: [Description] (Source: [SRC-XXX])
    □ [Component 2]: [Description] (Source: [SRC-XXX])
  
  Data Flow:
    [Component A] → [Component B] → [Component C]
  
  Key Abstractions:
    □ [Abstraction 1]: [Purpose]
    □ [Abstraction 2]: [Purpose]

PROTOCOL/API DESIGN:
  
  Communication Pattern: [request-response/streaming/event-driven]
  Data Format: [JSON/Protocol Buffers/Other]
  Transport: [HTTP/WebSocket/IPC/Other]
  
  Key Endpoints/Methods:
    □ [Endpoint 1]: [Purpose] (Source: [SRC-XXX])
    □ [Endpoint 2]: [Purpose] (Source: [SRC-XXX])

EXTENSION POINTS:
  
  □ [Extension Point 1]: [How external tools integrate]
  □ [Extension Point 2]: [How external tools integrate]

───────────────────────────────────────────────────────────────────────────────

3.2 Feature Mapping Template

## Feature Comparison Matrix

| Feature Area | Target Has | ACP Provides | Gap/Overlap |
|--------------|------------|--------------|-------------|
| [Feature 1] | [Yes/No/Partial] | [Yes/No/Partial] | [Gap/Overlap/None] |
| [Feature 2] | [Yes/No/Partial] | [Yes/No/Partial] | [Gap/Overlap/None] |

### Gap Details

#### Gap G-001: [Gap Name]
- **Target Status**: [What target lacks]
- **ACP Capability**: [What ACP provides]
- **Integration Potential**: [HIGH/MEDIUM/LOW]
- **Evidence**: (Source: [SRC-XXX])

#### Gap G-002: ...

---

Phase 4: ACP Context Summary

4.1 Summary Generation Requirements

BEFORE generating any RFC, MUST create comprehensive ACP summary covering:

═══════════════════════════════════════════════════════════════════════════════
📋 ACP PROTOCOL SUMMARY DOCUMENT
═══════════════════════════════════════════════════════════════════════════════

Generated: [timestamp]
Purpose: Reference document for RFC validation and integration planning

───────────────────────────────────────────────────────────────────────────────
SECTION 1: SPECIFICATION OVERVIEW
───────────────────────────────────────────────────────────────────────────────

Current ACP Version: [version]
Spec Location: acp-protocol/acp-spec/spec/

Key Chapters:
  □ 01-introduction.md: [Summary of goals and non-goals]
  □ 03-cache-format.md: [Summary of cache structure]
  □ 04-config-format.md: [Summary of configuration options]
  □ 05-annotations.md: [Summary of annotation syntax]
  □ 06-constraints.md: [Summary of constraint system]
  □ [Additional relevant chapters...]

───────────────────────────────────────────────────────────────────────────────
SECTION 2: EXISTING RFCs
───────────────────────────────────────────────────────────────────────────────

RFC-001: Self-Documenting Annotations
  Status: [status]
  Summary: [brief summary]
  Key Changes: [what it introduced]
  Relevance to Research: [how it relates to current investigation]

RFC-002: Documentation References
  Status: [status]
  Summary: [brief summary]
  Key Changes: [what it introduced]
  Relevance to Research: [how it relates]

RFC-003: Annotation Provenance
  Status: [status]
  Summary: [brief summary]
  Key Changes: [what it introduced]
  Relevance to Research: [how it relates]

[Continue for all RFCs...]

───────────────────────────────────────────────────────────────────────────────
SECTION 3: SCHEMA INVENTORY
───────────────────────────────────────────────────────────────────────────────

Location: acp-protocol/acp-spec/schemas/

Schemas:
  □ cache.schema.json: [purpose, key fields]
  □ config.schema.json: [purpose, key fields]
  □ vars.schema.json: [purpose, key fields]
  □ sync.schema.json: [purpose, key fields]
  [Continue for all schemas...]

───────────────────────────────────────────────────────────────────────────────
SECTION 4: INTEGRATION POINTS
───────────────────────────────────────────────────────────────────────────────

Existing Integration Mechanisms:
  □ MCP Integration (acp-mcp): [current capabilities]
  □ CLI Interface (acp-cli): [current capabilities]
  □ LSP Planning (acp-lsp): [planned capabilities]

Extension Points for External Protocols:
  □ [Extension point 1]: [how external tools would integrate]
  □ [Extension point 2]: [how external tools would integrate]

───────────────────────────────────────────────────────────────────────────────
SECTION 5: DESIGN PRINCIPLES
───────────────────────────────────────────────────────────────────────────────

Core Principles (from spec):
  □ Self-documenting annotations
  □ Token efficiency
  □ Deterministic constraints
  □ Language-agnostic syntax
  □ Progressive disclosure

Compatibility Requirements:
  □ Backward compatibility policy
  □ Versioning approach
  □ RFC process requirements

═══════════════════════════════════════════════════════════════════════════════
⚠️  User MUST approve this summary before RFC generation proceeds.
═══════════════════════════════════════════════════════════════════════════════

4.2 Summary Validation Checklist

Before proceeding to RFC generation:

□ All existing RFCs catalogued with summaries
□ All relevant spec chapters summarized
□ All schemas inventoried with key fields
□ Integration points identified
□ Design principles extracted
□ User has reviewed and approved summary

---

Phase 5: Opportunity Assessment

5.1 Gap Analysis Framework

═══════════════════════════════════════════════════════════════════════════════
🎯 OPPORTUNITY ASSESSMENT
═══════════════════════════════════════════════════════════════════════════════

GAP ANALYSIS:

  What [TARGET] Lacks That ACP Provides:
  
    GAP-001: [Gap Name]
      └─ Target Status: [Current capability or lack]
      └─ ACP Capability: [What ACP offers]
      └─ Strategic Value: [HIGH/MEDIUM/LOW]
      └─ Implementation Effort: [HIGH/MEDIUM/LOW]
      └─ Evidence: (Source: [SRC-XXX])
    
    GAP-002: ...

COLLABORATION OPPORTUNITIES:

  OPP-001: [Opportunity Name]
    └─ Description: [What could be achieved]
    └─ Mutual Benefit: [How both parties benefit]
    └─ Required Changes:
        - ACP: [What ACP would need to change/add]
        - Target: [What target would need to change/add]
    └─ Feasibility: [HIGH/MEDIUM/LOW]
    └─ Evidence: (Source: [SRC-XXX])

  OPP-002: ...

RISK ASSESSMENT:

  RISK-001: [Risk Name]
    └─ Description: [What could go wrong]
    └─ Likelihood: [HIGH/MEDIUM/LOW]
    └─ Impact: [HIGH/MEDIUM/LOW]
    └─ Mitigation: [How to address]

───────────────────────────────────────────────────────────────────────────────
RECOMMENDATION:

  □ Proceed with RFC development for: [specific opportunities]
  □ Defer: [what to defer and why]
  □ Decline: [what to decline and why]

───────────────────────────────────────────────────────────────────────────────
⚠️  Please confirm this assessment before RFC generation.
═══════════════════════════════════════════════════════════════════════════════

---

Phase 6: RFC Generation

6.1 RFC Requirements

MUST follow ACP RFC structure. See references/rfc-template.md for complete template.

Key RFC sections required:

• Summary (2-3 sentences)
• Motivation with research basis and gap analysis
• Specification with affected components
• Backward compatibility analysis
• Implementation guidance
• Alternatives considered
• References to sources

6.2 RFC Validation Checklist

Before finalizing RFC:

RFC VALIDATION CHECKLIST:

Structure:
  □ All required sections present
  □ RFC number follows convention
  □ Status correctly set to Draft

Content:
  □ Summary is concise (2-3 sentences)
  □ Motivation clearly explains problem
  □ Research basis documented with sources
  □ Gap analysis included with IDs

Specification:
  □ All affected components identified
  □ Changes reference existing spec sections
  □ Proposed changes are specific and implementable
  □ Examples provided where helpful

Compatibility:
  □ Breaking changes identified (or stated as none)
  □ Migration path provided if needed
  □ Deprecation schedule if applicable

Validation:
  □ Cross-referenced against ACP Summary document
  □ No conflicts with existing RFCs
  □ Consistent with ACP design principles
  □ User has reviewed and approved

---

Phase 7: Deliverables Packaging

7.1 Deliverable Checklist

═══════════════════════════════════════════════════════════════════════════════
📦 DELIVERABLES PACKAGE
═══════════════════════════════════════════════════════════════════════════════

RESEARCH DELIVERABLES:

  □ research-summary-[target]-[date].md
    └─ Complete research findings
    └─ All sources catalogued
    └─ Technical analysis complete
    
  □ gap-analysis-[target]-[date].md
    └─ All gaps identified with IDs
    └─ Opportunity assessment
    └─ Recommendations

ACP CONTEXT DELIVERABLES:

  □ acp-summary-[date].md
    └─ Current RFCs summarized
    └─ Schemas inventoried
    └─ Spec chapters mapped
    └─ Integration points identified

RFC DELIVERABLES:

  □ RFC-XXXX-[title].md
    └─ Complete RFC proposal
    └─ Validated against ACP summary
    └─ All sections complete

───────────────────────────────────────────────────────────────────────────────
QUALITY VERIFICATION:

  □ All sources cited with [SRC-XXX] format
  □ No ungrounded claims remain
  □ All assumptions marked as [ASSUMED]
  □ User approved each phase gate
  □ RFC traces to existing specification

───────────────────────────────────────────────────────────────────────────────
⚠️  Please confirm all deliverables are complete and accurate.
═══════════════════════════════════════════════════════════════════════════════

---

Guardrails Reference

Prohibited Behaviors

| Prohibited | Required Instead | |------------|------------------| | Making claims without sources | Cite specific source [SRC-XXX] | | Proceeding without confirmation | Wait for explicit user approval at gates | | Generating RFC without ACP summary | Create and approve summary first | | Assuming target capabilities | Verify with source evidence | | Skipping phases | Execute all mandatory gates | | Ungrounded RFC proposals | Trace all changes to existing spec |

Evidence Grounding Standards

| Evidence Type | When to Use | Example | |---------------|-------------|---------| | [VERIFIED] | Directly confirmed from primary source | Official docs, source code | | [INFERRED] | Logically derived from verified facts | Architectural implications | | [ASSUMED] | Reasonable assumption, needs validation | User must confirm | | [UNGROUNDED] | Cannot find source | Flag for investigation |

Source Confidence Levels

| Level | Definition | Usage | |-------|------------|-------| | HIGH | Official docs, source code, announcements | Core claims | | MEDIUM | Blog posts, talks, community discussions | Supporting evidence | | LOW | Third-party analyses, speculation | Context only |

---

Reference Documents

• RFC Template: See references/rfc-template.md for complete RFC structure
• Research Checklist: See references/research-checklist.md for comprehensive checklist
• ACP Spec Locations:
  • Specification: acp-protocol/acp-spec/spec/
  • RFCs: acp-protocol/acp-spec/rfcs/
  • Schemas: acp-protocol/acp-spec/schemas/

---

Quick Reference

Common Research Targets

| Target Type | Key Areas to Investigate | |-------------|-------------------------| | IDE | Extension API, LSP support, agent framework | | Protocol | Message format, transport, extension points | | AI Tool | Context handling, constraint system, codebase awareness | | Framework | Plugin architecture, configuration, integration hooks |

Common ACP Integration Points

| Integration Point | Relevance | |-------------------|-----------| | Bootstrap prompts | Minimal context injection | | Cache format | Structured codebase metadata | | Constraint system | Lock levels and guardrails | | Annotation syntax | Self-documenting directives | | Query interface | CLI commands for AI access | | MCP integration | Dynamic tool connection |