Skip to content

DAAF-Contribution-Community/daaf / .claude/skills/daaf-orchestrator

daaf-orchestrator

Verified

Operational framework for the DAAF orchestrator. Defines engagement modes, confirmation protocol, subagent dispatch, context budget, and reference-loading. Loaded exclusively by the orchestrator — not for subagents or user questions.

references/ad-hoc-collaboration-mode.md

View on GitHub
# Ad Hoc Collaboration Mode

Flexible, user-driven collaboration for skilled researchers who want a rigorous thought partner. The user brings whatever they're working on -- a script to debug, an approach to think through, a data question, code to review, a one-off analysis task, a package question -- and DAAF responds with domain expertise, methodological rigor, and hands-on support. No formal deliverables are required, but artifacts can be produced on request.

## User Orientation

The mode confirmation already gave the user this preview, so do not repeat it after confirmation. Present these points only when the user signals they are new to DAAF or asks for more detail.

- This is a flexible working session -- bring whatever you need help with
- I can review code, debug scripts, investigate data sources, write analysis code, brainstorm approaches, explain packages, and more
- If you point me to files or documents, I read them first and, before anything multi-step, tell you what I see and what I plan
- A workspace is created the first time we produce something -- a script, data, a figure, or session notes once there is a decision or result worth recording -- and I'll suggest its name then
- You're in control -- change topics freely, ask follow-ups, or escalate to a full analysis pipeline at any time

**For more detail:** Consult `{BASE_DIR}/user_reference/02_understanding_daaf.md`.

---

## Scope Check

- **Tier:** Soft. A statement of what you see and what you plan, never a gate: this mode imposes no checkpoints (§ Boundaries > Never Do).
- **When:** before each new multi-step or artifact-producing task: once per task, not on every turn. A question answered in conversation gets no check.
- **Read first:** the files, documents, URLs or prior projects the user pointed to, wherever they live (§ Working with User-Provided Files), before saying anything about the plan. The read-first rule in `SKILL.md` § Scope Check > Read First covers PDFs (one `search-agent` digest), web pages and large projects. A data file is described from its listing only; its rows are examined by the dispatched agent's scripts, not read into the conversation.
- **Where reads land:** until the workspace exists, fetches, PDF ingests and a digest are staged in the session scratchpad (`SKILL.md` § Scope Check > Read First); they graduate into the workspace when the first artifact creates it (§ Workspace Setup). Once the workspace exists, fetch into its `web_fetches/` directly.
- **What to say:** "Here's what I see in [materials]; here's my plan. I'm starting on it now — stop me if anything looks off." (With no materials, just the plan.) Then start in the same turn; the user can redirect at any point. When this action will create the workspace, name its proposed topic label here (§ Workspace Setup).
- **When to ask instead:** if the materials or the request leave two readings that would lead to different work, ask that one question and wait. That is a clarifying question, not a checkpoint.

Why: a plan stated after reading costs one sentence and lets the user catch a wrong interpretation before effort is spent, without turning a flexible session into a gated one. The tier definitions are in `SKILL.md` § Scope Check.

---

## Ad Hoc Collaboration Workflow

Unlike pipeline modes, Ad Hoc Collaboration has no fixed stage progression. The orchestrator operates in a **dispatch loop**, responding to whatever the user brings:

```
┌─────────────────────────────────┐
│   User asks / provides context  │
└───────────────┬─────────────────┘
                │
┌───────────────▼─────────────────┐
│   Orchestrator identifies need   │
│   and either:                    │
│   (a) responds directly, or     │
│   (b) dispatches to agent       │
└───────────────┬─────────────────┘
                │
┌───────────────▼─────────────────┐
│   Response delivered to user     │
└───────────────┬─────────────────┘
                │
                ▼
   [User continues, changes topic,
    or exits]
```

There are no mandatory checkpoints, gates, or phase transitions. The user drives the conversation. The orchestrator's role is to identify what the user needs and bring the right capabilities to bear -- either by responding directly or by dispatching to a specialized agent.

**Intent check for multi-step tasks:** When the orchestrator infers a multi-step task from a loose conversational request (e.g., the user says "can you take a look at my enrollment analysis?" and the orchestrator prepares to dispatch research-executor), give the soft Scope Check before executing (§ Scope Check): read whatever the user referenced first, then a brief "Here's what I see in [your analysis]; here's my plan: a script that [does X]. I'm starting on it now — stop me if anything looks off." Then start in the same turn. This catches a wrong interpretation early without becoming a checkpoint, and it comes once for each new multi-step task, not on every turn.

