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.

Core Principle

Extract the WHY, never the WHAT. Artifacts on disk are the source of truth for current state. Git is the source of truth for what changed and when. The brain captures reasoning, rejected alternatives, evolution context, and lessons -- the knowledge layer that no file or commit preserves.

Never duplicate artifact content. A decision thought references the ADR it came from but does not restate the ADR. A lesson thought captures the insight, not the code that was fixed.

Phase 1: Scan & Inventory

Before extracting anything, scan the project and present an inventory.

Step 0: Pre-load Brain MCP Tool Schemas

Brain MCP tool schemas are deferred — the first call to any atelier_* or agent_* tool without its schema loaded fails with InputValidationError. Run ToolSearch once before any brain call to load the schemas up front:

ToolSearch query: select:mcp__plugin_atelier-pipeline_atelier-brain__atelier_stats,mcp__plugin_atelier-pipeline_atelier-brain__agent_capture,mcp__plugin_atelier-pipeline_atelier-brain__agent_search,mcp__plugin_atelier-pipeline_atelier-brain__atelier_relation,mcp__plugin_atelier-pipeline_atelier-brain__atelier_browse,mcp__plugin_atelier-pipeline_atelier-brain__atelier_trace

Proceed to Step 1 only after ToolSearch returns.

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:

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.

See scout-fanout.md for the Phase 2a scout fan-out protocol: invocation pattern, scout categories, content format, invocation template, skip conditions, file-count gate, dry-run mode, failure handling, and completeness check.

See extraction.md for the Phase 2b Extract & Capture protocol: Sonnet subagent invocation, failure handling, and extraction rules for each source type (ADRs, feature specs, UX docs, error patterns, context brief, and git history).

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:

Guardrails

These rules are mandatory:

1. Never capture artifact content verbatim. The thought must be a synthesized reasoning statement, not a copy-paste. If yo