Context-Aware Research

The Problem With Generic Research

When you Google “how to parse EML files in Python,” you get dozens of blog posts and Stack Overflow answers. Each one assumes a different starting point — different OS, different Python version, different libraries already installed. You have to read through them all and figure out which approach fits your specific situation.

AI coding agents can do better. They can see your filesystem, your existing configuration, your installed tools. They can give you a recommendation that fits your project.

The Pattern

Ask research questions that include your context. Instead of “how do I parse EML files?”, ask within your project:

do tech research on how we can extract the data in emails/ to an organized content directory in markdown

The agent sees your existing mise.toml, your .gitignore, your project structure. It knows what tools you already have and what approach makes sense given your environment.

What Context-Aware Research Looks Like

Here’s what Claude produces after thinking for about 4 minutes:

Research Summary: EML to Markdown Extraction

Recommendation: Python with email stdlib + html2text

Why this stack:

- Zero dependencies for MIME parsing - Python's email module is in the standard library
- Automatic encoding handling - BytesParser handles quoted-printable and UTF-8 automatically
- Mature HTML conversion - html2text has 556K weekly downloads, battle-tested since Aaron Swartz created it
- Perfect for batch processing - 218 files processed locally without streaming overhead

Newsletter Categories Identified

The emails follow consistent patterns that enable automatic organization:

| Pattern     | Category            | Example                   |
| ----------- | ------------------- | ------------------------- |
| FOD#64:     | Findings of the Day | Technical findings series |
| Topic 4:    | Topic               | Deep-dive tutorials       |
| AI 101:     | AI101               | Educational content       |
| 🦸🏻#5:       | Agentic             | Agent/reasoning series    |
| 🌁#77:      | Insights            | SF-based insights         |
| 🎙️          | Podcast             | Interviews                |
| Guest post: | GuestPost           | Guest contributions       |

Caveats:

- html2text is GPLv3 licensed
- Complex email tables may need pre-cleaning
- Images are referenced but not downloaded by default

What Makes This Pattern Powerful

1. Recommendations Are Tailored

The agent knows you’re using mise for tool management, not pyenv or conda. It knows you have Python available through mise. It recommends Python’s stdlib email module because it sees a batch processing task (218 files), not a streaming use case.

Compare this to generic advice you’d get from searching, which might recommend Node.js mailparser (great for streaming, wrong for batch) or Docker-based tools (overkill for local processing).

2. Research Becomes Permanent Context

The agent writes its findings to reports/2025-11-30-eml-to-markdown-extraction.md with:

• Full frontmatter describing when to use and when not to use
• Complete code examples (copy-paste ready)
• Setup instructions
• A bibliography of sources
• Caveats section

This report lives in your project. Future agents read it before building. You never lose the research context.

3. Discovery Precedes Building

The agent identifies newsletter category patterns from the data before writing any code. It discovers that:

• Subject lines follow predictable regex patterns
• Plain text versions have real URLs (HTML versions have tracking links)
• Content can be organized into series subdirectories

These are insights you’d only discover by examining the data — and the agent does it for you.

The Structure of a Good Research Report

Every research report follows the same format:

---
title: Extracting Content from EML Files to Structured Markdown
date: 2025-11-30
topic: EML email parsing and HTML-to-Markdown conversion
recommendation: Python with email stdlib + html2text
---

# When to Use

- Batch processing of .eml files
- Converting MIME-encoded emails to readable Markdown
- ...

# When NOT to Use

- Real-time email processing requiring streaming
- Browser-based email parsing
- ...

## Executive Summary

[Brief recommendation with reasoning]

## Recommendation: [Chosen Approach]

### Why This Choice

[Simplicity, popularity, support analysis]

### Getting Started

[Installation and basic setup]

### Usage Guide

[Code examples]

## Alternatives Considered

[Table comparing alternatives]

## Caveats and Limitations

[When this is the wrong choice]

Apply This Pattern

The next time you need to make a technology decision in your project:

1. Start a fresh Claude Code session (clean context)
2. Ask within project context: “do tech research on how to [solve X problem] in this project”
3. Save the report to reports/
4. Build from the report in a later session

Don’t skip to implementation. Let the AI do the research first — it often finds simplifications you’d miss.

Next: Agents Writing Agents — The core pattern of this entire course.