---

## Workspace Setup

Workspace creation is **deferred until the first artifact-producing action.** If the session remains purely conversational (advice, brainstorming, package questions, methodology discussion), no workspace is needed.

When an artifact-producing action is triggered (dispatching a coding agent, saving a file — including SESSION_NOTES.md at the first milestone, § Session Notes and Continuity — running a script), the orchestrator creates:

```
research/YYYY-MM-DD_AdHoc_{Topic}/
├── scripts/
│   ├── adhoc/                     # For research-executor tasks
│   ├── debug/                     # For debugger agent
│   ├── cr/                        # For code-reviewer agent
│   └── scratch/                   # Working files, never relied on (created on first use)
├── data/
│   ├── raw/
│   └── processed/
├── output/
│   ├── analysis/
│   └── figures/
├── web_fetches/                   # web_fetch.sh DEST_DIR (created on first use)
├── papers/                        # pdf_ingest.sh output, e.g. staged papers moved in (created on first use)
├── user_pdfs/                     # copies of user PDFs from outside /daaf (created on first use)
├── logs/                          # collect_session_logs.sh output (created at wrap-up)
└── lit_search/                    # scholar_search.sh DEST_DIR (created on first use)
```

**Topic naming:** Propose a short topic label when the workspace is created, not at mode confirmation. By then you have read what the user pointed to and know what is being made, so the label reflects the work rather than a guess from the opening request, and a purely conversational session never needs one. Name it in the soft Scope Check when one precedes the action, otherwise in the message that creates the workspace (e.g., "I'm saving this to a workspace called 'Geospatial_Join_Debug' -- tell me if you'd prefer another name"); do not wait for an answer. If the work has no clear topic (e.g., "I have a few things to work on today"), use the fallback `YYYY-MM-DD_AdHoc_Session`.

**No STATE.md. No Plan.md.** These can be created later if the session evolves to need them (e.g., the user asks for a formal plan, or decides to escalate to Full Pipeline).

**LEARNINGS.md** is not created by default. If the session produces reusable insights (e.g., a data source caveat discovered during debugging, a methodology lesson), the orchestrator may create one in the workspace to capture them.

**Setup commands:** Execute these as individual Bash calls when workspace creation is triggered:

```bash
mkdir -p {PROJECT_DIR}/scripts/adhoc
mkdir -p {PROJECT_DIR}/scripts/debug
mkdir -p {PROJECT_DIR}/scripts/cr
mkdir -p {PROJECT_DIR}/data/raw
mkdir -p {PROJECT_DIR}/data/processed
mkdir -p {PROJECT_DIR}/output/analysis
mkdir -p {PROJECT_DIR}/output/figures
```

**Staged materials graduate now.** If read-first materials were staged before the workspace existed (§ Scope Check), move them in right after the setup commands and before anything cites them: `web_fetches/`, `papers/` and `user_pdfs/` to the same-named workspace folders, the digest to the workspace root beside SESSION_NOTES.md (the layout has no notes folder), one `mv` per call; then re-ingest any paper whose source PDF moved, with `--reingest`. Record the moves as one dated old → new line in SESSION_NOTES.md, creating it if needed (`SKILL.md` § Scope Check > Read First > "Graduation on confirmation").

---

## Orchestrator Skill Loading

**Exception to standard pattern:** The orchestrator loads `data-scientist` directly via the Skill tool at the start of Ad Hoc Collaboration mode, and also loads `creative-verification` directly on demand when a verification need surfaces (see "Creative Verification (Analytic Triangulation)" below). This is one of two modes where the orchestrator itself loads skills directly (the other is Framework Development, which loads `skill-authoring` and `agent-authoring`). Normally skills are loaded by subagents only.

**Rationale:** In this mode, the orchestrator frequently responds directly to the user -- advising on methodology, discussing approaches, explaining concepts -- and needs the `data-scientist` skill's methodology knowledge to provide rigorous advice without dispatching a subagent for every question.

Additional domain skills are loaded by subagents when dispatched, following the standard pattern. The available library skills depend on execution language:

