Signal/docs/superpowers/specs/2026-06-22-build-spec-phase2.md

# Build Spec Phase 2 — Session Brain Auto-Write + Insight Extraction

**Date:** 2026-06-22
**Design:** Pi
**Build:** Claude Code
**Est:** 1 session
**Depends on:** Phase 1 foundation complete (research_insight category live, shared-context pointers wired)

---

## Overview

Phase 2 closes the feedback loop between Pi and Claude Code by making the session brain automatically update the shared context file and extract research insights. Currently, `current-state.md` and insight planting are manual steps that Pi does ad hoc. This phase makes them an automatic part of every session-brain run.

Two substeps to add to `navaigate-session-brain/SKILL.md`:

- **Step 3B** — Write shared context file (`current-state.md`)
- **Step 3C** — Extract research insights to TriLane Memory

---

## 2.1 Add current-state.md write to session brain

### File to change

`~/.claude/skills/navaigate-session-brain/SKILL.md`

### What to add

Insert after Step 3 (Write Session Summary) and before Step 4 (Push to NotebookLM Brain):

```
## Step 3B — Update Shared Context File (current-state.md)

After the session summary is written, update the bridge file that Pi and Claude Code
both read at session start.

**File:** `signal/context/current-state.md`

**Rules:**
- Read the existing `signal/context/current-state.md` first
- Update sections based on this session, don't overwrite the whole file
- Only change what actually changed this session

**ACTIVE:**
Set to the primary accomplishment of this session. One line.
Format: `ACTIVE: <what was accomplished>`

**NEXT:**
Set to the next priority. One line.
Format: `NEXT: <what to do next>`

**Decisions (last 5, FIFO):**
- Prepend new decisions
- Remove oldest if more than 5 entries
- Format: `- YYYY-MM-DD: <decision summary>`

**Open Threads (max 5):**
- Add any new open threads from this session
- Close any threads that were resolved
- Keep max 5 — remove oldest/lowest priority
- Format: `- <thread description>`

**Stack:**
- Update the timestamp line at the end
- Only change other stack items if they actually changed this session

**Updated:**
- Set to current date with a summary of what Pi/Claude Code did
- Format: `YYYY-MM-DD (<who>: <what they did>)`

**Verification:**

```bash
head -50 signal/context/current-state.md
```

Should show the updated sections with this session's information.

```

### Acceptance

- [ ] After the next session brain run, `current-state.md` shows the session's ACTIVE, NEXT, decisions, and open threads
- [ ] Oldest decision drops off when 6+ exist
- [ ] Open threads capped at 5

---

## 2.2 Add insight extraction to session brain

### File to change

`~/.claude/skills/navaigate-session-brain/SKILL.md`

### What to add

Insert after Step 3B (above) and before Step 4 (Push to NotebookLM Brain):

```

## Step 3C — Extract Research Insights to TriLane Memory

After the shared context file is updated, check if this session produced a cross-document
synthesis or non-obvious insight worth persisting for long-term retrieval.

**Rules:**

- Only POST if the session produced a real insight (cross-document synthesis, new pattern
  discovery, non-obvious finding)
- Routine build work (bug fixes, deployments, config changes) does NOT produce insights
- Salience: 1.0 (permanent — these are planted for long-term retrieval)
- Content: exactly one paragraph (2-5 sentences)
- Tags: at least 2, at most 5, from the standard set: `cgm`, `pharmacy`, `payer_trend`,
  `policy`, `strategic`, `technical`, `product`, `competitor`, `regulatory`, `ux`, `security`,
  `infrastructure`, `business`, `compliance`

**TriLane API endpoint:**

```
POST localhost:8000/api/memory/16ee4620-4c81-48f9-bcd6-6c0a8fbbd71a
Content-Type: application/json
```

**Payload schema:**

```json
{
  "category": "research_insight",
  "content": "<one-paragraph insight>",
  "salience": 1.0,
  "tags": ["tag1", "tag2"]
}
```

**If no new insight:** Skip this step entirely. Do not POST an empty or placeholder item.

**Verification:**

```bash
curl localhost:8000/api/memory/16ee4620-4c81-48f9-bcd6-6c0a8fbbd71a | python3 -c "
import json,sys; items=json.load(sys.stdin);
insights=[i for i in items if i.get('category')=='research_insight'];
print(f'{len(insights)} research insights in Signal workspace')
for i in insights[-2:]:
    print(f'  - {i[\"content\"][:80]}... (tagged: {i.get(\"tags\",[])})')
"
```

If this session planted an insight, it should appear in the output.

### Acceptance

- [ ] Insights are only posted for sessions that produce cross-document synthesis
- [ ] Routine sessions skip this step
- [ ] API payload matches the schema exactly
- [ ] TriLane Memory returns 201 on success

---

## 2.3 Wire the new steps into the session brain flow

### File to change

`~/.claude/skills/navaigate-session-brain/SKILL.md`

### What to change

Update Step 6 (Confirm) to include acknowledgment of shared context update:

```
Current "Tell the user" section:
- How many memories were saved/updated
- That the session summary was added to the Brain notebook
- Any pending git commits flagged
- The suggested next steps

Add:
- Whether current-state.md was updated (yes/no)
```

### Verification

```
grep -A2 "current-state" ~/.claude/skills/navaigate-session-brain/SKILL.md
```

Should show the confirmation mention.

---

## Implementation Order

1. Modify `~/.claude/skills/navaigate-session-brain/SKILL.md`:
   - Add Step 3B (current-state.md write)
   - Add Step 3C (insight extraction)
   - Update Step 6 confirmation message
2. Commit the skill change to the signal repo (or user's dotfiles)
3. Run a manual test by executing the navaigate-session-brain skill once
4. Verify current-state.md and TriLane Memory

## Completion Report Template

```markdown
### Phase 2 (Session Brain)

#### 2.1 current-state.md write
- [ ] Step 3B added to navaigate-session-brain/SKILL.md
- [ ] ACTIVE/NEXT/Decisions/Open Threads all wired
- [ ] FIFO capped at 5 decisions and 5 threads

#### 2.2 Insight extraction
- [ ] Step 3C added to navaigate-session-brain/SKILL.md
- [ ] Insight check rule (skip routine sessions)
- [ ] TriLane POST wired with correct payload

#### 2.3 Step 6 confirmation
- [ ] current-state.md update acknowledged in final message
```