brain-hydrate

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.

<contract> <requires>

• Brain configured via /brain-setup: .claude/brain-config.json (or personal equivalent) present with valid database_url, openrouter_api_key, and scope.
• Brain reachable: atelier_stats returns successfully and brain_enabled: true.
• Brain MCP tool schemas pre-loaded via ToolSearch (Phase 1 Step 0) before any atelier_* / agent_* call.
• Pipeline installed: scout agent persona present in .claude/agents/ (required for the Phase 2a fan-out).
• At least one extractable source on disk: ADRs, feature specs, UX docs, error-patterns.md, context-brief.md, or git history.

</requires> <produces>

• Brain thoughts captured via agent_capture (types: decision, rejection, preference, lesson, correction, insight) — no per-run cap.
• Brain relations created via atelier_relation (evolves_from, triggered_by, supports, contradicts).
• Phase 3 progress and final-summary report on the main thread (counts per source type, breakdown, top themes).

</produces> <invalidates /> </contract>

<gate id="extraction-principles">

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.

</gate>

<procedure id="scan-inventory">

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.
2. Not reachable: "Brain is not running. Run /brain-setup first."
3. brain_enabled: false: "Brain is disabled. Enable it with PUT /api/config { brain_enabled: true } or run /brain-setup."

1. 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.

</procedure>

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).

<section id="progress-summary">

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.

</section>

<protocol id="incremental-rehydration">

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):
3. Match found (>0.85 similarity): Skip — this knowledge is already in the brain. Log: "Skipped (already captured): [summary]"
4. Partial match (0.7-0.85): Capture as a new thought and create an evolves_from relation to the existing thought.
5. No match (<0.7): Capture normally.
6. 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.

</protocol>

<section id="scope-controls">

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 |

</section>

<gate id="hydration-guardrails">

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