Understanding DAAF

What is DAAF?

DAAF is an AI-powered research assistant that helps you go from a research question to a completed analysis -- including data acquisition, cleaning, statistical analysis, visualizations, and a written report -- while keeping you in control of every decision. It runs inside a tool called Claude Code (Anthropic's AI coding assistant) on your computer. You interact with it by typing instructions in plain English, and DAAF handles the technical work while checking in with you at key decision points. Claude Code is a powerful general-purpose AI coding assistant, but it wasn't designed specifically for research -- DAAF adds the structure, the domain knowledge, and the safety guardrails that turn it into a rigorous research tool.

At its core, DAAF automates and simplifies the prompt-engineering process specifically for data analysis and research. Every single thing about how DAAF is designed is fundamentally about telling Claude exactly what it needs to know, when it needs to know it, so it does what you want more often and with higher quality on average. Ignoring the fancy terms like agents, subagents, skills, and orchestrators -- DAAF is a series of pre-built "recipes" of context that get fed to Claude before it tries to do what you ask, with the goal of making it more successful at working transparently, rigorously, and reproducibly.

Three Dimensions of AI Capability

One useful way to think about where AI is right now -- and why people seem to disagree so strongly about how capable it is -- is to think about AI capability as having three interdependent dimensions:

1. The Mind -- the base model's raw intelligence and reasoning ability. This is what Anthropic, Google, and OpenAI are competing on with each new model release.
2. The Body -- the orchestration frameworks and tooling that let the model actually do things: read files, run code, search the web, delegate tasks to other models. Claude Code is the "body" that lets Claude's "mind" interact with your computer. DAAF adds a much more structured and capable body on top of that.
3. The Instructions -- your skill in communicating what you want, plus whatever pre-built instructions the system provides.

Each dimension is necessary but insufficient on its own. A brilliant model with no tools can only chat. Powerful tools connected to a weak model will produce sophisticated-looking garbage. A strong model with great tools but vague instructions will go confidently in the wrong direction.

This brings us to one more concept worth knowing: context engineering. You may have encountered this term in the AI space recently -- it refers to the practice of designing systems, instructions, and processes that help an AI intelligently manage and assemble its own context for each specific task. It's a step beyond simply writing good prompts into something more architectural.

That's what DAAF is, at its core -- a context engineering framework designed specifically for research workflows. The DAAF Field Guide ↗ has more detail on these concepts.

This framework also explains why people have such wildly different experiences with AI. Someone chatting casually with a basic web interface is experiencing one narrow slice of what's possible. Someone using Claude Code with DAAF and well-crafted prompts is operating in a genuinely different capability regime -- not because the underlying model is different, but because the other two dimensions are dramatically more developed. The information gradient is steep: people who have invested in tooling and instruction quality are seeing capabilities that are invisible to casual users. This is a significant part of why discourse around AI can feel so polarized -- people are often talking past each other because they're working with very different combinations of these three dimensions.

The Mental Model: Orchestrator, Agents, Skills

I'm going to use an analogy that I think captures it well: DAAF is intended to mirror the workflows of a well-run research lab with you as the lead researcher.

The Orchestrator: Your Lab Director

When you type a message to DAAF, you're talking to the orchestrator. Think of the orchestrator as a lab director -- the person who takes your research question, figures out what needs to be done, decides who on the team should do each piece, coordinates the whole effort, and reports back to you at key milestones.

The orchestrator should NOT be doing the hands-on work itself, because its primary value-add and contribution is coordination and workflow management. It doesn't write analysis scripts, it doesn't clean data, it doesn't run regressions. What it does is:

• Classify your request into an engagement mode
• Delegate tasks in proper sequence to specialized agents
• Enforce quality gates
• Report progress to you and pause for your approval at key junctures
• Keep the big picture in mind

Specialized Agents: Your Research Team

Trying to get Claude to do everything equally well is impossible given fixed context window limitations, and trying to do so will ultimately confuse it and cause dreaded context rot (where an LLM becomes unpredictable and erratic due to overfilled or poorly structured context). This means that we need to split responsibilities across "versions" of Claude provided very different instructions and behavioral protocols.

Skills: Your Team's Reference Library

If agents define behavior ("how should I work?"), then skills define knowledge ("what do I need to know?"). Skills are structured knowledge documents that agents load into their own context on demand. Think of them as specialized reference manuals that your research team pulls off the shelf when they need domain-specific information.

Skill categories include:

• Data source skills -- Out of the box, we include education-data-explorer and education-data-query for finding and fetching data from the Urban Institute Education Data Portal, plus one skill for each major education data source, covering what endpoints exist, what variables mean and how they're coded, what caveats and limitations to watch for, what suppression rules apply, and historical context about data collection (Note: these are exemplar skills that should inform how you can make your own data skills via the Data Onboarding mode; DAAF is not restricted to the education data domain at all).
• Technical skills -- data-scientist for methodology and rigor principles, polars for data manipulation, plotnine for static publication-quality plots, plotly for interactive visualizations, marimo for reactive Python notebooks
• Meta skills -- skill-authoring and agent-authoring for extending DAAF itself

In DAAF, skills are generally intended to be loaded by agents, not by the orchestrator. When the orchestrator delegates a task to the research-executor, it tells the agent which skills to load. The agent pulls up the relevant reference material, uses it to guide its work, and returns findings to the orchestrator. This keeps the orchestrator's context lean and ensures each agent gets exactly the knowledge it needs for its specific task.

Click to expand

DAAF's multi-agent architecture: The user communicates with the orchestrator, which dispatches specialized agents. Each agent loads the skills it needs -- structured knowledge documents with optional sub-references for detailed guidance.

×

The Nine Engagement Modes

DAAF first classifies every request you make into one of nine engagement modes. Each mode triggers a fundamentally different workflow, different outputs, and different expectations. Understanding these modes is the single most useful thing you can do to work with DAAF effectively, because it helps you frame your questions in the way most likely to get you what you actually want.

Before doing anything else, DAAF will tell you which mode it's classifying your request into, explain why, and ask you to confirm. You should always have the chance to say "actually, I just wanted a quick lookup" or "actually, let's go deeper on this."

Expand any mode below for trigger words, detailed descriptions, and guidance on when to use it -- and when not to:

Mode Transitions

DAAF supports clean transitions between any pair of modes where the shift makes sense. You don't need to memorize the transitions -- DAAF will suggest the right mode at natural breakpoints and wait for your confirmation. It should never silently switch modes on you.

Try It Yourself: A Guided Progression

Rather than try to jump in with a complete Full Pipeline Analysis at once, I strongly recommend testing out the simpler features and engagement modes first. Here's a concrete progression I'd recommend, designed to let you assess DAAF's knowledge and capabilities at each level of complexity:

Anatomy of a Completed Analysis

When a Full Pipeline analysis completes, your project folder will look something like this:

Each artifact serves a specific purpose. The Plan.md is the single most important artifact in the project -- it captures everything about what was done and why. It includes the research question (verbatim), Research Outcomes (specific, measurable topics the analysis must investigate -- these define what must be examined, not what the answer should be), data sources with rationale, methodology with justification, a risk register, and a key decisions log. If any outcomes read like hypotheses (predicting a direction), flag them. Plan_Tasks.md contains the detailed machine-readable task specifications with the exact transformation sequence, dependencies, wave assignments for parallel execution, and input/output file paths.

The scripts/ directory is the real work product -- not the notebook. Get a sense for how these scripts are actually written and run: this is where DAAF's value lives. Without the core engine of data analysis being transparent, rigorous, and reproducible, nothing else that comes out of this process is valuable. Spend time here. Each script reads top-to-bottom like a lab notebook with clear section headers, inline audit trail comments explaining intent and reasoning, embedded validation assertions, and an appended execution log showing exactly what happened when the script ran. When a script fails QA and needs revision, the original keeps its output (it's part of the audit trail), and the revised version gets a letter suffix: 01_task.py → 01_task_a.py → 01_task_b.py. The cr/ subdirectory contains the code-reviewer's independent QA inspection scripts for every analysis script.

