From 763871a2a52eaa678cd9291ec1f47efaa964e159 Mon Sep 17 00:00:00 2001
From: Lukas May <lukas.may@carealytix.com>
Date: Thu, 5 Mar 2026 16:58:12 +0100
Subject: [PATCH] =?UTF-8?q?fix:=20Refine=20flow=20=E2=80=94=20optimistic?=
 =?UTF-8?q?=20UI=20update=20+=20instruction=20passthrough?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add getActiveRefineAgent to spawn mutation optimistic updates and
  live event invalidation rules so the refine panel reflects agent
  state immediately without manual refresh
- Accept optional instruction param in buildRefinePrompt() and inject
  it as <user_instruction> block so the agent knows what to focus on
- Pass input.instruction through in architect router spawn call
---
 apps/server/agent/prompts/refine.ts     |  7 +++++--
 apps/server/trpc/routers/architect.ts   |  2 +-
 apps/web/src/hooks/useRefineAgent.ts    | 13 ++++++++++---
 apps/web/src/routes/initiatives/$id.tsx |  2 +-
 4 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/apps/server/agent/prompts/refine.ts b/apps/server/agent/prompts/refine.ts
index a9de91d..843a66c 100644
--- a/apps/server/agent/prompts/refine.ts
+++ b/apps/server/agent/prompts/refine.ts
@@ -4,7 +4,10 @@
 
 import { CODEBASE_EXPLORATION, INPUT_FILES, SIGNAL_FORMAT } from './shared.js';
 
-export function buildRefinePrompt(): string {
+export function buildRefinePrompt(instruction?: string): string {
+  const instructionBlock = instruction
+    ? `\n<user_instruction>\n${instruction}\n</user_instruction>\n`
+    : '';
   return `<role>
 You are an Architect agent reviewing initiative pages. You do NOT write code.
 </role>
@@ -17,7 +20,7 @@ Write one file per modified page to \`.cw/output/pages/{pageId}.md\`:
 - Frontmatter: \`title\`, \`summary\` (what changed and why)
 - Body: Full replacement markdown content for the page
 </output_format>
-
+${instructionBlock}
 <improvement_priorities>
 1. **Ambiguity**: Requirements interpretable multiple ways → make specific
 2. **Missing details**: Gaps forcing agents to guess → fill with concrete decisions
diff --git a/apps/server/trpc/routers/architect.ts b/apps/server/trpc/routers/architect.ts
index 0ce23a5..24bc3e9 100644
--- a/apps/server/trpc/routers/architect.ts
+++ b/apps/server/trpc/routers/architect.ts
@@ -265,7 +265,7 @@ export function architectProcedures(publicProcedure: ProcedureBuilder) {
           status: 'in_progress',
         });
 
-        const prompt = buildRefinePrompt();
+        const prompt = buildRefinePrompt(input.instruction);
 
         return agentManager.spawn({
           name: input.name,
diff --git a/apps/web/src/hooks/useRefineAgent.ts b/apps/web/src/hooks/useRefineAgent.ts
index 9310c0c..75c4606 100644
--- a/apps/web/src/hooks/useRefineAgent.ts
+++ b/apps/web/src/hooks/useRefineAgent.ts
@@ -110,9 +110,11 @@ export function useRefineAgent(initiativeId: string): UseRefineAgentResult {
     onMutate: async ({ initiativeId, instruction }) => {
       // Cancel outgoing refetches
       await utils.listAgents.cancel();
+      await utils.getActiveRefineAgent.cancel({ initiativeId });
 
-      // Snapshot previous value
+      // Snapshot previous values
       const previousAgents = utils.listAgents.getData();
+      const previousRefineAgent = utils.getActiveRefineAgent.getData({ initiativeId });
 
       // Optimistically add a temporary agent
       const tempAgent = {
@@ -133,20 +135,25 @@ export function useRefineAgent(initiativeId: string): UseRefineAgentResult {
       };
 
       utils.listAgents.setData(undefined, (old = []) => [tempAgent, ...old]);
+      utils.getActiveRefineAgent.setData({ initiativeId }, tempAgent as any);
 
-      return { previousAgents };
+      return { previousAgents, previousRefineAgent };
     },
     onSuccess: () => {
       // Agent will appear in the list after invalidation
     },
     onError: (err, variables, context) => {
-      // Revert optimistic update
+      // Revert optimistic updates
       if (context?.previousAgents) {
         utils.listAgents.setData(undefined, context.previousAgents);
       }
+      if (context?.previousRefineAgent !== undefined) {
+        utils.getActiveRefineAgent.setData({ initiativeId }, context.previousRefineAgent);
+      }
     },
     onSettled: () => {
       void utils.listAgents.invalidate();
+      void utils.getActiveRefineAgent.invalidate({ initiativeId });
     },
   });
 
diff --git a/apps/web/src/routes/initiatives/$id.tsx b/apps/web/src/routes/initiatives/$id.tsx
index 350634b..7ff848e 100644
--- a/apps/web/src/routes/initiatives/$id.tsx
+++ b/apps/web/src/routes/initiatives/$id.tsx
@@ -31,7 +31,7 @@ function InitiativeDetailPage() {
   useLiveUpdates([
     { prefix: 'task:',  invalidate: ['listPhases', 'listTasks', 'listInitiativeTasks'] },
     { prefix: 'phase:', invalidate: ['listPhases', 'listTasks', 'listInitiativePhaseDependencies'] },
-    { prefix: 'agent:', invalidate: ['listAgents'] },
+    { prefix: 'agent:', invalidate: ['listAgents', 'getActiveRefineAgent'] },
     { prefix: 'page:',  invalidate: ['listPages', 'getPage', 'getRootPage'] },
   ]);