| Python Skill | R Skill | Domain |
|-------------|---------|--------|
| `polars` | `tidyverse` | Data manipulation |
| `plotnine` | `ggplot2` | Static visualization |
| `plotly` | `plotly-r` | Interactive visualization |
| `statsmodels` | `r-stats` | Standard regression / GLM |
| `pyfixest` | `fixest` | Fixed effects / DiD |
| `linearmodels` | `plm` | Panel RE / between / FD / Fama-MacBeth. LIML, non-panel GMM-IV, SUR, 3SLS: Python only (R: no installed package, escalate). Dynamic-panel GMM: `plm` (`pgmm`) in R; no DAAF Python skill (`pydynpd` is installed but no skill covers it), escalate |
| `svy` | `survey-r` | Complex survey analysis |
| `scikit-learn` | `tidymodels` | Machine learning |
| `geopandas` | `sf-terra` | Spatial analysis |
| `great-tables` | `gt` | Table formatting |
| `marimo` | `quarto` | Notebook format |

Domain-specific data source skills (e.g., `education-data-source-ccd`) are language-agnostic.

When the user asks about a specific tool or package and the orchestrator answers directly, loading the relevant skill first is the expected precondition for that answer — library skills encode environment-specific constraints and curated caveats that general knowledge lacks, so answering without the skill risks recommending approaches this environment cannot run or that the skill explicitly warns against. If a skill fails to load, answer from base knowledge and flag reduced confidence due to the missing skill.

---

## Creative Verification (Analytic Triangulation)

Ad Hoc Collaboration is the pilot venue for **creative verification** — collaborative
analytic triangulation that stress-tests a provisional finding or designs pre-specified
challenges before an analysis runs. Its purpose is to reduce the researcher's line-by-
line code-review burden by substituting behavioral, output-level verification
(independent re-derivation, reconciliation, discriminating tests) for granular code
spelunking: "calibrated confidence per unit of researcher attention."

**Trigger signals.** Reach for it when the user wants to:

- verify, challenge, stress-test, or "poke holes in" a result they already have;
- understand whether a finding survives different denominators, specifications, windows,
  or measures;
- design discriminating or pre-specified challenges *before* running an analysis;
- reduce what they would otherwise feel obligated to inspect by hand, line by line.

**How the orchestrator runs it.** Load the `creative-verification` skill **directly** via
the Skill tool — the same direct-load exception this mode grants `data-scientist`
(Orchestrator Skill Loading above), loaded on-demand when a verification need surfaces
rather than at session start. Then run the skill's **challenge loop** conversationally
(elicit the researcher's own concern first → state the focal claim precisely → generate
competing explanations including data/process ones → identify discriminating observables
→ prioritize a small first bundle → pre-commit each test's interpretation rule → execute
through normal DAAF machinery → interpret against the pre-committed rule → update the
ledger, then stop, iterate, or promote). Existing agents execute the tests: dispatch
`research-executor` for challenge scripts and diagnostic artifacts, `code-reviewer` for
QA, `debugger` for a *reveals-data/process-issue* result that needs root-causing —
using the standard Ad Hoc dispatch conventions above.

**Maintain the ledger.** Keep a hypothesis/evidence ledger at
`{PROJECT_DIR}/TRIANGULATION_LEDGER.md` per `agent_reference/TRIANGULATION_PROTOCOL.md`
(two tables — hypotheses and tests — with interpretation rules pre-committed before
execution; the ledger is the arbiter and doubles as a coverage map of what has and has
not been triangulated). The orchestrator owns the ledger; subagents return results and
the orchestrator records them. Diagnostic dashboards (Plotly HTML / standalone Marimo
apps) are separately-planned artifacts, never Stage 9 notebooks, and pass the skill's
interactive-artifact QA contract.

**Escalation.** Creative verification runs alongside the official analysis and never
silently changes it. New data sources, population changes, or methodology changes need
explicit user approval before a test runs. When a confirmed triangulation result should
be acted on — adopting a different denominator, adding a robustness result, correcting a
data-process issue — **promote it into Revision and Extension mode** (Escalation Triggers
below), rather than editing the official analysis in place.

---

## Skill Information and Online Verification

Skills are a solid starting point for framework conventions and domain knowledge — they represent curated, reviewed content that is more reliable than ad-hoc inference. However, skills are point-in-time snapshots: APIs evolve, endpoints deprecate, documentation updates, and coded values change.

**The critical distinction:** Information the orchestrator or agents supply *beyond* what is explicitly encoded in a skill is LLM-generated inference — not curated knowledge — and is substantially more likely to be wrong. This is a core limitation of LLM agents: they can confidently produce plausible-sounding details that are partially or entirely fabricated. When responding directly (without dispatching), the orchestrator should distinguish between what it knows from a loaded skill vs. what it is inferring from general knowledge, and be transparent about this distinction with the user.

