Skip to content

Commit 111e1e5

Browse files
committed
refactor(system-prompt): remove redundancy with orchestrator guidance - v15→v16
**Problem:** Significant redundancy between system prompt behavioral instructions and AgentOrchestrator's context-aware continuation guidance system. Same todo workflow rules, alternation enforcement, and continuation logic appeared in multiple places (system prompt + orchestrator + TodoReminderInjector). **Solution:** Simplified system prompt by removing redundant behavioral enforcement and focusing on identity/capabilities. Orchestrator handles workflow behavior at runtime with fresh state and context-aware adaptability. **Changes:** REMOVED (3 sections, ~930 tokens): 1. MULTI-STEP REQUESTS - TODO LIST WORKFLOW section (buildSAMSpecificPatterns) - Redundant with AgentOrchestrator Variants 1 & 2 2. buildWorkflowContinuationProtocol() function (dead code, never called) - Redundant with orchestrator's 4 continuation variants 3. buildThinkToolGuidance() function (dead code, never called) SIMPLIFIED (3 sections, ~140 tokens): 1. Tool Responsibility (buildToolUsage) - Removed enforcement language, kept principles 2. Think Tool (buildSAMSpecificPatterns) - Removed "CRITICAL" warnings, kept guidance 3. Multi-Step Request Handling (buildOperationalModes) - Removed "REQUIRED" enforcement, kept educational principles VERSION BUMP: - currentVersion: 15 → 16 - Added version comment explaining changes DOCUMENTATION: - Created project-docs/SYSTEM_PROMPT_EVOLUTION.md - Comprehensive change tracking and rationale - Design principles for system prompt vs orchestrator - Future opportunities and lessons learned **Total Savings:** ~1070 tokens (~20-25% reduction from affected sections) **Separation of Concerns:** - System Prompt: WHO SAM is + WHAT SAM can do - Orchestrator: HOW to behave during workflow (runtime enforcement) **Testing:** ✅ Build: PASS (make build-debug) ✅ No compile errors ✅ System prompt generates correctly ⏸ Manual testing: Pending (Test Cases 1-5 defined in scratch/system-prompt-analysis.md) **Files Modified:** - Sources/ConfigurationSystem/SystemPromptConfiguration.swift - project-docs/SYSTEM_PROMPT_EVOLUTION.md (new)
1 parent 6fd8d1e commit 111e1e5

2 files changed

Lines changed: 280 additions & 110 deletions

File tree

Sources/ConfigurationSystem/SystemPromptConfiguration.swift

Lines changed: 12 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,10 @@ public struct SystemPromptConfiguration: Codable, Identifiable, Hashable, Sendab
5757
public var autoEnableDynamicIterations: Bool
5858

5959
/// Current version of the prompt system (increment when making breaking changes).
60-
public static let currentVersion = 15
60+
/// Version 16: Removed redundant behavioral instructions now handled by AgentOrchestrator's
61+
/// context-aware continuation guidance system. System prompt now focuses on identity and
62+
/// capabilities; orchestrator handles workflow enforcement at runtime.
63+
public static let currentVersion = 16
6164

6265
public init(
6366
id: UUID = UUID(),
@@ -352,14 +355,8 @@ public struct SystemPromptConfiguration: Codable, Identifiable, Hashable, Sendab
352355
4. Retry alternatives on failures
353356
354357
**Tool Responsibility:**
355-
356-
**It is YOUR RESPONSIBILITY to:**
357-
- Use tools repeatedly until task is complete
358-
- Try alternative tools when one fails
359-
- Gather as much context as needed
360-
- **Not give up unless request genuinely cannot be fulfilled**
361-
362-
**Continue working until the user's request is completely resolved. Only stop when certain the task is complete. Do not stop when encountering uncertainty — research or deduce the most reasonable approach and continue.**
358+
- Use tools repeatedly to gather context and complete work
359+
- Try alternative approaches when one fails
363360
"""
364361
}
365362

@@ -397,15 +394,12 @@ public struct SystemPromptConfiguration: Codable, Identifiable, Hashable, Sendab
397394
- **Do not claim completion unless actions were actually performed**
398395
399396
## Multi-Step Request Handling
400-
**For multi-step requests (e.g., ‘import document, analyze, report results’):**
401-
- **REQUIRED FIRST STEP:** Restate ALL steps of the request in your response before executing ANY tools.
402-
- This ensures you maintain awareness of all steps throughout execution.
403-
- You MUST process all steps sequentially in one workflow.
404-
- Do NOT mark a request complete after only partial progress (e.g., just importing a document).
405-
- Immediately continue to the next step unless user clarification or additional input is required.
406-
- Only signal completion when the full deliverable is ready.
407-
- Plan ONCE. After initial reasoning, proceed directly to tool execution. Do NOT repeat planning unless new ambiguity arises.
397+
**For multi-step requests:**
398+
- Understand all steps before starting
399+
- Process sequentially in one workflow
400+
- Complete all steps before declaring done
408401
- **Example:** "I'll: 1) Create test.txt, 2) Read it back, 3) Create result.txt" THEN execute step 1.
402+
409403
"""
410404
}
411405

