TAR - Technical Approach Research

Research and recommend technical approaches for implementation challenges or new features.

Purpose

TAR handles two types of research:

1. Problem Diagnosis: Research why something is broken/slow/buggy and propose fixes

   • Example: "Our Lambda functions are timing out under load"
   • Example: "OAuth token refresh is failing intermittently"

2. Feature Architecture: Research the best way to architect a new feature

   • Example: "Build real-time voice chat for web and mobile"
   • Example: "Add multi-account support to our authentication system"

Primary Goal: Thorough research and diagnosis. Understanding the problem deeply and recommending the right solution.

Secondary Benefit: Research output naturally contains information useful for creating GitHub issues later (if desired).

Input

Project/Feature Description:

$ARGUMENTS

Perplexity AI: Your Research Partner

USE PERPLEXITY ITERATIVELY - Don't Stop at the First Answer

Perplexity is your research partner. Have a conversation with it, dig deeper, ask follow-ups. Don't treat it like a search engine where you get one answer and move on.

Research Pattern

1. Start with perplexity_ask (5-20 sec)

• Get initial understanding of the problem/approach
• Identify key concepts and technologies

2. Dig Deeper with Follow-ups

• Ask about edge cases: "What are common pitfalls with [approach]?"
• Ask about gotchas: "What breaks when [condition]?"
• Ask about real examples: "Who uses [approach] in production?"
• Ask about alternatives: "What about [alternative approach]?"

3. Use perplexity_reason (30 sec - 2 min) for Implementation Details

• "How do I handle [specific technical challenge]?"
• "What's the debugging strategy when [error occurs]?"
• "Why does [approach] fail under [condition]?"

4. Use perplexity_research (3-10 min) ONLY for Deep Dives

• Comprehensive architecture analysis
• Multiple competing approaches need full comparison
• Novel/cutting-edge technology with limited documentation

Provide Comprehensive Context

Every Perplexity query should include:

• Environment: OS, versions, cloud provider, region
• Current State: What exists today, what's broken, error messages
• Constraints: Performance requirements, scale, budget, team skills
• Architecture: Related systems, dependencies, data flow
• Goal: What success looks like

Bad Perplexity Query:

"How do I fix Lambda timeouts?"

Good Perplexity Query:

"I have AWS Lambda functions in me-central-1 running Python 3.11 that call Aurora PostgreSQL via Data API. Under load (100+ concurrent requests), functions timeout after 30 seconds. Current config: 1024MB memory, no VPC, cold start ~2s, warm ~500ms. Database queries are simple SELECTs taking <50ms. What are the most likely causes and solutions? Looking for production-proven approaches."

Iterative Research Example

Round 1: "What causes Lambda timeouts with Aurora Data API?" → Response mentions connection pooling, query optimization, memory allocation

Round 2: "Does Aurora Data API support connection pooling? What are the gotchas?" → Response explains Data API is HTTP-based, no traditional pooling needed

Round 3: "What are the common Aurora Data API errors under high load and how to handle them?" → Response lists throttling, transaction timeouts, network issues

Round 4: "How do production systems handle Aurora Data API throttling? Show real examples." → Response provides retry strategies, backoff algorithms, monitoring approaches

Result: Deep understanding of the problem and battle-tested solutions.

Steps

1. Understand the Problem Space

For Problem Diagnosis:

• What's the symptom? (error messages, slow performance, unexpected behavior)
• When does it occur? (always, under load, specific conditions)
• What changed recently? (code, config, traffic, infrastructure)
• What's already been tried? (debugging steps, failed solutions)

For Feature Architecture:

• What's the user need? (what problem are we solving?)
• What are the constraints? (performance, scale, budget, timeline)
• What's the environment? (platforms, existing systems, team skills)
• What's the scope? (MVP vs full feature, what's out of scope)

2. Research with Perplexity (Iteratively!)

Initial Research (perplexity_ask):

• Problem diagnosis: "What causes [symptom] in [technology]?"
• Feature architecture: "How do companies implement [feature] for [scale/platform]?"

