---
name: brain-hydrate
description: Use when users want to bootstrap the brain with existing project knowledge -- reading ADRs, feature specs, UX docs, commit history, and error patterns to seed institutional memory on a project that already has artifacts on disk. Also use for incremental re-hydration after significant work outside the pipeline. Triggers on "hydrate brain", "bootstrap brain", "seed memory", "brain init", "populate brain", "import history".
---
# Atelier Brain -- Hydrate
This skill reads existing project artifacts and git history, extracts reasoning and decisions, and captures them as brain thoughts with proper types, importance scores, and relations. Run this conversationally -- present the scan results, get approval, then execute.
---
## Phase 1: Scan & Inventory
Before extracting anything, scan the project and present an inventory.
### Step 1: Verify Brain is Live
1. Call `atelier_stats` to confirm the brain is reachable and `brain_enabled: true`.
- **Not reachable:** "Brain is not running. Run `/brain-setup` first."
- **brain_enabled: false:** "Brain is disabled. Enable it with `PUT /api/config { brain_enabled: true }` or run `/brain-setup`."
2. Check current thought count. If thoughts already exist, warn:
> "Brain already has [N] thoughts. This hydration will ADD to existing knowledge, not replace it. Duplicate detection will prevent exact re-imports. Proceed?"
### Step 2: Scan Artifacts
Scan the project for extractable sources. Use Glob and Bash to inventory:
| Source | How to find | What to count |
|--------|------------|---------------|
| ADRs | `ls docs/adrs/*.md` or `ls docs/architecture/*.md` | Number of ADR files |
| Feature specs | `ls docs/product/*.md` | Number of spec files |
| UX docs | `ls docs/ux/*.md` | Number of UX files |
| Error patterns | `cat docs/pipeline/error-patterns.md` | Number of entries |
| Context briefs | `cat docs/pipeline/context-brief.md` | Exists or not |
| Git history | `git log --oneline --since="6 months ago"` (or full history if <500 commits) | Number of significant commits |
### Step 3: Present Inventory
Present the scan results to the user:
```
Brain Hydration Scan
====================
ADRs: [N] files in docs/adrs/
Feature specs: [N] files in docs/product/
UX docs: [N] files in docs/ux/
Error patterns: [N] entries
Context brief: [exists/none]
Git commits: [N] commits (last 6 months)
Estimated thoughts: [low]-[high]
Estimated relations: [low]-[high]
Ready to hydrate?
```
The user may exclude sources ("skip git history", "only ADRs") or adjust the time window. Respect their scope.
---
## Phase 2a: Scout Fan-Out
After the user approves the scan inventory, Eva fans out scout subagents in parallel. Each scout reads one category of artifact files and returns raw content in a named inline block. This keeps all file reading off the main thread and off Opus.
**Invocation pattern:** `Agent(subagent_type: "scout")`. Facts only -- no extraction, no opinions. Each scout returns raw file content with clear delimiters per file.
**Dedup rule:** Each file is read by exactly one scout. No file appears in more than one scout's file set.
### Scout Categories
| Scout | Files | Block element |
|-------|-------|---------------|
| **ADR scout** | `docs/architecture/ADR-*.md` or `docs/adrs/ADR-*.md` | `` |
| **Specs scout** | `docs/product/*.md` | `` |
| **UX scout** | `docs/ux/*.md` | `` |
| **Pipeline scout** | `error-patterns.md` + `context-brief.md` | `` |
| **Git scout** | `git log` output -- filter for significant commits only; if no significant commits found, returns empty | `` |
### Scout Content Format
Each scout returns content using file delimiters:
```
=== FILE: docs/architecture/ADR-0002-team-collaboration.md ===
[full file content]
=== END FILE ===
=== FILE: docs/architecture/ADR-0005-xml-prompt-structure.md ===
[full file content]
=== END FILE ===
```
The Sonnet subagent parses these delimiters to process each file individually against the extraction rules.
### Skip Conditions
- **User excluded source type:** If the user narrowed scope (e.g., "only ADRs"), only the ADR scout fires. All other scouts are skipped.
- **Zero files in category:** If the Phase 1 scan found zero files for a category (e.g., no UX docs), that scout is skipped entirely. The Sonnet subagent skips that source type gracefully.
- **Scope-based exclusion:** If the user explicitly says "skip git history", the Git scout does not fire.
### File-Count Gate
If a single scout would read **more than 20 files**, split into multiple sub-scouts with **disjoint** (non-overlapping) file sets. Each file is assigned to exactly one sub-scout.
Example: 25 ADRs → ADR scout A (13 files) + ADR scout B (12 files). Split as evenly as possible; if the count is odd, the first sub-scout gets the larger half. Eva determines the split at fan-out time using Phase 1 inventory counts. The Sonnet subagent receives all sub-scout outputs concatenated in the same `` element.
### Dry-Run Mode (Phase 2a)
In dry-run mode, scouts still fire normally so the user can preview what content would be extracted. Scout results are collected but not passed to a capture subagent.
### Scout Failure Handling
If a scout fails (timeout or error), Eva reports which category failed to the user. **No automatic re-invocation.** The user decides whether to proceed with partial content or abort. Consistent with retro lesson #004: hang-and-timeout failures are diagnostic information, not a trigger for re-invocation.
### Completeness Check (Gate Before Extraction)
Before invoking the Sonnet subagent, Eva verifies scout output completeness: the file count returned by each scout must match the Phase 1 inventory count for that category. If a mismatch is found, Eva reports the gap to the user before proceeding. Skipped scouts (per skip conditions above -- zero-file categories, user-excluded sources, or scope-based exclusions) are excluded from this check and do not count as mismatches.
---
---
## Phase 3: Progress & Summary
The Sonnet subagent produces a progress report per source type. Eva reads this output and presents the summary on the main thread.
### During Extraction
The Sonnet subagent reports progress after each source type:
```
[ADRs] Captured 12 decisions, 5 rejections, 3 insights. Created 4 relations.
[Specs] Captured 8 decisions, 3 preferences. Created 6 cross-references to ADR thoughts.
[UX] Captured 4 decisions, 2 preferences.
[Error patterns] Captured 7 lessons.
[Git history] Scanned 187 commits, captured 11 significant insights/lessons.
```
### Final Summary
After all sources are processed, call `atelier_stats` and present:
```
Brain Hydration Complete
========================
Thoughts captured: [N] (was [M] before hydration)
Relations created: [R]
Breakdown:
decisions: [n]
rejections: [n]
preferences: [n]
lessons: [n]
corrections: [n]
insights: [n]
Top themes (by thought density):
1. [theme] — [count] thoughts
2. [theme] — [count] thoughts
3. [theme] — [count] thoughts
The brain now has institutional memory of your project's
decisions, rejected alternatives, lessons learned, and
user preferences. Agents will surface this context
automatically during pipeline runs.
```
---
## Incremental Re-Hydration
If the user runs `/brain-hydrate` on a project that was previously hydrated:
1. The scan phase is identical.
2. The Sonnet subagent performs dedup before each capture by calling `agent_search` with the candidate thought text (threshold 0.85):
- **Match found (>0.85 similarity):** Skip — this knowledge is already in the brain. Log: "Skipped (already captured): [summary]"
- **Partial match (0.7-0.85):** Capture as a new thought and create an `evolves_from` relation to the existing thought.
- **No match (<0.7):** Capture normally.
3. The Sonnet subagent reports skip count in its progress output: "Skipped [N] thoughts already in brain."
If all candidates are already captured, the Sonnet subagent completes normally with captured=0 and reports the full skip count. Eva presents this in the Phase 3 summary.
This makes re-hydration safe to run multiple times. The brain's write-time conflict detection provides a second safety net.
---
## Scope Controls
The user can narrow scope at any point:
| User says | Behavior |
|-----------|----------|
| "only ADRs" | Skip all other sources |
| "skip git history" | Process artifacts only |
| "since January" | Adjust git log window |
| "just docs/product/feature-x.md" | Single-file extraction |
| "dry run" | Scan and show what WOULD be captured, but don't write |
---
## Guardrails
These rules are mandatory:
1. **Never capture artifact content verbatim.** The thought must be a synthesized reasoning statement, not a copy-paste. If you find yourself capturing more than 2 sentences from a single source paragraph, you're copying, not synthesizing.
2. **Never capture code.** No function signatures, no SQL schemas, no config snippets. The brain stores reasoning about code decisions, not the code itself.
3. **Never overwrite existing thoughts.** Hydration is additive. If the brain already has thoughts, hydration adds to them. It never deletes or modifies existing thoughts.
4. **Respect the write-time conflict detection.** If `agent_capture` returns a conflict warning (duplicate or candidate), log it and move on. Do not force-write.
5. **Cap single-run extraction.** Maximum 100 thoughts per hydration run. If the scan estimates more, batch: "Found ~150 extractable thoughts. I'll capture the first 100 (highest importance). Run again for the remainder."
6. **Always verify at the end.** Call `atelier_stats` after hydration to confirm thought count increased as expected.
---
## Important Notes
- **This skill is conversational.** Present the scan, get approval, then execute. Do not auto-run extraction without user confirmation.
- **First hydration on a new project is the primary use case.** Incremental re-hydration is the secondary use case for catching up after work done outside the pipeline.
- **Quality over quantity.** 30 high-signal thoughts are worth more than 200 noisy ones. When in doubt, skip the extraction — the brain should be a curated reasoning ledger, not a dump.
- **The user can abort at any time.** Thoughts already captured remain (they're individually valid). The brain is append-only — partial hydration is fine.
### Model Assignment
| Component | Model | Rationale |
|-----------|-------|-----------|
| Phase 1 (scan) | Opus (main thread) | Lightweight, conversational -- just Glob, shell inventory, stats |
| Phase 2a (scouts) | Haiku (scout subagent) | File reading only, no reasoning needed |
| Phase 2b (extraction) | Sonnet (subagent) | Synthesis quality sufficient for structured extraction rules |
| Phase 3 (summary) | Opus (main thread) | Format and present results |
Scouts are invoked as `Agent(subagent_type: "scout")` with no `model` parameter — model pinning is owned by the scout frontmatter. The capture subagent uses `model: "sonnet"` via `Agent(model: "sonnet")`.