Research Compound

Research Compound

Compound learnings into folder-specific AGENTS.md files during research work.

Trigger Conditions

Activate this behavior when:

• Investigating a specific domain (jobs, models, services, controllers, etc.)
• Using research agents (repo-analyst, docs-researcher, etc.)
• Reading multiple files in the same folder hierarchy
• User asks to "understand", "investigate", or "research" a subsystem

Pre-Research: Check Existing Context

Before diving into code, find and read the nearest AGENTS.md:

# From target folder, traverse up to find nearest AGENTS.md
# Example: researching app/jobs/cash_app/
# Check: app/jobs/cash_app/AGENTS.md
#        app/jobs/AGENTS.md
#        app/AGENTS.md
#        AGENTS.md (root)

What to Extract

From existing AGENTS.md, note:

• Known patterns and conventions
• Documented gotchas
• File organization rules
• Testing approaches
• Previous learnings (avoid re-discovering)

Pre-Research Output

Briefly acknowledge:

Found existing context in app/jobs/AGENTS.md:
- Jobs use Sidekiq with retry configuration
- Naming: *Job suffix required
- Testing: Use perform_inline in specs

Post-Research: Evaluate Learnings

After research, evaluate each discovery:

Worth Recording (YES)

Skip Recording (NO)

Update Protocol

Step 1: Locate Target AGENTS.md

Use nearest-wins hierarchy:

1. If {domain}/AGENTS.md exists → update it
2. If not, check parent folder
3. If no AGENTS.md in hierarchy → create at domain level

# Find existing AGENTS.md files
find . -name "AGENTS.md" -type f | head -20

Step 2: Determine Section

Map learning type to section:

If section doesn't exist, create it.

Step 3: Format the Learning

- **[Short title]**: [Concrete description]
  - Example: `path/to/example.rb:42`

Keep entries:

• Single bullet point (1-2 lines)
• Concrete, not vague
• With file reference when applicable

Step 4: Append (Don't Replace)

Use Edit tool to append to appropriate section:

## Gotchas

- **Existing gotcha**: Description
- **NEW: Merchant ID required**: CashApp jobs use `merchant_id`, not `user_id`
  - Example: `app/jobs/cash_app/process_payment_job.rb:15`

Creating New AGENTS.md

If no AGENTS.md exists in the domain hierarchy, create one:

# {Domain Name}

## Purpose

{One-line description of this domain}

## Patterns

- **Pattern name**: Description
  - Example: `path/to/file.rb`

## Gotchas

- **Gotcha name**: Description

## Testing

- **Testing approach**: Description

Placement Rules

Only create subfolder AGENTS.md if:

• 3+ files in that specific folder
• Distinct patterns from parent domain
• Significant complexity warranting isolation

Examples

Example 1: Pre-Research Check

User: "Investigate how background jobs work in this app"

Claude:
1. Target domain: app/jobs/
2. Check for AGENTS.md...
   - Found: app/jobs/AGENTS.md
3. Read existing context:
   "Jobs use Sidekiq, ApplicationJob base class, *Job suffix"
4. Proceed with research, avoiding re-discovery of known patterns

Example 2: Post-Research Update

After researching app/jobs/cash_app/:

Discovered:
- CashApp jobs require merchant_id (not user_id) ← WORTH RECORDING
- ProcessPaymentJob has 3 retries ← SKIP (too specific)
- All CashApp jobs log to separate channel ← WORTH RECORDING

Update app/jobs/cash_app/AGENTS.md:
## Gotchas
+ - **Merchant ID required**: Use `merchant_id`, not `user_id` for CashApp jobs
+   - Example: `app/jobs/cash_app/process_payment_job.rb:15`

## Patterns
+ - **Separate logging**: CashApp jobs use `CashAppLogger` channel
+   - Example: `app/jobs/cash_app/base_job.rb:8`

Example 3: Creating New AGENTS.md

Researching app/services/webhooks/ (no existing AGENTS.md)

After research, create app/services/webhooks/AGENTS.md:

# Webhooks

## Purpose

Outbound webhook delivery and retry management.

## Patterns

- **Delivery service**: All webhooks go through `WebhookDeliveryService`
  - Example: `app/services/webhooks/delivery_service.rb`
- **Payload builders**: Each event type has a `*PayloadBuilder`
  - Example: `app/services/webhooks/payment_payload_builder.rb`

## Gotchas

- **Idempotency required**: Webhooks may retry; receivers must handle duplicates
- **Timeout**: 30-second timeout on delivery attempts

Quality Checks

Before updating AGENTS.md, verify:

• Learning is generalizable (applies beyond single file)
• Not already documented
• Concrete enough to act on
• Has file reference for examples
• Matches existing AGENTS.md style/structure

Best Practices Research

When research requires external best practices (not just codebase analysis), use this methodology.

Research Process

1. Clarify the query - Identify the technology AND version (ask if not provided)
2. Search with version specificity - Always include version in queries (e.g., "Rails 8 API authentication" not "Rails authentication")
3. Use Perplexity MCP (mcp__perplexity-ask__perplexity_ask) to search for:
   • Official documentation for [technology] [version]
   • "[technology] [version] best practices [current year]"
   • Well-regarded open source examples
4. Evaluate sources - Prioritize: official docs > widely-adopted standards > community guides
5. Note version-specific guidance - Flag when practices apply only to certain versions

Best Practices Output Format

## [Topic] Best Practices

### Must Have
- **[Practice name]**: [Description]
  > "[Direct quote from source]"
  -- Source: [Link or reference]

### Recommended
- **[Practice name]**: [Description]

### Anti-patterns to Avoid
- **[Anti-pattern]**: [Why it's problematic]

### Sources
- [All referenced sources with links]

Research Constraints

• Research only -- do not implement or write code
• Cite everything -- no unsourced recommendations
• Note conflicts -- if sources disagree, present both views with trade-offs
• Be current -- flag outdated practices explicitly

Anti-Patterns