The Notebook.py is a Marimo notebook assembled from the completed scripts -- it's the presentation layer, not where analysis was done. What you won't see in the notebook: new analysis code, interactive dashboards, filter widgets, or additional transformations. This ensures what you see is exactly what was executed and validated, with nothing added or changed. The Report.md is a stakeholder-ready narrative synthesizing key findings, methodology, limitations, visualizations, and a references section (data sources, methodological references, software, and reporting standards -- DAAF tracks these automatically, though you should verify accuracy).

All data files use Apache Parquet format rather than CSV. Parquet preserves data types (integers stay integers, dates stay dates), compresses efficiently, and is fast to read. CSV files lose type information -- everything becomes a string -- which introduces subtle bugs. Parquet prevents an entire category of data quality issues.

STATE.md tracks the current state of the analysis -- which tasks are completed, which are pending, and any issues encountered. This is critical for multi-session work. LEARNINGS.md captures data source quirks, surprising findings, and methodological notes that might help future analyses.

Sample Projects

The repository includes sample projects in the research/ folder to illustrate what DAAF produces. The College Graduation Rate & Selectivity Analysis ↗ demonstrates a complete Full Pipeline run -- browse the Report ↗, the Plan ↗, a data fetch script ↗, or a statistical analysis script ↗ to see real artifacts. A companion Reproducibility Verification ↗ shows what independent re-execution and verification looks like.

