brain-hydrate

Files (3)

• SKILL.md
• extraction.md
• scout-fanout.md

SKILL.md (first lines)

# 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`.
   - **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.

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

From UberUmbra/atelier-pipeline, Apache-2.0.

More from UberUmbra/atelier-pipeline