Research Compound Skill

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)

| Criteria | Example | |----------|---------| | Applies to multiple files in domain | "All jobs inherit from ApplicationJob" | | Non-obvious convention | "Jobs must call super before custom logic" | | Gotcha that caused confusion | "CashApp jobs require merchant_id, not user_id" | | Integration pattern | "Jobs trigger webhooks via WebhookService" | | Testing insight | "Use freeze_time for scheduled job specs" |

Skip Recording (NO)

| Criteria | Example | |----------|---------| | One-off implementation detail | "ProcessPaymentJob has 3 retries" | | Already documented | Pattern exists in AGENTS.md | | Too specific to single file | "Line 42 has a TODO" | | Obvious from code | "Job processes payments" |

Update Protocol

Step 1: Locate Target AGENTS.md

Use nearest-wins hierarchy:

If {domain}/AGENTS.md exists → update it
If not, check parent folder
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:

| Learning Type | Target Section | |---------------|----------------| | Pattern/Convention | ## Patterns or ## Conventions | | Gotcha/Warning | ## Gotchas or ## Common Issues | | File organization | ## Structure | | Testing approach | ## Testing | | Integration point | ## Integration or ## Dependencies |

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

| Domain Depth | Create At | |--------------|-----------| | app/jobs/ | app/jobs/AGENTS.md | | app/jobs/cash_app/ | app/jobs/cash_app/AGENTS.md (if 3+ files) | | app/services/payments/ | app/services/payments/AGENTS.md |

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

Clarify the query - Identify the technology AND version (ask if not provided)
Search with version specificity - Always include version in queries (e.g., "Rails 8 API authentication" not "Rails authentication")
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
Evaluate sources - Prioritize: official docs > widely-adopted standards > community guides
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

| Don't | Do Instead | |-------|------------| | Dump all findings into AGENTS.md | Filter for generalizable patterns only | | Create AGENTS.md for every folder | Only domains with distinct patterns | | Write paragraphs | Single bullet points with examples | | Duplicate root-level guidance | Only domain-specific additions | | Update on every file read | Batch updates at research completion |

Agent Skills: Research Compound

Install this agent skill to your local

Skill Files