**When to verify online:** The orchestrator CAN and SHOULD use WebSearch (to discover) plus the DAAF fetch protocol (`web-retrieval` skill's `web_fetch.sh`; the built-in WebFetch is blocked) to verify information when:
- A skill's `skill-last-updated` frontmatter date suggests staleness (more than a few months old)
- The orchestrator is filling in details beyond what the skill explicitly covers
- An API endpoint, URL, variable name, or coded value produces unexpected results
- The user asks about something the loaded skills don't cover comprehensively
- The orchestrator is about to present a specific factual claim (not a framework convention) drawn from general knowledge rather than a skill

**Proactive surfacing:** Do not wait for the user to ask whether information should be verified. Proactively surface that online verification is available when the situation warrants it:
- *"This detail isn't covered by my curated knowledge, so I'm working from general knowledge — want me to verify this online before we proceed?"*
- *"I can look up the latest documentation for this to make sure we're working with current information."*
- *"The skill I'm drawing from was last updated [date] — I can cross-check against the source's current docs if that would be helpful."*

**When dispatching to agents:** Agents with web access (search-agent, data-ingest, debugger) can verify directly. For agents without it (research-executor, code-reviewer), unexpected errors or results that may stem from skill drift should be flagged in return output so the orchestrator can dispatch verification via search-agent or verify directly.

---

## Dispatch Logic

The orchestrator identifies what the user needs and responds accordingly. This is not a rigid classification -- the orchestrator uses judgment, and the user may shift between topics freely within a session.

### When to Respond Directly

The orchestrator responds directly (without dispatching a subagent) when:

- The user asks about methodology, statistical approaches, or research design
- The user asks about a package or tool that the orchestrator can answer by first loading the relevant skill via the Skill tool, then answering from it (e.g., Python: `polars`, `plotnine`, `marimo`, `statsmodels`, `pyfixest`, `linearmodels`, `geopandas`, `scikit-learn`; R: `tidyverse`, `ggplot2`, `quarto`, `r-stats`, `fixest`, `plm`, `sf-terra`, `tidymodels`; either: `science-communication`)
- The user asks a conceptual question about data or analysis
- The user wants to brainstorm or think through an approach
- The question can be answered adequately from the orchestrator's loaded skills — general knowledge may supplement a loaded skill, but where a relevant skill exists it should be loaded rather than answered from memory, and anything inferred beyond skill content must be flagged as inference (per the loaded-vs-inferred distinction above)

### When to Dispatch to an Agent

The orchestrator dispatches to a specialized agent when:

- The task requires code execution (writing and running scripts)
- The task requires deep data source investigation (caveats, coded values, suppression patterns)
- The task requires formal review rigor (QA inspection scripts, adversarial evaluation)
- The task requires hypothesis-driven diagnosis (scientific debugging methodology)
- The task requires structured planning output (analysis outlines, research plans)

### Dispatch Table

| User Need | `subagent_type` | Notes |
|-----------|----------------|-------|
| Write or run analysis code | `research-executor` | Orchestrator frames the user's request as a `<task>` block. When the task involves statistical modeling, use the `data-scientist` skill's routing tree (§ Related Skills - When to Load > Load for Specific Needs, Statistical modeling branch) to select the library by execution language. Python: `statsmodels` for standard regression/GLM/diagnostics/time series, `pyfixest` for fixed effects/DiD/IV, `linearmodels` for random effects/between/first difference/Fama-MacBeth/LIML/non-panel GMM-IV/SUR/3SLS, `svy` for complex survey analysis, `geopandas` for spatial regression, `scikit-learn` for clustering/prediction ML; dynamic-panel GMM has no DAAF Python skill (escalate). R: `r-stats` for standard regression/GLM/time series, `fixest` for FE/DiD/IV, `plm` for RE/between/FD/Fama-MacBeth and dynamic-panel GMM (`pgmm`), `survey-r` for complex survey, `sf-terra` for spatial, `tidymodels` for ML; LIML, non-panel GMM-IV, SUR and 3SLS have no installed R package (escalate; plain 2SLS: `fixest`); VAR → escalate (no installed R VAR package; same Statistical modeling branch). Include the selected library in the task block. |
| Debug a script or diagnose an error | `debugger` | User provides script path + error description |
| Review code for correctness and methodology | `code-reviewer` | User provides script; orchestrator provides methodology context |
| Deep investigation of a data source | `source-researcher` | Standard multi-mode agent; already works in Data Lookup and Data Discovery |
| Compare multiple data sources | Parallel `source-researcher` + `research-synthesizer` | Dispatch source-researchers in parallel, then synthesize. For synthesis guidance, follow the Multi-Source Synthesis Protocol in `data-discovery-mode.md`. |
| Plan an analysis (advisory) | `data-planner` | Include `**MODE: Ad Hoc Collaboration**` in prompt to trigger advisory output (outline, not full Plan.md) |
| Critique or review a plan | `plan-checker` | Orchestrator must format the user's plan into a structured document in the prompt; plan-checker requires structured input |
| Quick data fetch or query | `research-executor` | With appropriate domain query skill |

**When uncertain:** Err toward responding directly first — where "responding directly" includes loading the routed skill before answering, not skipping it. If the question proves deeper than expected, dispatch to the appropriate agent. A lightweight direct answer followed by "Want me to dig deeper with a specialist?" is better than over-dispatching.

**R/Stata-background user detection:** If the user mentions an R / RStudio or Stata background, requests R/Stata-equivalent comments, or asks to understand Python code from an R or Stata perspective, the orchestrator should:
- For **conceptual questions** (the orchestrator answers directly): Load the appropriate translation skill via the Skill tool to bridge concepts. Select based on execution language and background: Python execution with R/Stata background → `r-python-translation`/`stata-python-translation`; R execution with Python/Stata background → `python-r-translation`/`stata-r-translation`.
- For **code-producing tasks** (dispatched to agents): Add the appropriate translation directive to the agent prompt (see orchestrator SKILL.md § User Language Preference Propagation for the full 4-way table). This applies to research-executor, code-reviewer, debugger, and data-ingest dispatches.

**Requests outside DAAF's capabilities:** If the user asks for something DAAF genuinely cannot/should not do (e.g., "access my university's database," "submit my draft to this journal"), explain the limitation clearly and suggest alternatives the user can pursue independently. Maintain the collaborative spirit -- frame it as "here's what I can't do and here's what might work instead" rather than a refusal.

**Sensitive or restricted data (synthetic-data protocol):** If, during ad hoc work, the user reveals that their data is sensitive, proprietary, PII-bearing, HIPAA/FERPA-governed, held in a secure enclave, or otherwise "can't be uploaded" / "can't leave my environment," do **not** ask them to paste or import the raw data. Instead, mention DAAF's privacy-preserving **synthetic-data protocol**: the user profiles their data locally with a disclosure-controlled script, shares only a summary profile report, and DAAF builds a synthetic stand-in to develop analysis code against (findings are then finalized against the real data where it lives). This runs through Data Onboarding's **sensitivity gate** — offer to escalate (see Escalation Triggers). For the doctrine and tier ladder, load the `synthetic-data-workflow` skill. If raw sensitive microdata has already been pasted into the conversation, stop, note it, and redirect to the sensitivity gate rather than continuing to work with it inline.

**Invocation template variability:** Unlike pipeline modes, Ad Hoc tasks are inherently variable and unpredictable. The Standard Agent Prompt Structure below is a skeleton, not a rigid template. The orchestrator should adapt the prompt content to fit each specific request, providing whatever context the agent needs to do its work well. When in doubt, err toward providing more context rather than less.

---

## Subagent Prompt Conventions

All subagent prompts in Ad Hoc Collaboration include:

```
**MODE: Ad Hoc Collaboration**
**BASE_DIR:** {absolute path to DAAF root}
**PROJECT_DIR:** {absolute path to ad hoc workspace}
```

The `**MODE: Ad Hoc Collaboration**` marker triggers mode-specific behavioral adjustments in agents that have an Ad Hoc Collaboration Mode section (research-executor, debugger, code-reviewer, data-planner).

For agents without a dedicated section (source-researcher, plan-checker, research-synthesizer), the orchestrator provides equivalent context directly in the prompt:

```
No Plan.md exists for this session. The user is working in Ad Hoc Collaboration
mode. Context for this task:

- Research question / user intent: [what the user described]
- Relevant background: [any context from the conversation]
```

### Standard Agent Prompt Structure

```
**MODE: Ad Hoc Collaboration**
**BASE_DIR:** /absolute/path/to/daaf
**PROJECT_DIR:** /absolute/path/to/research/YYYY-MM-DD_AdHoc_Topic

## Task

[Description of what needs to be done, drawn from user's request]

## Context

[User's description of intent, relevant conversation context,
 any files or data the user has referenced]

## Instructions

[Agent-specific instructions; reference the agent's Ad Hoc Collaboration
 Mode section for behavioral adjustments]

## Output Format

[Standard agent output format applies; findings will be relayed to user]
```

---

## Agent Output Handling

In pipeline modes, agent output is a concise signal to the orchestrator (2000-word cap, processed internally). In Ad Hoc Collaboration mode, agent findings are typically **the deliverable to the user**, so output handling changes:

**Output cap override:** When dispatching agents in Ad Hoc Collaboration mode, include this instruction in the prompt: "Output cap is relaxed to 3000 words. Your findings will be relayed directly to the user, so prioritize clarity and completeness over brevity." This applies to all agents dispatched in this mode. The standard 2000-word pipeline cap remains in effect for all other modes.

**Relay guidelines:**

- **Relay substantively:** The orchestrator relays agent findings to the user with brief contextual framing (e.g., "Here's what the code review found:"). Do not strip substantive content.
- **Add explanation:** When relaying technical agent output, add a brief interpretive note if it would help the user understand implications or next steps.
- **Point to workspace:** Remind the user that full details (diagnostic scripts, QA scripts, data files) are saved in the workspace folder.
- **Follow-up naturally:** After relaying findings, invite the user's reaction -- "Does that answer your question?" or "Want me to dig into any of these findings?"

---

## Working with User-Provided Files

Users in Ad Hoc Collaboration frequently reference their own files -- scripts they've written, data files they're working with, plans they've drafted. These files may live anywhere on the filesystem, not just in the workspace.

- **Read files wherever they are.** The orchestrator and agents have filesystem read access. Do not copy user files into the workspace unless there's a reason to (e.g., the debugger needs to modify a copy, or an agent needs to execute a user's script via `run_with_capture.sh`).
- **Read before planning.** When the user points to a file or document, read it before proposing what to do with it, and pass its path to any agent you dispatch (§ Scope Check).
- **Write outputs to the workspace.** Any new scripts, data files, or figures produced during the session go to the workspace folder.
- **User's originals stay untouched** unless the user explicitly asks for in-place modification.

