docs: merge codex insights into claude super plan
Adds key architectural choices summary, assumptions section, sidebar visual demotion (F9), message click-to-expand in compact log, and backend-first rationale from the codex plan. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
chihlasm
@@ -11,6 +11,17 @@ Reframe `/assistant` from a generic AI chat surface into a **live MSP triage coc
|
||||
|
||||
The change is a UI and data layer reframe. The existing session, branching, PSA, and conclude architecture is preserved and extended, not rebuilt.
|
||||
|
||||
### Key Architectural Choices
|
||||
|
||||
This plan explicitly chooses:
|
||||
|
||||
- **`FlowPilot`** as the primary page/product label (not "Assistant Harness")
|
||||
- **Backend triage + handoff contracts required in v1** — not deferred to a later phase
|
||||
- **Desktop-first cockpit layout** with clean mobile degradation
|
||||
- **Explicit persisted triage fields** on the session model, not purely derived/computed header state
|
||||
- **Prompt-embedded structured extraction** (`[TRIAGE_UPDATE]` marker) as the primary AI triage path, with post-response model pass only as fallback
|
||||
- **Sidebar visual demotion** — existing sidebar stays but is visually de-emphasized so the cockpit reads as an operations surface, not a chat app
|
||||
|
||||
---
|
||||
|
||||
## What Phase 0 Resolved
|
||||
@@ -272,7 +283,7 @@ Thin handle bar between work zone and conversation log. On drag: update `workZon
|
||||
|
||||
### F7 — Compact `ConversationLog` rendering
|
||||
|
||||
Replace current full `<ChatMessage>` bubbles in the log zone with a compact list: `you: ...` / `fp: ...` prefix style, tighter line height, no avatars. `ChatMessage` can still be used for rich content (forks, suggested flows) in a compact variant.
|
||||
Replace current full `<ChatMessage>` bubbles in the log zone with a compact list: `you: ...` / `fp: ...` prefix style, tighter line height, no avatars. `ChatMessage` can still be used for rich content (forks, suggested flows) in a compact variant. Individual messages should support click-to-expand for full rendering when the engineer needs to re-read a longer response or review a suggested flow.
|
||||
|
||||
### F8 — Redesigned `ConcludeSessionModal.tsx`
|
||||
|
||||
@@ -283,7 +294,16 @@ On open:
|
||||
4. Render output destination checkboxes: Post to CW note / Save to KB / Send client summary
|
||||
5. Confirm → call resolve/escalate/pause with enriched request body including structured fields
|
||||
|
||||
### F9 — MSP-native language pass
|
||||
### F9 — Sidebar visual demotion
|
||||
|
||||
The existing `ChatSidebar` stays functionally unchanged but should be visually softened so the cockpit — not the session list — reads as the primary surface. Specific changes:
|
||||
|
||||
- Reduce sidebar background contrast (use `bg-sidebar` or one step darker)
|
||||
- Reduce sidebar header prominence (smaller label, no bold "Chat History" heading)
|
||||
- Rename "Chat History" → "Case History" (part of language pass)
|
||||
- Default sidebar to collapsed state on first cockpit load (existing collapse toggle + `localStorage`)
|
||||
|
||||
### F10 — MSP-native language pass
|
||||
|
||||
| Old | New |
|
||||
|-----|-----|
|
||||
@@ -295,14 +315,14 @@ On open:
|
||||
| "Chat history" (sidebar label) | "Case History" |
|
||||
| Compose placeholder | "Describe finding, paste log output, or ask FlowPilot..." |
|
||||
|
||||
### F10 — New API methods (`aiSessions.ts`)
|
||||
### F11 — New API methods (`aiSessions.ts`)
|
||||
|
||||
```typescript
|
||||
updateTriage(sessionId: string, fields: Partial<TriageMeta>): Promise<TriageMeta>
|
||||
getHandoffDraft(sessionId: string): AsyncGenerator<HandoffDraftChunk>
|
||||
```
|
||||
|
||||
### F11 — New types (`types/ai-session.ts`)
|
||||
### F12 — New types (`types/ai-session.ts`)
|
||||
|
||||
```typescript
|
||||
interface TriageMeta {
|
||||
@@ -333,6 +353,9 @@ interface QuestionItem {
|
||||
## Phased Execution Order
|
||||
|
||||
### Phase 1 — Backend Foundation
|
||||
|
||||
> Lock backend schema and API changes first so the cockpit can be built against stable session contracts.
|
||||
|
||||
1. Write migration `071` — add 5 columns to `ai_sessions`
|
||||
2. Run `alembic upgrade head`, verify columns
|
||||
3. Update `AISession` model with new mapped columns
|
||||
@@ -368,18 +391,19 @@ interface QuestionItem {
|
||||
25. Implement drag-resizable split with `localStorage` persistence
|
||||
26. Compact `ConversationLog` rendering
|
||||
|
||||
### Phase 6 — Handoff Modal + Language Pass
|
||||
### Phase 6 — Handoff Modal + Language Pass + Sidebar
|
||||
27. Redesign `ConcludeSessionModal.tsx` — structured handoff form
|
||||
28. MSP-native language pass across all assistant components
|
||||
29. Update `<PageMeta>` title
|
||||
28. Sidebar visual demotion — background, label prominence, default-collapsed
|
||||
29. MSP-native language pass across all assistant components
|
||||
30. Update `<PageMeta>` title
|
||||
|
||||
### Phase 7 — QA + Hardening
|
||||
30. `npx tsc -b` — fix any TypeScript errors
|
||||
31. `npm run build` — production build clean
|
||||
32. Functional regression: all chat flows, session switching, conclude/resume
|
||||
33. Harness feel test: cockpit within 3 seconds?
|
||||
34. Mobile viewport check
|
||||
35. Stress test: 50+ messages, 10+ steps, long outputs
|
||||
31. `npx tsc -b` — fix any TypeScript errors
|
||||
32. `npm run build` — production build clean
|
||||
33. Functional regression: all chat flows, session switching, conclude/resume
|
||||
34. Harness feel test: cockpit within 3 seconds?
|
||||
35. Mobile viewport check
|
||||
36. Stress test: 50+ messages, 10+ steps, long outputs
|
||||
|
||||
---
|
||||
|
||||
@@ -450,6 +474,18 @@ curl -X POST http://localhost:8000/ai-sessions/{id}/handoff-draft \
|
||||
|
||||
---
|
||||
|
||||
## Assumptions
|
||||
|
||||
- Desktop is the primary target; mobile must remain usable but does not drive the layout.
|
||||
- `/assistant` remains the chat-session cockpit; `/pilot` is out of scope.
|
||||
- New triage fields are **additive** — they do not replace `problem_summary`, `problem_domain`, `ticket_data`, or `conversation_messages`.
|
||||
- `issue_category` is the operator-facing display field; `problem_domain` remains the internal classifier. Both coexist.
|
||||
- `evidence_items` is editable by both AI and engineer; engineer edits persist through the triage PATCH endpoint.
|
||||
- PSA context is optional — every triage header field must degrade gracefully when PSA is absent or session is free-text-only.
|
||||
- The existing `TaskLane.tsx` component remains in the codebase — `StepsPanel` is a new component that consumes the same props with different rendering. No risky renames during this work.
|
||||
|
||||
---
|
||||
|
||||
## Critical Files
|
||||
|
||||
| File | Change |
|
||||
|
||||
Reference in New Issue
Block a user