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:

{
  "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:

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

### 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