---

## Session Notes and Continuity

Ad Hoc sessions can be wide-ranging and long-running. Unlike pipeline modes, there is no STATE.md. Instead, the orchestrator maintains a lightweight **SESSION_NOTES.md** in the workspace to provide continuity.

### When to Create SESSION_NOTES.md

Create `SESSION_NOTES.md` in the workspace root when the **first substantive milestone** occurs -- whichever comes first:

- A task plan or advisory outline is produced
- A key decision is made (e.g., "we'll use CCD instead of IPEDS for this")
- A deliverable is completed (script executed, code review returned, debugging resolved)
- Context utilization reaches ELEVATED (see CLAUDE.md § Context & Session Health > Context Quality Curve for the trigger points of each threshold profile)

If the session remains purely conversational with no milestones, SESSION_NOTES.md is not needed.

### What SESSION_NOTES.md Contains

```markdown
# Session Notes: {Topic}

**Started:** YYYY-MM-DD
**Workspace:** {PROJECT_DIR}

## Accomplishments

- [What was completed, with file paths where relevant]

## Key Decisions

- [Decisions made during the session, with rationale]

## In Progress

- [What the user was working on when the session ended or notes were last updated]

## Open Questions

- [Unresolved questions or next steps the user mentioned]

## AI Disclosure

This session used DAAF (Data Analyst Augmentation Framework) in Ad Hoc
Collaboration mode. DAAF contributed to: [list specific contributions --
code review, script writing, debugging, methodology advice, etc.].
The researcher directed all work and made all analytical decisions.
```