Follow-up Questions (keep digging):

• "What are the gotchas with [approach]?"
• "How does [company] handle [specific challenge]?"
• "What breaks when [condition occurs]?"
• "What's the debugging strategy for [error]?"
• "What are alternatives to [initial approach]?"

Deep Dive (perplexity_reason or perplexity_research if needed):

• Complex architectural decisions
• Multiple approaches need full comparison
• Novel technology with limited documentation

3. Examine Codebase (If Applicable)

If diagnosing a problem in existing code:

• Read relevant files to understand current implementation
• Check recent changes: git log --oneline -20 path/to/file
• Look for related issues: gh issue list --search "keyword"
• Check error logs, metrics, monitoring

4. Research Multiple Approaches

Find 3-4 viable approaches:

• Look for production case studies (last 2 years preferred)
• Focus on real-world implementations from companies at scale
• Include performance data, not just descriptions
• Note which approach is most common (battle-tested)

5. Evaluate Trade-offs

For each approach, analyze:

• Performance: Latency, throughput, resource usage
• Complexity: Dev time, code complexity, operational overhead
• Cost: Infrastructure, licensing, ongoing maintenance
• Scalability: How it handles growth
• Team Fit: Required skills, learning curve
• Risk: Common pitfalls, anti-patterns, failure modes

6. Make Recommendation

• Pick the approach that best fits the constraints
• Explain WHY this is recommended (not just what)
• Be honest about trade-offs and limitations
• Provide real examples of successful implementations
• Include actionable next steps

7. Deliver Research Report

Use the output format below. Keep focus on research quality, not on formatting for GitHub issues.

Output Format

# Technical Research: [Problem/Feature Name]

## Research Type
[Problem Diagnosis | Feature Architecture]

## Executive Summary
[2-3 paragraphs covering:
- What's the problem or what are we building?
- What did the research reveal?
- What's recommended and why?
- Key trade-offs to be aware of]

## Problem Analysis (For Diagnosis) OR Requirements (For Architecture)