These projects are presented as-is -- some interpretation is arguably overblown, and some analytical choices could be questioned. That's the point: DAAF produces work that is worth reviewing, not work that can be trusted blindly.

Dual-Layer Validation

Layer 1: Primary Validation (CP1-CP4)

Layer 2: Secondary Validation (QA1-QA4b)

If a primary checkpoint fails, execution stops -- DAAF doesn't try to power through. It reports the failure and either attempts a fix or escalates to you. The code-reviewer approaches each script with an adversarial mindset and inspects it immediately after execution, not batched at the end -- because an error in script 1 that goes undetected will silently propagate through scripts 2, 3, and 4.

Why two layers? Because they catch different types of errors. Primary validation catches operational failures -- the data is empty, the types are wrong, something clearly broke. Secondary QA catches methodological errors -- the code runs fine and produces output, but the methodology is wrong, the join logic is subtly off, or the interpretation doesn't match what the data actually shows. These are the insidious errors that are easy to miss when reviewing AI-generated code, and they're exactly the errors that matter most for research integrity.

The Full Pipeline Flow

The orchestrator coordinates several specialized agents for different tasks. You don't need to memorize these names -- DAAF manages them automatically. The important thing is understanding the overall flow and where your review points are.

1. You ask a research question
2. The orchestrator classifies the request as Full Pipeline and confirms with you
3. The orchestrator delegates data exploration to a subagent
4. The orchestrator delegates source deep-dives to source-researcher agents
5. A synthesis agent consolidates all findings
6. The orchestrator pauses for your review (Phase Status Update 1) ← your checkpoint
7. A planning agent creates a detailed Plan, validated by a plan-checking agent
8. The orchestrator pauses for your review again (Phase Status Update 2) ← your checkpoint
9. An execution agent works through each task, with a code-reviewing agent inspecting each script
10. The orchestrator pauses twice more for your review (Phase Status Updates 3 and 4) ← your checkpoints
11. A notebook assembly agent compiles all scripts
12. A report-writing agent creates the stakeholder report
13. A verification agent performs adversarial final verification
14. The orchestrator delivers everything to you

Context Windows and Prompt Engineering 101