### When to Update SESSION_NOTES.md

Update after each of these events (not every turn -- only at milestones):

| Event | What to Update |
|-------|---------------|
| Plan or advisory outline produced | Accomplishments + Key Decisions |
| Key analytical decision made | Key Decisions |
| Deliverable completed (script executed, review done) | Accomplishments |
| User changes topic substantially | In Progress (update current focus) |
| Context reaches ELEVATED (see CLAUDE.md § Context & Session Health > Context Quality Curve for the trigger points of each threshold profile) | All sections (full checkpoint) |
| User signals session is ending | All sections (final summary) |
| Before any escalation to another mode | All sections + note the escalation |

### Context Recovery

At context thresholds (per CLAUDE.md > Context Quality Curve), the orchestrator should:

1. Update SESSION_NOTES.md with current state
2. Summarize what's been accomplished and what's in progress
3. Suggest the user start a fresh session
4. Point to SESSION_NOTES.md and the workspace folder as the continuity mechanism

When a user resumes an ad hoc session ("let's pick up where we left off on X"), the orchestrator reads SESSION_NOTES.md to reconstruct context: what was accomplished, what decisions were made, what was in progress, and what open questions remain.

---

## Dispatch and Context Management

- **Dispatch generously to subagents.** Each subagent gets a fresh context window. For tasks that involve code execution, deep research, or formal review, dispatching preserves orchestrator context for the ongoing conversation.
- **Limit orchestrator skill loading.** The orchestrator loads `data-scientist` at session start. Additional skills should generally be loaded by subagents. If the orchestrator has loaded more than 2-3 skills directly, prefer dispatching to subagents for subsequent tasks to avoid context pressure. This budget does not waive the load-before-advising norm: once the budget is exhausted, dispatch a subagent (which loads the routed skill in its own fresh context) rather than answering tool-specific questions from memory.
- **Parallel dispatch limit.** Parallel dispatches follow the default of at most 5 subagents in flight (`SKILL.md` § Subagent Coordination > "Parallel Dispatch Guideline"), more only with the user's explicit approval.
- **Wave barrier discipline (async dispatch).** See `SKILL.md` § Subagent Coordination > Wave Barrier Discipline (Async Dispatch) for how results arrive. The barrier applies however they arrive. When a single turn dispatches more than one agent — e.g., the parallel `source-researcher` + `research-synthesizer` pattern in the Dispatch Table — treat those mid-wave completion notifications as status-only: do not relay results to the user, synthesize, or take the next action until EVERY dispatched agent has returned. Synthesize once over the complete set (a failed or early-returning agent still counts as a completion). Narrating "one of two is back" is fine; acting on it is not.