**For Problem Diagnosis:**
- **Symptom**: [Exact error, behavior, or performance issue]
- **When It Occurs**: [Conditions, frequency, patterns]
- **Current State**: [What's already in place, recent changes]
- **Root Cause**: [What the research revealed]
- **Impact**: [Who/what is affected]

**For Feature Architecture:**
- **Core Need**: [What problem we're solving for users]
- **Constraints**: [Performance, scale, budget, timeline, technical]
- **Platforms**: [Web, mobile, APIs, infrastructure]
- **Scope**: [What's included, what's explicitly out of scope]
- **Success Criteria**: [What "done" looks like]

## Research Findings

### Key Insights from Research
1. [Major insight from Perplexity research]
2. [Important gotcha or edge case discovered]
3. [Production pattern or anti-pattern found]

### Technologies/Patterns Investigated
- [Technology/Pattern 1]: [Brief description]
- [Technology/Pattern 2]: [Brief description]
- [Technology/Pattern 3]: [Brief description]

---

## Approach 1: [Name] ⭐ RECOMMENDED

**Overview**: [One paragraph: what it is, how it works, why it exists]

**Why This Approach**:
- [Key advantage 1 - specific, measurable]
- [Key advantage 2 - real-world proof]
- [Key advantage 3 - fits constraints]

**Trade-offs**:
- ⚠️ [Limitation or consideration 1]
- ⚠️ [Limitation or consideration 2]

**Real-World Examples**:
- **[Company/Project]**: [How they use it, scale, results]
- **[Company/Project]**: [How they use it, scale, results]

**Common Pitfalls**:
- [Pitfall 1 and how to avoid it]
- [Pitfall 2 and how to avoid it]

**Complexity**: Low/Medium/High
**Development Time**: [Estimate based on research]
**Operational Overhead**: Low/Medium/High

---

## Approach 2: [Alternative Name]

**Overview**: [One paragraph description]

**Pros**:
- [Advantage 1]
- [Advantage 2]

**Cons**:
- [Disadvantage 1]
- [Disadvantage 2]

**When to Use**: [Specific scenarios where this is better than recommended approach]

**Real-World Examples**:
- [Company/Project using this approach]

---

## Approach 3: [Alternative Name]

**Overview**: [One paragraph description]

**Pros**:
- [Advantage 1]
- [Advantage 2]

**Cons**:
- [Disadvantage 1]
- [Disadvantage 2]

**When to Use**: [Specific scenarios where this is better than recommended approach]

**Real-World Examples**:
- [Company/Project using this approach]

---

## Comparison Matrix

| Aspect | Approach 1 ⭐ | Approach 2 | Approach 3 |
|--------|-------------|-----------|-----------|
| Dev Speed | Fast/Medium/Slow | ... | ... |
| Performance | Good/Excellent | ... | ... |
| Complexity | Low/Medium/High | ... | ... |
| Scalability | Good/Excellent | ... | ... |
| Cost | Low/Medium/High | ... | ... |
| Team Fit | Good/Poor | ... | ... |
| Battle-Tested | Very/Somewhat/New | ... | ... |

## Implementation Roadmap

**For Recommended Approach:**

### Phase 1: Foundation (Week 1-2)
1. [Specific technical task]
2. [Specific technical task]
3. [Validation checkpoint]

### Phase 2: Core Development (Week 3-4)
1. [Specific technical task]
2. [Specific technical task]
3. [Testing/validation]

### Phase 3: Polish & Deploy (Week 5+)
1. [Specific technical task]
2. [Performance testing/optimization]
3. [Production rollout]

## Critical Risks & Mitigation

| Risk | Impact | Likelihood | Mitigation Strategy |
|------|--------|-----------|---------------------|
| [Technical risk 1] | High/Medium/Low | High/Medium/Low | [Specific strategy] |
| [Technical risk 2] | High/Medium/Low | High/Medium/Low | [Specific strategy] |

## Testing Strategy

**What to Test**:
- [Specific test type 1 and why]
- [Specific test type 2 and why]

**Performance Benchmarks**:
- [Metric 1]: Target [value], measured by [method]
- [Metric 2]: Target [value], measured by [method]

## Key Resources

**Documentation**:
- [Official docs with URL and specific sections to read]

**Real Examples**:
- [GitHub repo / blog post with URL and what's relevant]
- [Production case study with URL and key takeaways]

**Tools/Libraries**:
- [Tool name with URL and what it does]

---

## Optional: Issue Creation Summary

**If creating a GitHub issue from this research**, the following information would be relevant:

**Summary**: [2-3 sentence summary for issue title/description]

**Key Requirements**:
- [Specific requirement 1]
- [Specific requirement 2]

**Recommended Approach**: [One paragraph on what to implement]

**Implementation Guidance**:
- [Problem to solve 1]
- [Problem to solve 2]

**Testing Needs**:
- [Test requirement 1]
- [Test requirement 2]

**Documentation Needs**:
- [Doc requirement 1]

Example Commands

Problem Diagnosis:

/tar Our Lambda functions are timing out when calling Aurora PostgreSQL via Data API under load. Functions are Python 3.11, 1024MB memory, no VPC, in me-central-1. Timeouts happen at 100+ concurrent requests.

Feature Architecture:

/tar Build a real-time voice chat feature for web and mobile apps with low latency (<200ms) and support for 10+ concurrent users per room. Budget conscious, team familiar with JavaScript/Python.

Notes

• Research is the goal - Deep understanding matters more than perfect formatting
• Use Perplexity iteratively - Ask follow-ups, dig into gotchas, find real examples
• Provide context - Every Perplexity query should include environment, constraints, goals
• Focus on practicality - Real implementations beat theoretical perfection
• Recency matters - Prioritize solutions from last 2 years (technology evolves)
• Show your work - Include Perplexity queries, sources, reasoning
• Be honest about trade-offs - No approach is perfect
• Real examples prove it works - "Company X uses this at Y scale" is gold
• Issue creation is optional - Sometimes research is just research