feat(build-spec): Phase 2 — session-brain auto-write + insight extraction spec
This commit is contained in:
Kisa
parent
4625585146
commit
1183d83f1a
2 changed files with 223 additions and 4 deletions
|
|
@ -1,7 +1,7 @@
|
|||
# current-state
|
||||
|
||||
ACTIVE: Build Spec Phase 1 COMPLETE (Claude Code) + Phase 3 shared-context pointers wired. STTIL Shield + AI Consent Addendum architecture still with Pi.
|
||||
NEXT: Pi to direct next build phase (Phase 2 session-brain auto-write, or Phase 4 support bot). TriLane research_insight category is live.
|
||||
ACTIVE: Build Spec Phase 2 DESIGNED — session-brain auto-write + insight extraction spec ready for Claude Code.
|
||||
NEXT: Claude Code builds Phase 2 (modify navaigate-session-brain SKILL.md). Pi stands by for verification.
|
||||
|
||||
## Decisions (last 5)
|
||||
|
||||
|
|
@ -14,7 +14,7 @@ NEXT: Pi to direct next build phase (Phase 2 session-brain auto-write, or Phase
|
|||
## Open Threads (max 5)
|
||||
|
||||
- LabABLE Meeting Fri 2026-06-26 1:30 PM — run /pilot-prep.
|
||||
- Build Spec Phase 2: session-brain auto-writes current-state.md + insight extraction (Pi to design).
|
||||
- Build Spec Phase 2: spec written at signal/docs/superpowers/specs/2026-06-22-build-spec-phase2.md. Ready for Claude Code to build.
|
||||
- 3 validation product blockers: MA misclassification, duplicate patient_id, doc-status override (Claude Code is on these).
|
||||
- Primary domain sttilsolutions.com still "Pending" in Clerk (separate from Frontend API — non-blocking for auth).
|
||||
|
||||
|
|
@ -32,4 +32,4 @@ NEXT: Pi to direct next build phase (Phase 2 session-brain auto-write, or Phase
|
|||
|
||||
TriLane Memory now has the `research_insight` category live + 1 planted insight (CGM-to-pharmacy, salience 1.0) in the Signal workspace. Session summaries no longer leak into the Signal workspace; they live in the Sessions workspace.
|
||||
|
||||
## Updated: 2026-06-22 (Pi: Clerk prod migration complete, Firecrawl persisted, Build Spec Phase 2 next)
|
||||
## Updated: 2026-06-22 (Pi: Clerk migration done, Phase 2 spec written, ready for Claude Code build)
|
||||
|
|
|
|||
219
docs/superpowers/specs/2026-06-22-build-spec-phase2.md
Normal file
219
docs/superpowers/specs/2026-06-22-build-spec-phase2.md
Normal file
|
|
@ -0,0 +1,219 @@
|
|||
# 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
|
||||
```
|
||||
Loading…
Reference in a new issue