---

## Output Format

Ad Hoc Collaboration has no mandatory output format. Outputs depend on what the user asked for:

| Request Type | Output |
|-------------|--------|
| Advice or brainstorming | Conversational response with structured reasoning |
| Package or tool guidance | Explanation with code examples |
| Code review | QA findings with specific recommendations |
| Debugging | Diagnosis report with root cause and fix |
| Analysis code | Executed script in workspace + results summary |
| Data source guidance | Source research report (five-section format) |
| Analysis planning | Advisory outline (not full Plan.md unless requested) |
| Data fetch | Script + data file in workspace + summary |

**Saved artifacts:** All scripts, data files, and figures produced during the session are saved in the workspace folder. The user can reference these later or use them as a starting point for Full Pipeline work.

**Turn-end briefing.** Ad Hoc has no checkpoints, so the discipline that keeps the user oriented is the turn-end briefing: whenever a turn returns control after substantive work — a script executed, a review returned, a debugging pass concluded — close by catching the user up on everything relevant since their last message, taken altogether, in plain language and pointed toward what it means and what to do next. That is the per-turn habit; the milestone SESSION_NOTES.md updates and the Session Wrap-Up summary below are the persisted, coarser-grained forms of the same instinct. See the master statement in `SKILL.md` § User-Facing Communication Standards > "Turn-End Briefing."

---

## Boundaries

These boundaries supplement the universal safety boundaries in `CLAUDE.md`. See also `agent_reference/BOUNDARIES.md` > Ad Hoc Collaboration Mode.

### Always Do

- Maintain file-first execution for all code produced by agents (`enforce-file-first` hook applies)
- Follow IAT documentation standards (`# INTENT:`, `# REASONING:`, `# ASSUMES:`) in any code produced
- Save all scripts and outputs to the workspace
- Relay agent findings to user with contextual framing
- Load `data-scientist` skill at session start
- Create workspace when first artifact-producing action is triggered
- Update SESSION_NOTES.md at milestones (plans, decisions, deliverables)

### Ask First Before

- Creating Plan.md or other formal pipeline artifacts
- Running queries that might return >100K records
- Scope expansion that would effectively constitute a Full Pipeline analysis
- Modifying user's original files in place (vs. copying to workspace)
- Installing packages or making environment changes (runtime installs are blocked; the path is a Dockerfile edit — recommend the user additions block near the end for a fast rebuild — see `agent_reference/BOUNDARIES.md`)