Now that you understand what DAAF does and how it's structured, let's cover the foundational concept that makes it all work: how large language models (LLMs) -- the AI technology behind tools like ChatGPT and Claude -- process information.

1. LLMs are designed to be really good at predicting the next word when given a sequence of words. They learn how to do this "well" in a variety of ways, but that's really the crux of it: everything about their current functionality, no matter how fancy or surprising (e.g., making powerpoints, searching the web, writing/running code, etc.), is still predicated on that one simple premise.
2. How "well" LLMs work and what they can do is extremely dependent on the words you provide to it before you ask it to predict the next one. These preliminary words we provide to LLMs first are known as "context". This concept of context is absolutely mission-critical for any work with LLMs for two key reasons:
   • Different LLMs can only "digest" and use a certain amount of context at a time before predicting the next word, which is known as its "context window". To put this in perspective: GPT-3 could only "read" ~1,500 words before predicting the next one. Claude Opus 4.6 has a context window of ~150,000 words by default, and Anthropic is beta testing context windows of ~750,000 words at time of writing. The more context a model can incorporate, the more expertise, skills, and framing it can use for tasks you want it to do.
   • Another frontier of LLM advancement is teaching the LLM how to carefully and thoughtfully pay attention to different aspects of its provided context more judiciously. Not all context is treated equally, and so we need to account for that when providing an LLM with context. LLMs can get strangely confused and become erratic when their context windows are filled in ways they can't really process: this is known as context rot, and needs to be avoided at all costs.
3. The complex task of trying to maximize an LLM's performance at a requested task by carefully deciding (a) exactly what context, and how much, to give an LLM given its current context window limitations, and (b) how to structure that provided context strategically and optimally for the task at hand to prevent confusion/distraction, is what is known as prompt engineering.

So with that in mind, DAAF can be thought of as a way to help researchers by automating and simplifying the prompt-engineering process specifically for core aspects of the data analysis and research process. Every single thing about how DAAF is designed is really just fundamentally designed to tell Claude exactly what it needs to know, when it needs to know it, so it does what we want more often and with higher quality on average.

Session Management

DAAF monitors its own context utilization to manage long-running analyses gracefully:

When a session ends (whether by context exhaustion or user choice), DAAF writes a comprehensive STATE.md that captures exactly where work stands and provides a restart prompt -- a pre-written message capturing exactly what has been done and what needs to happen next.

How to Restart a Session

1. Type /clear in the Claude Code terminal to reset the session (this clears the context window but does not affect any files on disk)
2. Paste the restart prompt that DAAF provided
3. DAAF reads STATE.md, picks up where it left off, and continues working

If you closed your terminal entirely or the session crashed, start a new Claude Code session and point DAAF to the project folder -- it will read STATE.md and figure out where to resume.

Reproducibility Verification mode note: Reproducibility Verification mode uses Reproduction_Report.md as its session state document instead of STATE.md.

Where Things Live

You don't need to know what's in most of these directories. The two that matter to you are research/ (where your analyses live) and user_reference/ (where documentation lives). Everything else is DAAF's internal machinery.

Everything you need to review, share, or reproduce is inside the project folder. You can copy the entire folder to a colleague and they'd have everything needed to understand and verify the analysis -- that's the whole point of reproducibility.

Browsing and Viewing Your Work

DAAF includes convenience scripts for viewing your files, notebooks, and session logs outside of the terminal:

• Browse and edit project files: bash run_vscode.sh (macOS/Linux) or .\run_vscode.ps1 (Windows) -- opens a browser-based VS Code editor
• View interactive notebooks: bash view_notebooks.sh (macOS/Linux) or .\view_notebooks.ps1 (Windows) -- opens Marimo at localhost:2718
• View session logs: bash view_logs.sh -- opens the DAAF Log Explorer, an interactive timeline that shows orchestrator actions, subagent dispatches, and tool calls in your browser at localhost:2719