@@ -511,45 +505,10 @@ private static func buildSAMSpecificPatterns() -> String {
511505
512506
**Two-Phase Workflow:** GATHER all data first, then ANALYZE into ONE deliverable.
513507
514-
**Think Tool:** Shows "Thinking..." to user. Use for complex planning, error analysis, multiple approaches. Planning ≠ progress - execute after thinking.
515-
516-
CRITICAL - THINK TOOL LIMITATION:
517-
- Use the think tool only for initial planning or error analysis; immediately follow with a tool call that produces a tangible output.
518-
- Never call the think tool twice in a row; if you do, immediately switch to tool-based execution.
519-
- Planning alone is not progress—after thinking, you MUST produce a tool-generated, user-facing deliverable.
508+
**Think Tool:** Shows "Thinking..." for complex planning or error analysis. Use for reasoning, then execute with tool calls. Avoid consecutive think calls.
520509
521510
**Sequential Lists:** One item per message, emit continue after each (except last → complete).
522511
523-
MULTI-STEP REQUESTS - TODO LIST WORKFLOW:
524-
525-
**When to use todos:** Multi-step tasks that benefit from visible progress tracking
526-
527-
**Starting fresh (no todos yet):**
528-
1. FIRST: Create todo list with todo_operations(operation: "write", todoList: [...])
529-
- Set first todo: "in-progress"
530-
- Set remaining todos: "not-started"
531-
2. Then proceed with workflow below
532-
533-
**Working with existing todos:**
534-
1. Do the work for current in-progress todo
535-
2. Mark it completed: todo_operations(operation: "update", todoUpdates: [{"id": X, "status": "completed"}])
536-
3. Mark next todo in-progress: todo_operations(operation: "update", todoUpdates: [{"id": Y, "status": "in-progress"}])
537-
4. Repeat until all complete
538-
539-
**CRITICAL RULES:**
540-
- ALWAYS create todos FIRST before trying to update them (NEVER call update when no todos exist)
541-
- You MUST call todo_operations(update) to change todo status - the system cannot infer status from your text
542-
- When completing a todo: Mark it done with the tool, then move to next todo - do NOT repeat the work in your response
543-
- Each todo gets ONE completion response - mark done and move forward
544-
545-
**Anti-duplication:**
546-
- After completing Todo 1: Mark complete, start Todo 2, work on Todo 2
547-
- Do NOT: Complete Todo 1, mark done, then re-summarize Todo 1's results again
548-
- Tool call = progress indicator, not invitation to repeat output
549-
550-
**Before Complete:** Verify ALL requested items delivered. If user asked for N things, confirm N things done.
551-
552-
553512
## Data Visualization Protocol (CRITICAL)
554513
555514
**Mermaid Diagram Types:** flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, pie, bar, journey, mindmap, timeline, quadrantChart, requirementDiagram, gitGraph, xychart-beta (bar/line charts).
@@ -575,63 +534,6 @@ private static func buildSAMSpecificPatterns() -> String {
575534
"""
576535
}
577536

578-
/// Builds Think Tool Guidance section - Consolidated from multiple scattered sections.
579-
private static func buildThinkToolGuidance() -> String {
580-
return """
581-
### Think Tool (Supplemental)
582-
583-
Shows "Thinking..." to user for complex reasoning. Use sparingly - execution matters more.
584-
Avoid think tool loops: plan once, execute, don't re-plan.
585-
"""
586-
}
587-
588-
/// Builds Workflow Continuation Protocol section.
589-
private static func buildWorkflowContinuationProtocol() -> String {
590-
return """
591-
### Workflow Continuation (CRITICAL)
592-
593-
**The StatusSignalReminderInjector provides the status signal format - follow those instructions.**
594-
595-
**WITH TODO LIST:**
596-
When user asks for multiple distinct outputs (e.g., "import X, analyze Y, create Z table"):
597-
1. FIRST: Create a todo list with ALL requested deliverables
598-
2. THEN: Execute each deliverable in sequence
599-
3. AFTER EACH: Mark todo complete AND emit the appropriate status signal
600-
4. FINALLY: Emit complete status only when ALL deliverables are provided
601-
602-
**WITHOUT TODO LIST (simple multi-step):**
603-
For quick multi-step tasks that don't warrant a full todo list:
604-
1. Execute step → emit continue status
605-
2. When you receive the "continue" response from the system → Execute next step
606-
3. Repeat until last step → emit complete status
607-
608-
**TODO MANAGEMENT - USING todo_operations TOOL:**
609-
610-
Create todos (write):
611-
`todo_operations(operation="write", todoList=[{"id":1,"title":"Task 1","description":"...","status":"not-started"},...])`
612-
613-
Mark in-progress (update):
614-
`todo_operations(operation="update", todoUpdates=[{"id":1,"status":"in-progress"}])`
615-
616-
**CRITICAL - Mark completed (update):**
617-
`todo_operations(operation="update", todoUpdates=[{"id":1,"status":"completed"},{"id":2,"status":"in-progress"}])`
618-
619-
**You MUST call the update operation to mark tasks completed. The system cannot infer completion.**
620-
621-
**AFTER COMPLETING ANY TODO - MANDATORY SEQUENCE:**
622-
1. You've done the work (e.g., brainstormed names)
623-
2. IMMEDIATELY call: {"name":"todo_operations","arguments":{"operation":"update","todoUpdates":[{"id":CURRENT_ID,"status":"completed"},{"id":NEXT_ID,"status":"in-progress"}]}}
624-
3. Then start the next task
625-
4. Do NOT output the same work twice - if you've brainstormed, mark complete and move to research
626-
627-
**LOOP PREVENTION:**
628-
When you receive the "continue" response from the system, DO THE NEXT THING - don't describe the last thing.
629-
Red flags: describing same work multiple times, asking "should I continue?", same output appearing twice.
630-
631-
**Remember:** If user asks for N things, deliver N things. Partial = Failure.
632-
"""
633-
}
634-
635537
/// Builds Workflow Mode execution behavior for complex multi-step workflows.
636538
private static func buildWorkflowMode() -> String {
637539
return """

0 commit comments

Comments
 (0)