Structured Context Engineering for File-Native Agentic Systems

# Research Integration: Structured Context Engineering for File-Native Agentic Systems

## Your Mission

Create a new branch and develop a detailed implementation plan for integrating this research idea into the codebase. Do NOT implement yet — focus on understanding, planning, and identifying risks.

## Branch Setup

```bash
git checkout -b experiment/structured-context-engineering-for-file-native-age
```

## The Research

**Paper**: [Structured Context Engineering for File-Native Agentic Systems](https://arxiv.org/abs/2602.05447)
**PDF**: https://arxiv.org/pdf/2602.05447

**Core Achievement**:
Identified that specific formats like TOON can reduce token usage by 20% while maintaining 100% schema accuracy.

**Why This Matters for carlcrm**:
The developer is already handling custom fields as JSON. This paper suggests that switching to a more agent-friendly format like TOON could improve the reliability of automated CRM workflows.

**Suggested Integration Approach**:
Modify the _row_to_dict function in carlcrm/services/companies.py to optionally output custom fields in TOON format when the requester is an AI agent.

**Estimated Effort**: quick read

## Goal Context

This addresses the following project goal:
> Develop a service layer for CRM entities that handles optimistic locking and JSON serialization for custom fields.

## Model Requirements

**Commercial APIs available**: Claude, GPT, Gemini

✅ **You can implement this using API calls only** — no local GPU required.

*The paper demonstrates that frontier-tier models (Claude, GPT, Gemini) accessible via API achieve the highest accuracy and benefit most from file-based context retrieval techniques.*

**Benchmarks used**: SQL generation

## Your Task: Create the Integration Plan

### Phase 1: Understand the Codebase Context

1. **Identify the integration surface**: Which files/modules would this touch?
2. **Map dependencies**: What existing code would this interact with?
3. **Find similar patterns**: Is there existing code that does something similar we can learn from?

### Phase 2: Design the Integration

Create a detailed plan covering:

1. **Architecture**: How does this fit into the existing system?
2. **Data flow**: What inputs does it need? What outputs does it produce?
3. **Configuration**: What new settings/parameters are needed?
4. **Testing strategy**: How will we validate this works?

### Phase 3: Premortem — What Could Go Wrong?

**Think about this integration failing 2 weeks from now. Why did it fail?**

Consider:
- **Performance**: Could this slow down critical paths?
- **Complexity**: Are we adding too much complexity for the benefit?
- **Maintenance**: Will this be hard to maintain or debug?
- **Dependencies**: Are we adding risky dependencies?
- **Edge cases**: What inputs or states could break this?
- **Rollback**: If this doesn't work, how easily can we revert?

For each risk, note:
- Likelihood (low/medium/high)
- Impact (low/medium/high)
- Mitigation strategy

### Phase 4: Define Success Criteria

Before implementing, define:

1. **Minimum viable test**: What's the simplest way to prove this works?
2. **Quantitative metrics**: What numbers should improve? By how much?
3. **Qualitative checks**: What should "feel" better?
4. **Failure signals**: What would tell us to abandon this approach?

## Output Format

Create a `PLAN.md` file in the repo root with:

```markdown
# Experiment: [Title]

## Summary
[1-2 sentence summary of what we're trying]

## Integration Points
- [ ] File 1: description of changes
- [ ] File 2: description of changes

## Architecture Decision
[Explain the chosen approach and why]

## Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| ... | ... | ... | ... |

## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Open Questions
- Question 1?
- Question 2?

## Next Steps
1. First implementation step
2. Second implementation step
```

## Important Guidelines

- **Read the paper first** — skim the abstract, intro, and methodology sections
- **Don't over-engineer** — start with the simplest version that could work
- **Preserve optionality** — design so we can easily extend or remove this later
- **Document decisions** — future you will thank present you
- **Ask questions** — if something is unclear, note it rather than assuming

---

*This prompt was generated by DSI (Daily Session Intelligence) to help you systematically explore research ideas.*