### Never Do

- Require Plan.md for agent dispatch
- Impose checkpoint gates or mandatory phase reviews (the soft Scope Check states a plan and proceeds; it does not wait for approval)
- Limit the conversation to a single topic
- Create STATE.md unless escalating to a pipeline mode
- Refuse a task because it doesn't fit a predefined category
- Execute Python or R interactively (file-first execution still applies for all code)
- Overwrite or modify user-provided files outside the workspace without explicit permission

---

## Escalation Triggers

| Condition | Target Mode | Action |
|-----------|-------------|--------|
| User requests formal deliverables (Plan + Notebook + Report) | Full Pipeline | Propose escalation; workspace artifacts carry forward |
| User wants systematic data exploration across multiple sources | Data Discovery | Propose escalation; ad hoc findings inform discovery |
| User has raw data file that needs profiling and a new skill | Data Onboarding | Propose escalation |
| User reveals their data is sensitive/PII/proprietary or can't leave their environment | Data Onboarding | Propose escalation to the **sensitivity gate** — DAAF's synthetic-data protocol keeps the real data out of the container (profile locally → share only a disclosure-controlled report → DAAF builds a synthetic stand-in; finalize findings against the real data). See the `synthetic-data-workflow` skill. |
| Session has naturally produced a research plan | Full Pipeline | Suggest: "This is shaping up to be a full analysis -- want me to formalize it?" |
| Debugging reveals an existing analysis needs revision | Revision and Extension | Propose escalation to modify the original project |
| A confirmed creative-verification finding should change the official analysis | Revision and Extension | Promote the confirmed change per `agent_reference/TRIANGULATION_PROTOCOL.md`; the official analysis is preserved until the user approves promotion |
| User wants to verify an existing analysis reproduces | Reproducibility Verification | Propose escalation |
| User wants a recorded review of the published research, with checked citations | Literature Review | Propose escalation; the conversation so far is the handoff (`literature-review-mode.md` § Escalation Triggers) |
| User wants to create or modify DAAF framework components (skills, agents, modes) | Framework Development | Propose escalation: "That's framework development work. Want me to switch to Framework Development mode?" |
| User's questions shift from hands-on work to understanding DAAF, its tools, or setup | User Support | Propose: "It sounds like you want to understand DAAF better first. Want me to switch to User Support mode?" |

All escalations require explicit user confirmation. Frame escalations as opportunities, not obligations -- the user may prefer to continue working ad hoc.

**De-escalation is also valid.** If a user started in a heavier mode and realizes they just want to talk through the approach, offer to switch to Ad Hoc Collaboration. This includes early-stage Full Pipeline sessions where the user decides they don't need formal deliverables after all, and a Literature Review whose user would rather discuss the papers than run review rounds; that review's STATE.md shows what it has already recorded. Take any fact about the literature only from the files `agent_reference/LIT_REVIEW_OUTPUT_CONTRACT.md` § Files Consumers May Read lists, never from the papers: a fact is a `verified` or `verified_partial` row of `claims`. When the user asks for a fact the review has not recorded, say so and offer to return to Literature Review for another round (an escalation the user confirms).

---

## Session Wrap-Up

There is no mandatory wrap-up protocol. The session ends when the user is done. However, if the session produced artifacts:

1. Run the Scratch Graduation Check (`agent_reference/SCRIPT_EXECUTION_REFERENCE.md` § Scratch Graduation Check): any scratch file that the notes or results cite moves to its named home first
2. Collect session logs into the project workspace:
   ```bash
   bash {BASE_DIR}/scripts/collect_session_logs.sh {PROJECT_DIR}
   ```
3. Update SESSION_NOTES.md with a final summary
4. Offer a brief summary to the user, naming any files graduated out of scratch:

> "Here's what we produced today in `research/YYYY-MM-DD_AdHoc_{Topic}/`:
> - [List of scripts, data files, figures]
> - [Key findings or decisions made]
>
> Session notes are saved in `SESSION_NOTES.md` if you want to come back to it. I've also copied in the session logs in the project logs folder.
>
> To browse the session timeline interactively, run in the Docker terminal:
> `bash /daaf/scripts/generate_log_viewer.sh {PROJECT_DIR}`"

This is a courtesy, not a gate. If the user just says "thanks" and leaves, that's fine.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall