This is page 10 of 12. Use http://codebase.md/minipuft/claude-prompts-mcp?lines=false&page={x} to view the full context.
# Directory Structure
```
├── .actrc
├── .gitattributes
├── .github
│ └── workflows
│ ├── ci.yml
│ ├── mcp-compliance.yml
│ └── pr-validation.yml
├── .gitignore
├── agent.md
├── assets
│ └── logo.png
├── CLAUDE.md
├── config
│ └── framework-state.json
├── docs
│ ├── architecture.md
│ ├── chain-modification-examples.md
│ ├── contributing.md
│ ├── enhanced-gate-system.md
│ ├── execution-architecture-guide.md
│ ├── installation-guide.md
│ ├── mcp-tool-usage-guide.md
│ ├── mcp-tools-reference.md
│ ├── prompt-format-guide.md
│ ├── prompt-management.md
│ ├── prompt-vs-template-guide.md
│ ├── README.md
│ ├── template-development-guide.md
│ ├── TODO.md
│ ├── troubleshooting.md
│ └── version-history.md
├── LICENSE
├── local-test.sh
├── plans
│ ├── nunjucks-dynamic-chain-orchestration.md
│ ├── outputschema-realtime-progress-and-validation.md
│ ├── parallel-conditional-execution-analysis.md
│ ├── sqlite-storage-migration.md
│ └── symbolic-command-language-implementation.md
├── README.md
├── scripts
│ ├── setup-windows-testing.sh
│ ├── test_server.js
│ ├── test-all-platforms.sh
│ └── windows-tests
│ ├── test-windows-paths.js
│ ├── test-windows-startup.sh
│ └── windows-env.sh
└── server
├── config
│ ├── framework-state.json
│ └── tool-descriptions.json
├── config.json
├── jest.config.cjs
├── LICENSE
├── package-lock.json
├── package.json
├── prompts
│ ├── analysis
│ │ ├── advanced_analysis_engine.md
│ │ ├── content_analysis.md
│ │ ├── deep_analysis.md
│ │ ├── deep_research.md
│ │ ├── markdown_notebook.md
│ │ ├── note_integration.md
│ │ ├── note_refinement.md
│ │ ├── notes.md
│ │ ├── progressive_research.md
│ │ ├── prompts.json
│ │ ├── query_refinement.md
│ │ └── review.md
│ ├── architecture
│ │ ├── prompts.json
│ │ └── strategic-system-alignment.md
│ ├── content_processing
│ │ ├── format_enhancement.md
│ │ ├── noteIntegration.md
│ │ ├── obsidian_metadata_optimizer.md
│ │ ├── prompts.json
│ │ ├── vault_related_notes_finder.md
│ │ └── video_notes_enhanced.md
│ ├── debugging
│ │ ├── analyze_logs.md
│ │ └── prompts.json
│ ├── development
│ │ ├── analyze_code_structure.md
│ │ ├── analyze_file_structure.md
│ │ ├── code_review_optimization_chain.md
│ │ ├── component_flow_analysis.md
│ │ ├── create_modularization_plan.md
│ │ ├── detect_code_issues.md
│ │ ├── detect_project_commands.md
│ │ ├── expert_code_implementation.md
│ │ ├── generate_comprehensive_claude_md.md
│ │ ├── prompts.json
│ │ ├── strategicImplement.md
│ │ ├── suggest_code_improvements.md
│ │ └── transform_code_to_modules.md
│ ├── documentation
│ │ ├── create_docs_chain.md
│ │ ├── docs-content-creation.md
│ │ ├── docs-content-planning.md
│ │ ├── docs-final-assembly.md
│ │ ├── docs-project-analysis.md
│ │ ├── docs-review-refinement.md
│ │ └── prompts.json
│ ├── education
│ │ ├── prompts.json
│ │ └── vault_integrated_notes.md
│ ├── general
│ │ ├── diagnose.md
│ │ └── prompts.json
│ ├── promptsConfig.json
│ └── testing
│ ├── final_verification_test.md
│ └── prompts.json
├── README.md
├── scripts
│ └── validate-dependencies.js
├── src
│ ├── api
│ │ └── index.ts
│ ├── chain-session
│ │ └── manager.ts
│ ├── config
│ │ └── index.ts
│ ├── Dockerfile
│ ├── execution
│ │ ├── context
│ │ │ ├── context-resolver.ts
│ │ │ ├── framework-injector.ts
│ │ │ └── index.ts
│ │ ├── index.ts
│ │ ├── parsers
│ │ │ ├── argument-parser.ts
│ │ │ ├── index.ts
│ │ │ └── unified-command-parser.ts
│ │ └── types.ts
│ ├── frameworks
│ │ ├── framework-manager.ts
│ │ ├── framework-state-manager.ts
│ │ ├── index.ts
│ │ ├── integration
│ │ │ ├── framework-semantic-integration.ts
│ │ │ └── index.ts
│ │ ├── methodology
│ │ │ ├── guides
│ │ │ │ ├── 5w1h-guide.ts
│ │ │ │ ├── cageerf-guide.ts
│ │ │ │ ├── react-guide.ts
│ │ │ │ └── scamper-guide.ts
│ │ │ ├── index.ts
│ │ │ ├── interfaces.ts
│ │ │ └── registry.ts
│ │ ├── prompt-guidance
│ │ │ ├── index.ts
│ │ │ ├── methodology-tracker.ts
│ │ │ ├── service.ts
│ │ │ ├── system-prompt-injector.ts
│ │ │ └── template-enhancer.ts
│ │ └── types
│ │ ├── index.ts
│ │ ├── integration-types.ts
│ │ ├── methodology-types.ts
│ │ └── prompt-guidance-types.ts
│ ├── gates
│ │ ├── constants.ts
│ │ ├── core
│ │ │ ├── gate-definitions.ts
│ │ │ ├── gate-loader.ts
│ │ │ ├── gate-validator.ts
│ │ │ ├── index.ts
│ │ │ └── temporary-gate-registry.ts
│ │ ├── definitions
│ │ │ ├── code-quality.json
│ │ │ ├── content-structure.json
│ │ │ ├── educational-clarity.json
│ │ │ ├── framework-compliance.json
│ │ │ ├── research-quality.json
│ │ │ ├── security-awareness.json
│ │ │ └── technical-accuracy.json
│ │ ├── gate-state-manager.ts
│ │ ├── guidance
│ │ │ ├── FrameworkGuidanceFilter.ts
│ │ │ └── GateGuidanceRenderer.ts
│ │ ├── index.ts
│ │ ├── intelligence
│ │ │ ├── GatePerformanceAnalyzer.ts
│ │ │ └── GateSelectionEngine.ts
│ │ ├── templates
│ │ │ ├── code_quality_validation.md
│ │ │ ├── educational_clarity_validation.md
│ │ │ ├── framework_compliance_validation.md
│ │ │ ├── research_self_validation.md
│ │ │ ├── security_validation.md
│ │ │ ├── structure_validation.md
│ │ │ └── technical_accuracy_validation.md
│ │ └── types.ts
│ ├── index.ts
│ ├── logging
│ │ └── index.ts
│ ├── mcp-tools
│ │ ├── config-utils.ts
│ │ ├── constants.ts
│ │ ├── index.ts
│ │ ├── prompt-engine
│ │ │ ├── core
│ │ │ │ ├── engine.ts
│ │ │ │ ├── executor.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── processors
│ │ │ │ ├── response-formatter.ts
│ │ │ │ └── template-processor.ts
│ │ │ └── utils
│ │ │ ├── category-extractor.ts
│ │ │ ├── classification.ts
│ │ │ ├── context-builder.ts
│ │ │ └── validation.ts
│ │ ├── prompt-manager
│ │ │ ├── analysis
│ │ │ │ ├── comparison-engine.ts
│ │ │ │ ├── gate-analyzer.ts
│ │ │ │ └── prompt-analyzer.ts
│ │ │ ├── core
│ │ │ │ ├── index.ts
│ │ │ │ ├── manager.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── operations
│ │ │ │ └── file-operations.ts
│ │ │ ├── search
│ │ │ │ ├── filter-parser.ts
│ │ │ │ └── prompt-matcher.ts
│ │ │ └── utils
│ │ │ ├── category-manager.ts
│ │ │ └── validation.ts
│ │ ├── shared
│ │ │ └── structured-response-builder.ts
│ │ ├── system-control.ts
│ │ ├── tool-description-manager.ts
│ │ └── types
│ │ └── shared-types.ts
│ ├── metrics
│ │ ├── analytics-service.ts
│ │ ├── index.ts
│ │ └── types.ts
│ ├── performance
│ │ ├── index.ts
│ │ └── monitor.ts
│ ├── prompts
│ │ ├── category-manager.ts
│ │ ├── converter.ts
│ │ ├── file-observer.ts
│ │ ├── hot-reload-manager.ts
│ │ ├── index.ts
│ │ ├── loader.ts
│ │ ├── promptUtils.ts
│ │ ├── registry.ts
│ │ └── types.ts
│ ├── runtime
│ │ ├── application.ts
│ │ └── startup.ts
│ ├── semantic
│ │ ├── configurable-semantic-analyzer.ts
│ │ └── integrations
│ │ ├── index.ts
│ │ └── llm-clients.ts
│ ├── server
│ │ ├── index.ts
│ │ └── transport
│ │ └── index.ts
│ ├── smithery.yaml
│ ├── text-references
│ │ ├── conversation.ts
│ │ └── index.ts
│ ├── types
│ │ └── index.ts
│ ├── types.ts
│ └── utils
│ ├── chainUtils.ts
│ ├── errorHandling.ts
│ ├── global-resource-tracker.ts
│ ├── index.ts
│ └── jsonUtils.ts
├── tests
│ ├── ci-startup-validation.js
│ ├── enhanced-validation
│ │ ├── contract-validation
│ │ │ ├── contract-test-suite.js
│ │ │ ├── interface-contracts.js
│ │ │ └── interface-contracts.ts
│ │ ├── environment-validation
│ │ │ ├── environment-parity-checker.js
│ │ │ └── environment-test-suite.js
│ │ ├── lifecycle-validation
│ │ │ ├── lifecycle-test-suite.js
│ │ │ └── process-lifecycle-validator.js
│ │ └── validation-orchestrator.js
│ ├── helpers
│ │ └── test-helpers.js
│ ├── integration
│ │ ├── mcp-tools.test.ts
│ │ ├── server-startup.test.ts
│ │ └── unified-parsing-integration.test.ts
│ ├── performance
│ │ ├── parsing-system-benchmark.test.ts
│ │ └── server-performance.test.ts
│ ├── scripts
│ │ ├── consolidated-tools.js
│ │ ├── establish-performance-baselines.js
│ │ ├── functional-mcp-validation.js
│ │ ├── integration-mcp-tools.js
│ │ ├── integration-routing-system.js
│ │ ├── integration-server-startup.js
│ │ ├── integration-unified-parsing.js
│ │ ├── methodology-guides.js
│ │ ├── performance-memory.js
│ │ ├── runtime-integration.js
│ │ ├── unit-conversation-manager.js
│ │ ├── unit-semantic-analyzer.js
│ │ └── unit-unified-parsing.js
│ ├── setup.ts
│ ├── test-enhanced-parsing.js
│ └── unit
│ ├── conversation-manager.test.ts
│ ├── semantic-analyzer-three-tier.test.ts
│ └── unified-parsing-system.test.ts
├── tsconfig.json
└── tsconfig.test.json
```
# Files
--------------------------------------------------------------------------------
/plans/parallel-conditional-execution-analysis.md:
--------------------------------------------------------------------------------
```markdown
# Parallel & Conditional Execution - Current System Analysis
**Status**: Analysis Complete
**Created**: 2025-10-19
**Priority**: High
**Complexity**: Medium-High (Parallel), High (Conditional)
## Executive Summary
**Parallel Execution**: ✅ **Architecturally Designed** but ❌ **NOT Implemented**
**Conditional Execution**: ⚠️ **Template-Level Only** (Nunjucks conditionals, not execution branching)
**Parser Support**: ❌ **Neither operator currently detectable**
**Key Finding**: The system is **instruction-based** (generates instructions for LLM to execute steps) rather than **execution-based** (server executes steps directly). This architectural choice impacts how parallel and conditional operators can be implemented.
## Detailed Findings
### 1. Parallel Execution Status
#### ✅ Type Definitions Exist (Infrastructure Ready)
**Location**: `server/src/execution/types.ts:39`
```typescript
export interface ChainStep {
parallelGroup?: string; // Group ID for parallel execution (steps with same group run concurrently)
dependencies?: string[]; // Step IDs that must complete before this step
timeout?: number; // Step-specific timeout in milliseconds
retries?: number; // Number of retries for this step
stepType?: 'prompt' | 'tool' | 'gate' | 'condition';
}
```
**Location**: `server/src/execution/types.ts:237`
```typescript
export interface EnhancedChainExecutionOptions {
enableParallelExecution?: boolean; // Enable parallel execution of steps in same parallel group
maxConcurrency?: number; // Maximum concurrent steps
parallelTimeout?: number; // Timeout for parallel groups
}
```
**Location**: `server/src/types/index.ts:150`
```typescript
export interface EnhancedChainExecutionContext {
executionPlan?: {
executionOrder: string[]; // Topologically sorted step execution order
parallelGroups: Map<string, string[]>; // Parallel execution groups
};
activeParallelGroups: Map<string, string[]>; // Currently executing parallel groups
retryCount: Record<string, number>; // Retry attempts per step
}
```
#### ❌ Execution Logic NOT Implemented
**Current Chain Execution**: `server/src/mcp-tools/prompt-engine/core/executor.ts:437`
```typescript
// generateChainInstructions() - Returns instructions for LLM to execute
instructions += `- Execute steps sequentially, do not skip steps\n`;
instructions += `- Validate outputs before proceeding to next step\n`;
```
**Reality**:
- Chain executor generates **Markdown instructions** for LLM to execute steps
- No server-side step execution engine
- LLM is responsible for calling MCP tools for each step
- No `Promise.all()` or concurrent execution logic
**Missing Components**:
1. **Parallel Step Executor**: No code to execute multiple steps concurrently
2. **Dependency Resolver**: No topological sorting implementation
3. **Result Aggregator**: No logic to merge parallel step results
4. **Scheduler**: No parallel group scheduling
5. **Synchronization**: No coordination between parallel steps
**Detection Only**: `server/src/semantic/configurable-semantic-analyzer.ts:595`
```typescript
if ((step as any).parallelGroup) {
hasParallelSteps = true;
// Only used for semantic analysis/classification, not execution
}
```
### 2. Conditional Execution Status
#### ⚠️ Template-Level Conditionals Only (Nunjucks)
**What EXISTS**: Nunjucks template conditionals in user message templates
**Example**: `server/prompts/analysis/advanced_analysis_engine.md`
```nunjucks
{% if depth == 'expert' %}
## Expert-Level Analysis Required
Apply rigorous academic standards...
{% elif depth == 'comprehensive' %}
## Comprehensive Analysis
Thorough examination with detailed coverage...
{% else %}
## Standard Analysis
Balanced approach with key insights...
{% endif %}
```
**Classification Detection**: `server/src/mcp-tools/prompt-engine/utils/classification.ts:222`
```typescript
const conditionals = (convertedPrompt.userMessageTemplate.match(/\{%\s*(if|for|while)\s/g) || []).length;
complexity += conditionals * 0.1;
```
**Behavior**: Conditionals evaluated at **template rendering time** based on input arguments, NOT based on execution results.
#### ❌ What DOESN'T EXIST: Execution-Level Conditional Branching
**Missing Capabilities**:
1. **Dynamic Step Selection**: No ability to choose next step based on previous result
2. **LLM-Evaluated Conditions**: No condition evaluation against execution output
3. **Branching Logic**: No "if step1 succeeds then step2a else step2b" workflow
4. **Result-Based Routing**: No decision points in execution flow
5. **Conditional Operator**: No `?` operator parsing or execution
**Closest Analogy - Gate Conditionals**: `server/src/mcp-tools/prompt-engine/core/engine.ts:1589-1617`
```typescript
// Only conditional logic in execution system: gate result rendering
this.logger.info(`🔍 [DEBUG] Gate conditional logic:`, {
hasGateResults: !!gateResults
});
if (gateResults) {
this.logger.info(`🔀 [DEBUG] Taking IF branch (gateResults exists)`);
// Render gate results
return this.renderGateResults(gateResults, template);
} else {
this.logger.info(`🔀 [DEBUG] Taking ELSE branch (no gateResults)`);
// Render gate guidance
return this.renderGateGuidance(applicableGates, template);
}
```
**Note**: This is **gate rendering logic** for UI display, not execution branching.
### 3. Parser Support Status
#### ❌ NO Symbolic Operator Detection
**Current Parser**: `server/src/execution/parsers/unified-command-parser.ts`
**Supported Formats**:
```typescript
private initializeStrategies(): ParsingStrategy[] {
return [
this.createSimpleCommandStrategy(), // >>prompt_name arguments
this.createJsonCommandStrategy() // {"command": ">>prompt", "args": {...}}
];
}
```
**Operator Detection Patterns - NOT IMPLEMENTED**:
- ❌ Chain operator: `-->`
- ❌ Parallel operator: `+`
- ❌ Conditional operator: `?`
- ❌ Gate operator: `=`
- ❌ Framework operator: `@`
**Current Regex Patterns**: `server/src/execution/parsers/unified-command-parser.ts:132-138`
```typescript
canHandle: (command: string) => {
// More flexible pattern - handles spaces in prompt names via underscore conversion
return /^(>>|\/)[a-zA-Z0-9_\-\s]+(\s|$)/.test(command.trim());
}
```
**No symbolic operators** in detection patterns.
### 4. Test Evidence
#### Concurrent Command Processing Test
**Location**: `tests/integration/unified-parsing-integration.test.ts:414-428`
```typescript
test('should handle concurrent command processing', async () => {
const concurrentCommands = [
'>>simple_test concurrent test 1',
'>>multi_arg_test concurrent test 2',
'>>simple_test concurrent test 3'
];
const promises = concurrentCommands.map(command =>
parsingSystem.commandParser.parseCommand(command, promptsData)
);
const results = await Promise.all(promises);
expect(results).toHaveLength(3);
expect(stats.commandParser.totalParses).toBe(concurrentCommands.length);
});
```
**What This Tests**:
- Parser **thread-safety** (handling multiple parse requests concurrently)
- Multiple **independent commands** processed in parallel
**What This Does NOT Test**:
- Parallel execution of **steps within a single chain**
- Concurrent **prompt execution**
- Parallel **step result aggregation**
## Architectural Implications
### Current Architecture: Instruction-Based Execution
```
┌─────────────────────────────────────────────────────────────┐
│ User Command: >>chain_prompt args │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Parser: Detect chain, parse steps │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ChainExecutor: Generate Markdown instructions │
│ - Step 1: Call >>prompt1 │
│ - Step 2: Call >>prompt2 with step1_result │
│ - Step 3: Call >>prompt3 with step2_result │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Return instructions to LLM (Claude Code) │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LLM executes steps manually: │
│ - Calls prompt_engine tool for each step │
│ - Manages context/results between steps │
│ - Handles errors and retries │
└─────────────────────────────────────────────────────────────┘
```
**Key Characteristics**:
- ✅ Flexible (LLM can adapt execution)
- ✅ Error-resilient (LLM handles issues)
- ❌ No true parallel execution (LLM is sequential)
- ❌ Slower (multiple MCP tool calls)
- ❌ No deterministic branching (LLM makes decisions)
### Alternative Architecture: Server-Side Execution Engine
```
┌─────────────────────────────────────────────────────────────┐
│ User Command: >>step1 + step2 + step3 --> synthesis │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Parser: Detect operators (+, -->) │
│ - Parallel group: [step1, step2, step3] │
│ - Sequential: synthesis │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ExecutionEngine: Build execution plan │
│ - Parallel group 1: Execute step1, step2, step3 concurrently │
│ - Wait for all to complete │
│ - Sequential: Execute synthesis with aggregated results │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ StepExecutor: Execute each step │
│ Promise.all([ │
│ executePrompt('step1'), │
│ executePrompt('step2'), │
│ executePrompt('step3') │
│ ]) │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ResultAggregator: Merge parallel results │
│ aggregatedResult = { │
│ step1_result: "...", │
│ step2_result: "...", │
│ step3_result: "..." │
│ } │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Continue execution with synthesis step │
│ executePrompt('synthesis', aggregatedResult) │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Return final result to user │
└─────────────────────────────────────────────────────────────┘
```
**Key Characteristics**:
- ✅ True parallel execution (real concurrency)
- ✅ Faster (single MCP interaction)
- ✅ Deterministic (predictable execution flow)
- ❌ Less flexible (fixed execution plan)
- ❌ Complex error handling needed
- ❌ Major architectural change
## Gap Analysis
### Components Needed for Parallel Execution
#### 1. Parser Enhancement (**Estimated: 2-3 days**)
**File**: `server/src/execution/parsers/symbolic-command-parser.ts` (new)
```typescript
export class SymbolicCommandParser {
private readonly PARALLEL_PATTERN = /\s*\+\s*/g;
detectParallelOperator(command: string): {
hasParallel: boolean;
prompts: string[];
} {
if (!this.PARALLEL_PATTERN.test(command)) {
return { hasParallel: false, prompts: [] };
}
const prompts = command.split('+').map(p => p.trim());
return {
hasParallel: true,
prompts
};
}
}
```
#### 2. Execution Engine (**Estimated: 1-2 weeks**)
**File**: `server/src/execution/engines/parallel-executor.ts` (new)
```typescript
export class ParallelExecutor {
/**
* Execute multiple steps concurrently
*/
async executeParallelGroup(
steps: ChainStep[],
context: ExecutionContext
): Promise<ParallelExecutionResult> {
this.logger.info(`Executing ${steps.length} steps in parallel`);
const promises = steps.map(step =>
this.executeStep(step, context)
);
const results = await Promise.all(promises);
return this.aggregateResults(results);
}
private async executeStep(
step: ChainStep,
context: ExecutionContext
): Promise<StepResult> {
// Execute individual step
// This requires actual prompt execution, not instruction generation
}
private aggregateResults(
results: StepResult[]
): ParallelExecutionResult {
// Merge results from parallel executions
return {
combinedOutput: results.map(r => r.output).join('\n\n'),
stepResults: results,
metadata: {
executionTime: Math.max(...results.map(r => r.executionTime)),
stepCount: results.length
}
};
}
}
```
#### 3. Dependency Resolver (**Estimated: 3-5 days**)
**File**: `server/src/execution/engines/dependency-resolver.ts` (new)
```typescript
export class DependencyResolver {
/**
* Topological sort of steps based on dependencies
*/
resolveExecutionOrder(steps: ChainStep[]): ExecutionPlan {
const graph = this.buildDependencyGraph(steps);
const executionOrder = this.topologicalSort(graph);
const parallelGroups = this.identifyParallelGroups(steps, executionOrder);
return {
executionOrder,
parallelGroups,
estimatedTime: this.estimateExecutionTime(parallelGroups)
};
}
private identifyParallelGroups(
steps: ChainStep[],
executionOrder: string[]
): Map<string, string[]> {
const groups = new Map<string, string[]>();
// Group steps with same parallelGroup ID
for (const step of steps) {
if (step.parallelGroup) {
const existing = groups.get(step.parallelGroup) || [];
existing.push(step.promptId);
groups.set(step.parallelGroup, existing);
}
}
return groups;
}
private topologicalSort(graph: DependencyGraph): string[] {
// Kahn's algorithm or DFS-based topological sort
// Returns execution order respecting dependencies
}
}
```
#### 4. State Management (**Estimated: 3-5 days**)
**File**: `server/src/execution/engines/execution-state-manager.ts` (new)
```typescript
export class ExecutionStateManager {
private activeExecutions = new Map<string, ExecutionState>();
trackParallelGroup(
groupId: string,
stepIds: string[]
): void {
const state = this.getOrCreateState(groupId);
state.activeSteps = stepIds;
state.startTime = Date.now();
}
recordStepCompletion(
groupId: string,
stepId: string,
result: StepResult
): void {
const state = this.getState(groupId);
state.completedSteps.add(stepId);
state.stepResults[stepId] = result;
// Check if group is complete
if (state.completedSteps.size === state.activeSteps.length) {
this.finalizeGroup(groupId);
}
}
handleStepFailure(
groupId: string,
stepId: string,
error: Error
): void {
const state = this.getState(groupId);
state.failedSteps.add(stepId);
// Decide: fail fast or continue with partial results?
}
}
```
### Components Needed for Conditional Execution
#### 1. Parser Enhancement (**Estimated: 2-3 days**)
**File**: `server/src/execution/parsers/symbolic-command-parser.ts` (enhancement)
```typescript
export class SymbolicCommandParser {
private readonly CONDITIONAL_PATTERN = /\?\s*["'](.+?)["']\s*:\s*(\w+)(?:\s*:\s*(\w+))?/;
detectConditionalOperator(command: string): {
hasConditional: boolean;
condition: string;
trueBranch: string;
falseBranch?: string;
} {
const match = command.match(this.CONDITIONAL_PATTERN);
if (!match) {
return { hasConditional: false, condition: '', trueBranch: '' };
}
return {
hasConditional: true,
condition: match[1],
trueBranch: match[2],
falseBranch: match[3]
};
}
}
```
#### 2. Condition Evaluator (**Estimated: 1 week**)
**File**: `server/src/execution/engines/condition-evaluator.ts` (new)
```typescript
export class ConditionEvaluator {
/**
* Evaluate condition against execution result
*/
async evaluateCondition(
condition: string,
executionResult: any
): Promise<boolean> {
const conditionType = this.detectConditionType(condition);
switch (conditionType) {
case 'presence':
return this.evaluatePresenceCondition(condition, executionResult);
case 'comparison':
return this.evaluateComparisonCondition(condition, executionResult);
case 'pattern':
return this.evaluatePatternCondition(condition, executionResult);
case 'llm':
return this.evaluateLLMCondition(condition, executionResult);
}
}
private evaluatePresenceCondition(
condition: string,
result: any
): boolean {
// Check if result contains specific text/pattern
return result.toLowerCase().includes(condition.toLowerCase());
}
private async evaluateLLMCondition(
condition: string,
result: any
): Promise<boolean> {
// Use LLM to evaluate complex conditions
const prompt = `Evaluate if this condition is true: "${condition}"
Given the following execution result:
${result}
Return ONLY "true" or "false".`;
const evaluation = await this.callLLM(prompt);
return evaluation.toLowerCase().includes('true');
}
}
```
#### 3. Dynamic Step Selector (**Estimated: 3-5 days**)
**File**: `server/src/execution/engines/step-selector.ts` (new)
```typescript
export class StepSelector {
/**
* Select next step based on condition evaluation
*/
async selectNextStep(
conditionalOp: ConditionalOperator,
previousResult: any
): Promise<string> {
const conditionMet = await this.conditionEvaluator.evaluateCondition(
conditionalOp.condition,
previousResult
);
if (conditionMet) {
this.logger.info(`Condition "${conditionalOp.condition}" is TRUE, executing: ${conditionalOp.trueBranch}`);
return conditionalOp.trueBranch;
} else {
if (conditionalOp.falseBranch) {
this.logger.info(`Condition "${conditionalOp.condition}" is FALSE, executing: ${conditionalOp.falseBranch}`);
return conditionalOp.falseBranch;
} else {
this.logger.info(`Condition "${conditionalOp.condition}" is FALSE, no false branch, stopping`);
return null;
}
}
}
/**
* Build dynamic execution path based on conditions
*/
async buildConditionalPath(
initialStep: ChainStep,
conditionals: ConditionalOperator[]
): Promise<ChainStep[]> {
const path: ChainStep[] = [initialStep];
let currentResult = null;
for (const conditional of conditionals) {
const nextStepId = await this.selectNextStep(conditional, currentResult);
if (!nextStepId) break;
const nextStep = this.findStep(nextStepId);
path.push(nextStep);
// Would need to execute step to get result for next condition
currentResult = await this.executeStep(nextStep);
}
return path;
}
}
```
#### 4. Branch Execution Engine (**Estimated: 1 week**)
**File**: `server/src/execution/engines/branch-executor.ts` (new)
```typescript
export class BranchExecutor {
/**
* Execute conditional branches
*/
async executeConditionalBranch(
mainStep: ChainStep,
conditionalOp: ConditionalOperator,
context: ExecutionContext
): Promise<BranchExecutionResult> {
// Execute main step
const mainResult = await this.executeStep(mainStep, context);
// Evaluate condition
const conditionMet = await this.conditionEvaluator.evaluateCondition(
conditionalOp.condition,
mainResult
);
// Execute appropriate branch
const branchStepId = conditionMet
? conditionalOp.trueBranch
: conditionalOp.falseBranch;
if (!branchStepId) {
return {
mainResult,
branchResult: null,
conditionMet,
executionPath: [mainStep.promptId]
};
}
const branchStep = this.findStep(branchStepId);
const branchResult = await this.executeStep(branchStep, {
...context,
previousResult: mainResult
});
return {
mainResult,
branchResult,
conditionMet,
executionPath: [mainStep.promptId, branchStep.promptId]
};
}
}
```
## Implementation Strategies
### Strategy 1: Hybrid Approach (Recommended)
**Concept**: Extend instruction-based system with server-side execution for operators
**Parallel Operator Implementation**:
```
1. Parser detects `+` operator
2. Generate instructions that include:
- "Execute steps 1, 2, 3 in parallel using separate MCP tool calls"
- "Wait for all to complete before proceeding"
- Provide result aggregation template
3. LLM executes steps concurrently (multiple tool calls)
4. LLM aggregates results following template
```
**Pros**:
- ✅ Minimal architectural change
- ✅ Leverages existing instruction system
- ✅ LLM handles error cases flexibly
- ✅ Quick to implement (parser + instruction templates)
**Cons**:
- ❌ Not true server-side parallelism
- ❌ Depends on LLM's ability to parallelize
- ❌ Variable execution patterns
### Strategy 2: Server-Side Execution Engine (Future)
**Concept**: Build full execution engine with actual step execution
**Implementation**:
```
1. Parser detects operators and builds execution plan
2. ExecutionEngine executes steps directly:
- ParallelExecutor for `+` groups
- ConditionalExecutor for `?` branches
- SequentialExecutor for `-->` chains
3. Return final aggregated result to LLM
```
**Pros**:
- ✅ True parallel execution
- ✅ Deterministic execution flow
- ✅ Performance optimization
- ✅ Consistent behavior
**Cons**:
- ❌ Major architectural change
- ❌ Complex error handling
- ❌ Longer development time (2-3 months)
- ❌ Loss of LLM flexibility
### Strategy 3: Progressive Enhancement (Pragmatic)
**Concept**: Start with Strategy 1, evolve toward Strategy 2
**Phase 1** (Weeks 1-2): Instruction-based operators
- Implement `-->`, `=`, `@` with instruction generation
- Add `+` with parallel execution instructions for LLM
**Phase 2** (Weeks 3-4): Partial server-side execution
- Implement simple parallel executor for `+` operator
- Keep complex chains as instructions
- Measure performance improvements
**Phase 3** (Months 2-3): Full execution engine
- Build complete server-side execution system
- Migrate all operators to execution engine
- Maintain backward compatibility with instruction mode
**Pros**:
- ✅ Immediate value from Phase 1
- ✅ Incremental investment
- ✅ Learn from usage patterns
- ✅ Minimize risk
**Cons**:
- ⚠️ Longer overall timeline
- ⚠️ Temporary code duplication
- ⚠️ Multiple refactorings
## Recommendations
### Immediate Actions (This Week)
1. **Update Implementation Plan**: Revise `symbolic-command-language-implementation.md` with architecture insights
2. **Choose Strategy**: Recommend **Strategy 3 (Progressive Enhancement)**
3. **Prioritize Operators**:
- **Phase 1A**: `-->` (chain), `=` (gate), `@` (framework) - Instruction-based
- **Phase 1B**: `+` (parallel) - Instruction-based with LLM-driven concurrency
- **Phase 2**: `+` (parallel) - Server-side execution engine
- **Phase 3**: `?` (conditional) - Server-side execution engine
### Architecture Decision
**Proposal**: Dual-mode execution system
```typescript
export interface ExecutionMode {
mode: 'instruction' | 'server';
features: {
parallel: boolean;
conditional: boolean;
gateValidation: boolean;
};
}
// Start with instruction mode
const defaultMode: ExecutionMode = {
mode: 'instruction',
features: {
parallel: false, // LLM-driven via instructions
conditional: false,
gateValidation: true
}
};
// Evolve to server mode
const futureMode: ExecutionMode = {
mode: 'server',
features: {
parallel: true, // True Promise.all() execution
conditional: true, // Server-side branching
gateValidation: true
}
};
```
### Revised Implementation Timeline
**Phase 1A: Foundation (Weeks 1-2)** - Instruction-Based Operators
- Chain operator (`-->`) with instruction generation
- Gate operator (`=`) with temporary gate creation
- Framework operator (`@`) with framework switching
- **Deliverable**: Basic symbolic operators working
**Phase 1B: Parallel Instructions (Week 3)** - Hybrid Approach
- Parallel operator (`+`) detection
- Generate parallel execution instructions for LLM
- Result aggregation templates
- **Deliverable**: LLM-driven parallel execution
**Phase 2: Server-Side Parallel (Weeks 4-6)** - Execution Engine v1
- Build ParallelExecutor with Promise.all()
- Dependency resolution system
- Result aggregation engine
- **Deliverable**: True server-side parallelism
**Phase 3: Conditional Execution (Weeks 7-10)** - Execution Engine v2
- Condition evaluator (rule-based + LLM)
- Dynamic step selector
- Branch execution engine
- **Deliverable**: Full conditional workflow support
## Technical Debt & Risks
### Risk 1: Instruction vs Execution Paradigm Conflict
**Risk**: Mixing instruction-based and execution-based approaches creates complexity
**Mitigation**:
- Clear separation of concerns (mode detection)
- Feature flags for execution mode
- Comprehensive testing for both modes
- Migration guide for users
### Risk 2: LLM Reliability for Parallel Execution (Phase 1B)
**Risk**: LLM may not reliably execute parallel steps concurrently
**Mitigation**:
- Clear instructions emphasizing parallelism
- Examples of concurrent tool calls
- Fallback to sequential if needed
- Monitor success rates
### Risk 3: Performance Overhead of Server-Side Execution
**Risk**: Server-side execution may be slower due to MCP protocol overhead
**Mitigation**:
- Performance benchmarking
- Optimize MCP tool calls
- Batch operations where possible
- User choice between modes
### Risk 4: Complex Error Handling in Execution Engine
**Risk**: Server-side execution requires sophisticated error handling
**Mitigation**:
- Comprehensive error types
- Retry logic with backoff
- Partial result preservation
- Clear error messages
## Success Metrics
### Phase 1A Metrics
- ✅ Parser detects `-->`, `=`, `@` operators (100% accuracy)
- ✅ Instructions generated correctly (manual validation)
- ✅ LLM executes chains successfully (>90% success rate)
### Phase 1B Metrics
- ✅ Parallel operator detected (100% accuracy)
- ⚠️ LLM executes steps concurrently (>70% success rate)
- ⚠️ Results aggregated correctly (>80% accuracy)
### Phase 2 Metrics
- ✅ True parallel execution (Promise.all() used)
- ✅ Performance improvement (>30% faster than sequential)
- ✅ Dependency resolution works (100% correct ordering)
### Phase 3 Metrics
- ✅ Conditional branching works (100% correct paths)
- ✅ LLM condition evaluation accurate (>85% agreement with rules)
- ✅ Complex workflows supported (3+ branches)
## Next Steps
### Immediate (This Week)
1. ✅ Create this analysis document
2. ⏳ Update symbolic-command-language-implementation.md
3. ⏳ Create architecture decision record (ADR)
4. ⏳ Prototype parallel operator parser
### Short Term (Weeks 1-2)
1. Implement Phase 1A operators (instruction-based)
2. Test with real-world use cases
3. Gather user feedback
4. Refine instruction templates
### Medium Term (Weeks 3-6)
1. Build parallel executor (server-side)
2. Performance benchmarking
3. Migration guide for execution modes
4. User education materials
### Long Term (Months 2-3)
1. Full execution engine with conditionals
2. Advanced features (nested conditionals, complex dependencies)
3. Optimization and scaling
4. Production deployment
---
**End of Analysis Document**
This analysis will inform the implementation strategy for parallel and conditional execution operators in the symbolic command language system.
```
--------------------------------------------------------------------------------
/server/src/execution/parsers/argument-parser.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Argument Processing Pipeline
*
* Advanced argument processing system that handles validation, sanitization,
* type coercion, and enrichment based on prompt definitions and execution context.
*
* Features:
* - Type-aware argument coercion based on prompt definitions
* - Smart default resolution (replaces hardcoded {{previous_message}})
* - Multi-source context aggregation
* - Argument validation cascading
* - Context-aware placeholder resolution
*/
import { Logger } from "../../logging/index.js";
import type { PromptData, PromptArgument } from "../../prompts/types.js";
import { safeJsonParse, validateJsonArguments } from "../../utils/index.js";
import type { ValidationResult, ValidationError, ValidationWarning } from "../types.js";
/**
* Processing result with detailed metadata
*/
export interface ArgumentParsingResult {
processedArgs: Record<string, string | number | boolean | null>;
resolvedPlaceholders: Record<string, string | number | boolean | null>;
validationResults: ValidationResult[];
metadata: {
parsingStrategy: string;
appliedDefaults: string[];
typeCoercions: Array<{ arg: string; from: string; to: string }>;
contextSources: Record<string, string>;
warnings: string[];
};
}
/**
* Execution context for argument processing
*/
export interface ExecutionContext {
conversationHistory?: Array<{role: string; content: string; timestamp?: string}>;
environmentVars?: Record<string, string>;
promptDefaults?: Record<string, string | number | boolean | null>;
userSession?: Record<string, string | number | boolean | null>;
systemContext?: Record<string, string | number | boolean | null>;
}
/**
* Processing strategy interface
*/
interface ProcessingStrategy {
name: string;
canHandle: (rawArgs: string, promptData: PromptData) => boolean;
process: (rawArgs: string, promptData: PromptData, context: ExecutionContext) => ArgumentParsingResult;
}
/**
* Argument Processor Class
*/
export class ArgumentParser {
private logger: Logger;
private strategies: ProcessingStrategy[];
// Processing statistics
private stats = {
totalProcessed: 0,
successfulProcessing: 0,
validationFailures: 0,
typeCoercions: 0,
defaultsApplied: 0,
contextResolutions: 0
};
constructor(logger: Logger) {
this.logger = logger;
this.strategies = this.initializeStrategies();
this.logger.debug(`ArgumentParser initialized with ${this.strategies.length} processing strategies`);
}
/**
* Process arguments through validation, sanitization, and enrichment pipeline
*/
async parseArguments(
rawArgs: string,
promptData: PromptData,
context: ExecutionContext = {}
): Promise<ArgumentParsingResult> {
this.stats.totalProcessed++;
this.logger.debug(`Processing arguments for prompt "${promptData.id}": "${rawArgs.substring(0, 100)}..."`);
// Select appropriate processing strategy
const strategy = this.selectStrategy(rawArgs, promptData);
try {
const result = strategy.process(rawArgs, promptData, context);
// Apply validation and enrichment
const enrichedResult = await this.enrichResult(result, promptData, context);
this.stats.successfulProcessing++;
this.updateProcessingStats(enrichedResult);
this.logger.debug(`Arguments processed successfully using strategy: ${strategy.name}`);
return enrichedResult;
} catch (error) {
this.stats.validationFailures++;
this.logger.error(`Argument processing failed for prompt ${promptData.id}:`, error);
throw error;
}
}
/**
* Initialize processing strategies
*/
private initializeStrategies(): ProcessingStrategy[] {
return [
this.createJsonStrategy(),
this.createKeyValueStrategy(),
this.createSimpleTextStrategy(),
this.createFallbackStrategy()
];
}
/**
* Select best processing strategy for the given arguments
*/
private selectStrategy(rawArgs: string, promptData: PromptData): ProcessingStrategy {
for (const strategy of this.strategies) {
if (strategy.canHandle(rawArgs, promptData)) {
return strategy;
}
}
// Should never reach here due to fallback strategy, but safety first
return this.strategies[this.strategies.length - 1];
}
/**
* JSON argument processing strategy
*/
private createJsonStrategy(): ProcessingStrategy {
return {
name: 'json',
canHandle: (rawArgs: string) => {
const trimmed = rawArgs.trim();
return (trimmed.startsWith('{') && trimmed.endsWith('}')) ||
(trimmed.startsWith('[') && trimmed.endsWith(']'));
},
process: (rawArgs: string, promptData: PromptData, context: ExecutionContext): ArgumentParsingResult => {
const parseResult = safeJsonParse(rawArgs);
if (!parseResult.success || !parseResult.data) {
throw new Error(`Invalid JSON arguments: ${parseResult.error || 'Unknown parsing error'}`);
}
const jsonArgs = parseResult.data;
const validation = validateJsonArguments(jsonArgs, promptData);
const processedArgs = validation.sanitizedArgs || {};
// Ensure processedArgs only contains allowed types for UnifiedExecutionContext
const compatibleArgs: Record<string, string | number | boolean | null> = {};
for (const [key, value] of Object.entries(processedArgs)) {
if (Array.isArray(value)) {
// Convert arrays to JSON strings for compatibility
compatibleArgs[key] = JSON.stringify(value);
} else {
compatibleArgs[key] = value as string | number | boolean | null;
}
}
const validationResults = this.createValidationResults(compatibleArgs, promptData, validation);
return {
processedArgs: compatibleArgs,
resolvedPlaceholders: {},
validationResults,
metadata: {
parsingStrategy: 'json',
appliedDefaults: [],
typeCoercions: [],
contextSources: {},
warnings: validation.errors || []
}
};
}
};
}
/**
* Key-value pair processing strategy (arg1=value1 arg2=value2)
*/
private createKeyValueStrategy(): ProcessingStrategy {
return {
name: 'keyvalue',
canHandle: (rawArgs: string) => {
return /\w+\s*=\s*/.test(rawArgs);
},
process: (rawArgs: string, promptData: PromptData, context: ExecutionContext): ArgumentParsingResult => {
const processedArgs: Record<string, string | number | boolean | null> = {};
const typeCoercions: Array<{ arg: string; from: string; to: string }> = [];
// Parse key=value pairs with proper quote handling
const pairs = rawArgs.match(/(\w+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s]+(?:\s+(?!\w+\s*=)[^\s]*)*?))/g) || [];
for (const pair of pairs) {
const match = pair.match(/(\w+)\s*=\s*(?:"([^"]*)"|'([^']*)'|(.*))/);
if (match) {
const [, key, doubleQuoted, singleQuoted, unquoted] = match;
// Use the appropriate captured group - quoted strings take precedence
const value = doubleQuoted !== undefined ? doubleQuoted :
singleQuoted !== undefined ? singleQuoted :
unquoted || '';
const trimmedValue = value.trim();
// Find argument definition for type coercion
const argDef = promptData.arguments.find(arg => arg.name === key);
if (argDef) {
const coercedValue = this.coerceArgumentType(trimmedValue, argDef);
if (coercedValue.wasCoerced) {
typeCoercions.push({
arg: key,
from: typeof trimmedValue,
to: typeof coercedValue.value
});
}
processedArgs[key] = coercedValue.value;
} else {
processedArgs[key] = trimmedValue;
}
}
}
const validationResults = this.createValidationResults(processedArgs, promptData);
return {
processedArgs,
resolvedPlaceholders: {},
validationResults,
metadata: {
parsingStrategy: 'keyvalue',
appliedDefaults: [],
typeCoercions,
contextSources: {},
warnings: []
}
};
}
};
}
/**
* Simple text processing strategy
*/
private createSimpleTextStrategy(): ProcessingStrategy {
return {
name: 'simple',
canHandle: (rawArgs: string, promptData: PromptData) => {
return rawArgs.trim().length > 0 && promptData.arguments.length > 0;
},
process: (rawArgs: string, promptData: PromptData, context: ExecutionContext): ArgumentParsingResult => {
const processedArgs: Record<string, string | number | boolean | null> = {};
const appliedDefaults: string[] = [];
const contextSources: Record<string, string> = {};
if (promptData.arguments.length === 1) {
// Single argument - assign all text to it
const arg = promptData.arguments[0];
processedArgs[arg.name] = rawArgs.trim();
contextSources[arg.name] = 'user_provided';
} else {
// Multiple arguments - use intelligent defaults
this.applyIntelligentDefaults(
rawArgs,
promptData,
processedArgs,
appliedDefaults,
contextSources,
context
);
}
const validationResults = this.createValidationResults(processedArgs, promptData);
return {
processedArgs,
resolvedPlaceholders: {},
validationResults,
metadata: {
parsingStrategy: 'simple',
appliedDefaults,
typeCoercions: [],
contextSources,
warnings: []
}
};
}
};
}
/**
* Fallback processing strategy
*/
private createFallbackStrategy(): ProcessingStrategy {
return {
name: 'fallback',
canHandle: () => true, // Always handles as last resort
process: (rawArgs: string, promptData: PromptData, context: ExecutionContext): ArgumentParsingResult => {
const processedArgs: Record<string, string | number | boolean | null> = {};
const appliedDefaults: string[] = [];
const contextSources: Record<string, string> = {};
const warnings: string[] = [];
// Apply defaults for all arguments
for (const arg of promptData.arguments) {
if (rawArgs.trim()) {
// Use provided text for first argument, defaults for rest
if (Object.keys(processedArgs).length === 0) {
processedArgs[arg.name] = rawArgs.trim();
contextSources[arg.name] = 'user_provided';
} else {
const defaultValue = this.resolveContextualDefault(arg, context);
processedArgs[arg.name] = defaultValue.value;
contextSources[arg.name] = defaultValue.source;
appliedDefaults.push(arg.name);
}
} else {
const defaultValue = this.resolveContextualDefault(arg, context);
processedArgs[arg.name] = defaultValue.value;
contextSources[arg.name] = defaultValue.source;
appliedDefaults.push(arg.name);
}
}
warnings.push('Used fallback argument processing - consider using structured format');
const validationResults = this.createValidationResults(processedArgs, promptData);
return {
processedArgs,
resolvedPlaceholders: {},
validationResults,
metadata: {
parsingStrategy: 'fallback',
appliedDefaults,
typeCoercions: [],
contextSources,
warnings
}
};
}
};
}
/**
* Apply intelligent defaults for arguments
* ENHANCED: Smarter content mapping and auto-fill for 100% success rate
*/
private applyIntelligentDefaults(
userContent: string,
promptData: PromptData,
processedArgs: Record<string, string | number | boolean | null>,
appliedDefaults: string[],
contextSources: Record<string, string>,
context: ExecutionContext
): void {
// Enhanced priority order for content assignment with better semantic matching
const contentPriority = [
'content', 'text', 'input', 'data', 'message', 'query', 'prompt',
'description', 'topic', 'subject', 'analysis', 'code', 'file'
];
// Find the most appropriate argument for user content using multiple strategies
let targetArg = null;
// Strategy 1: Exact semantic match
for (const priority of contentPriority) {
targetArg = promptData.arguments.find(arg =>
arg.name.toLowerCase().includes(priority)
);
if (targetArg) {
this.logger.debug(`Semantic match found: ${targetArg.name} (matched: ${priority})`);
break;
}
}
// Strategy 2: Description-based matching
if (!targetArg && userContent) {
targetArg = promptData.arguments.find(arg =>
arg.description && (
arg.description.toLowerCase().includes('content') ||
arg.description.toLowerCase().includes('text') ||
arg.description.toLowerCase().includes('input') ||
arg.description.toLowerCase().includes('analyze')
)
);
if (targetArg) {
this.logger.debug(`Description match found: ${targetArg.name}`);
}
}
// Strategy 3: First required argument
if (!targetArg) {
targetArg = promptData.arguments.find(arg => arg.required);
if (targetArg) {
this.logger.debug(`First required argument selected: ${targetArg.name}`);
}
}
// Strategy 4: First argument (fallback)
if (!targetArg && promptData.arguments.length > 0) {
targetArg = promptData.arguments[0];
this.logger.debug(`First argument fallback: ${targetArg.name}`);
}
// Assign user content to target argument with intelligent processing
if (targetArg && userContent) {
processedArgs[targetArg.name] = this.processContentForArgument(userContent, targetArg);
contextSources[targetArg.name] = 'user_provided_smart_mapped';
this.logger.debug(`Mapped user content to ${targetArg.name}: "${userContent.substring(0, 50)}..."`);
}
// Fill remaining arguments with enhanced contextual defaults
for (const arg of promptData.arguments) {
if (!processedArgs[arg.name]) {
const defaultValue = this.resolveEnhancedContextualDefault(arg, context, userContent, promptData);
processedArgs[arg.name] = defaultValue.value;
contextSources[arg.name] = defaultValue.source;
appliedDefaults.push(arg.name);
}
}
// Log the mapping for debugging
this.logger.debug(`Intelligent defaults applied:`, {
promptId: promptData.id,
userContentLength: userContent.length,
targetArgument: targetArg?.name,
totalArguments: promptData.arguments.length,
appliedDefaults
});
}
/**
* Process content specifically for an argument type
*/
private processContentForArgument(content: string, arg: PromptArgument): string {
// Basic content processing - can be enhanced further
const trimmed = content.trim();
// If argument name suggests it wants a specific format, attempt to extract it
if (arg.name.toLowerCase().includes('json') && !trimmed.startsWith('{')) {
// For JSON arguments, wrap simple content appropriately
return `{"content": "${trimmed.replace(/"/g, '\\"')}"}`;
}
if (arg.name.toLowerCase().includes('url') && !trimmed.match(/^https?:\/\//)) {
// Basic URL validation/enhancement could go here
this.logger.debug(`Argument ${arg.name} expects URL but got: ${trimmed.substring(0, 50)}`);
}
return trimmed;
}
/**
* Enhanced contextual default resolver with more intelligence
*/
private resolveEnhancedContextualDefault(
arg: PromptArgument,
context: ExecutionContext,
userContent: string,
promptData: PromptData
): { value: any; source: string } {
// Enhanced strategies with content-aware defaults
const strategies = [
() => this.getFromPromptDefaults(arg, context.promptDefaults),
() => this.getFromEnvironment(arg, context.environmentVars),
() => this.getFromConversationHistory(arg, context.conversationHistory),
() => this.getFromSystemContext(arg, context.systemContext),
() => this.generateContentAwareDefault(arg, userContent, promptData),
() => this.generateSmartDefault(arg)
];
for (const strategy of strategies) {
const result = strategy();
if (result.value !== null && result.value !== undefined && result.value !== '') {
return result;
}
}
// Enhanced fallback with more semantic defaults
return this.generateSemanticFallback(arg);
}
/**
* Generate content-aware defaults based on user input and prompt context
*/
private generateContentAwareDefault(
arg: PromptArgument,
userContent: string,
promptData: PromptData
): { value: any; source: string } {
const argName = arg.name.toLowerCase();
const userLower = userContent.toLowerCase();
// Generate defaults based on argument semantics and user content
if (argName.includes('level') || argName.includes('depth')) {
if (userLower.includes('simple') || userLower.includes('basic')) {
return { value: 'beginner', source: 'content_inference' };
} else if (userLower.includes('complex') || userLower.includes('advanced')) {
return { value: 'expert', source: 'content_inference' };
}
return { value: 'intermediate', source: 'content_inference' };
}
if (argName.includes('format') || argName.includes('type')) {
if (userLower.includes('json') || userContent.includes('{')) {
return { value: 'json', source: 'content_inference' };
} else if (userLower.includes('list') || userLower.includes('bullet')) {
return { value: 'list', source: 'content_inference' };
}
return { value: 'text', source: 'content_inference' };
}
if (argName.includes('style') || argName.includes('tone')) {
if (userLower.includes('formal') || userLower.includes('professional')) {
return { value: 'formal', source: 'content_inference' };
} else if (userLower.includes('casual') || userLower.includes('friendly')) {
return { value: 'casual', source: 'content_inference' };
}
return { value: 'neutral', source: 'content_inference' };
}
if (argName.includes('length') || argName.includes('size')) {
const wordCount = userContent.split(/\s+/).length;
if (wordCount > 100) {
return { value: 'detailed', source: 'content_inference' };
} else if (wordCount < 20) {
return { value: 'brief', source: 'content_inference' };
}
return { value: 'moderate', source: 'content_inference' };
}
return { value: null, source: 'no_content_match' };
}
/**
* Generate semantic fallback defaults
*/
private generateSemanticFallback(arg: PromptArgument): { value: any; source: string } {
const argName = arg.name.toLowerCase();
// Common semantic defaults
const semanticDefaults: Record<string, string> = {
'level': 'intermediate',
'depth': 'moderate',
'format': 'text',
'style': 'neutral',
'tone': 'professional',
'length': 'moderate',
'type': 'analysis',
'mode': 'standard',
'approach': 'systematic',
'focus': 'comprehensive'
};
for (const [keyword, defaultValue] of Object.entries(semanticDefaults)) {
if (argName.includes(keyword)) {
return { value: defaultValue, source: 'semantic_fallback' };
}
}
// Description-based fallback
if (arg.description) {
const desc = arg.description.toLowerCase();
if (desc.includes('required') || desc.includes('must')) {
return { value: '[Please specify]', source: 'required_placeholder' };
}
}
// Final fallback
return { value: '', source: 'empty_fallback' };
}
/**
* Resolve contextual default for an argument (legacy method)
*/
private resolveContextualDefault(
arg: PromptArgument,
context: ExecutionContext
): { value: any; source: string } {
// Priority order for context resolution
const strategies = [
() => this.getFromPromptDefaults(arg, context.promptDefaults),
() => this.getFromEnvironment(arg, context.environmentVars),
() => this.getFromConversationHistory(arg, context.conversationHistory),
() => this.getFromSystemContext(arg, context.systemContext),
() => this.generateSmartDefault(arg)
];
for (const strategy of strategies) {
const result = strategy();
if (result.value !== null && result.value !== undefined) {
return result;
}
}
// Final fallback
return { value: '', source: 'empty_fallback' };
}
/**
* Get default from prompt-specific defaults
*/
private getFromPromptDefaults(
arg: PromptArgument,
promptDefaults?: Record<string, string | number | boolean | null>
): { value: any; source: string } {
if (promptDefaults && promptDefaults[arg.name] !== undefined) {
return { value: promptDefaults[arg.name], source: 'prompt_defaults' };
}
return { value: null, source: 'none' };
}
/**
* Get default from environment variables
*/
private getFromEnvironment(
arg: PromptArgument,
environmentVars?: Record<string, string>
): { value: any; source: string } {
if (environmentVars) {
const envKey = `PROMPT_${arg.name.toUpperCase()}`;
if (environmentVars[envKey]) {
return { value: environmentVars[envKey], source: 'environment' };
}
}
return { value: null, source: 'none' };
}
/**
* Get default from conversation history
*/
private getFromConversationHistory(
arg: PromptArgument,
conversationHistory?: any[]
): { value: any; source: string } {
if (conversationHistory && conversationHistory.length > 0) {
const lastMessage = conversationHistory[conversationHistory.length - 1];
if (lastMessage && lastMessage.content) {
// For content-like arguments, use last message
const contentArgs = ['content', 'text', 'input', 'message', 'query'];
if (contentArgs.some(keyword => arg.name.toLowerCase().includes(keyword))) {
return { value: lastMessage.content, source: 'conversation_history' };
}
}
}
return { value: null, source: 'none' };
}
/**
* Get default from system context
*/
private getFromSystemContext(
arg: PromptArgument,
systemContext?: Record<string, string | number | boolean | null>
): { value: any; source: string } {
if (systemContext && systemContext[arg.name] !== undefined) {
return { value: systemContext[arg.name], source: 'system_context' };
}
return { value: null, source: 'none' };
}
/**
* Generate smart default based on argument characteristics
*/
private generateSmartDefault(arg: PromptArgument): { value: any; source: string } {
// Generate contextual placeholders based on argument name and description
const name = arg.name.toLowerCase();
const description = (arg.description || '').toLowerCase();
if (name.includes('content') || name.includes('text') || name.includes('input')) {
return { value: '[Content will be provided]', source: 'smart_placeholder' };
}
if (name.includes('file') || name.includes('path')) {
return { value: '[File path will be specified]', source: 'smart_placeholder' };
}
if (name.includes('count') || name.includes('number')) {
return { value: '1', source: 'smart_default' };
}
if (name.includes('format') || name.includes('style')) {
return { value: 'default', source: 'smart_default' };
}
// Generic placeholder
return {
value: `[${arg.name} to be provided]`,
source: 'generic_placeholder'
};
}
/**
* Type coercion for arguments based on prompt definitions
*/
private coerceArgumentType(
value: string,
argDef: PromptArgument
): { value: any; wasCoerced: boolean } {
const originalType = typeof value;
// If argument has type hints in description, use them
const description = (argDef.description || '').toLowerCase();
if (description.includes('number') || description.includes('integer')) {
const numValue = Number(value);
if (!isNaN(numValue)) {
return { value: numValue, wasCoerced: originalType !== 'number' };
}
}
if (description.includes('boolean') || value.toLowerCase() === 'true' || value.toLowerCase() === 'false') {
return {
value: value.toLowerCase() === 'true',
wasCoerced: originalType !== 'boolean'
};
}
if (description.includes('array') || description.includes('list') ||
argDef.name.toLowerCase().includes('list') ||
description.includes('A list of') || description.includes('list of')) {
try {
const parsed = JSON.parse(value);
if (Array.isArray(parsed)) {
return { value: parsed, wasCoerced: true };
}
} catch {
// If not valid JSON, split by comma and clean up
const arrayValue = value.split(',').map(item => item.trim()).filter(item => item.length > 0);
return { value: arrayValue, wasCoerced: true };
}
}
// Handle JSON objects
if (description.includes('json') || description.includes('object') ||
description.includes('objects') || value.startsWith('{') || value.startsWith('[')) {
try {
const parsed = JSON.parse(value);
return { value: parsed, wasCoerced: true };
} catch {
// Invalid JSON, keep as string
return { value, wasCoerced: false };
}
}
// No coercion needed or possible
return { value, wasCoerced: false };
}
/**
* Create validation results for processed arguments
*/
private createValidationResults(
processedArgs: Record<string, string | number | boolean | null>,
promptData: PromptData,
existingValidation?: any
): ValidationResult[] {
const results: ValidationResult[] = [];
for (const arg of promptData.arguments) {
const value = processedArgs[arg.name];
const result: ValidationResult = {
argumentName: arg.name,
valid: true,
originalValue: value,
processedValue: value,
appliedRules: [],
warnings: [],
errors: []
};
// Check if argument is required but missing
if (arg.required && (value === undefined || value === null || value === '')) {
result.valid = false;
result.errors = result.errors || [];
result.errors.push({
field: arg.name,
message: `Required argument '${arg.name}' is missing`,
code: 'REQUIRED_ARGUMENT_MISSING',
suggestion: `Please provide a value for argument '${arg.name}'`,
example: `"${arg.name}": "example_value"`
});
}
// Add existing validation errors if any
if (existingValidation && existingValidation.errors) {
result.warnings = result.warnings || [];
result.warnings.push(...existingValidation.errors);
}
results.push(result);
}
return results;
}
/**
* Enrich processing result with additional validation and context
*/
private async enrichResult(
result: ArgumentParsingResult,
promptData: PromptData,
context: ExecutionContext
): Promise<ArgumentParsingResult> {
// Add any additional enrichment logic here
// For now, just return the result as-is
return result;
}
/**
* Update processing statistics
*/
private updateProcessingStats(result: ArgumentParsingResult): void {
this.stats.defaultsApplied += result.metadata.appliedDefaults.length;
this.stats.typeCoercions += result.metadata.typeCoercions.length;
this.stats.contextResolutions += Object.keys(result.metadata.contextSources).length;
}
/**
* Get processing statistics
*/
getStats(): typeof this.stats {
return { ...this.stats };
}
/**
* Reset statistics
*/
resetStats(): void {
this.stats = {
totalProcessed: 0,
successfulProcessing: 0,
validationFailures: 0,
typeCoercions: 0,
defaultsApplied: 0,
contextResolutions: 0
};
}
}
/**
* Factory function to create argument processor
*/
export function createArgumentParser(logger: Logger): ArgumentParser {
return new ArgumentParser(logger);
}
```
--------------------------------------------------------------------------------
/server/src/frameworks/integration/framework-semantic-integration.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Framework-Semantic Integration - Phase 2 Implementation
* Intelligent framework switching and consensus mechanisms
*
* Key Integration Points:
* - Semantic Analysis provides WHAT the prompt needs (complexity, structure, requirements)
* - Framework Manager provides HOW to approach it (methodology, system prompts)
* - Integration layer coordinates between systems WITHOUT interference
*/
import { Logger } from "../../logging/index.js";
import { ConvertedPrompt } from "../../types/index.js";
import { FrameworkManager } from "../framework-manager.js";
import {
FrameworkDefinition,
FrameworkExecutionContext,
FrameworkSelectionCriteria,
FrameworkSwitchingConfig,
FrameworkUsageInsights,
FrameworkSwitchRecommendation,
IntegratedAnalysisResult
} from "../types/index.js";
import {
ContentAnalyzer,
ContentAnalysisResult
} from "../../semantic/configurable-semantic-analyzer.js";
import { FrameworkStateManager } from "../framework-state-manager.js";
import { PromptGuidanceService } from "../prompt-guidance/service.js";
/**
* Integrated analysis result (imported from types/integration-types.js)
*/
/**
* Framework switching configuration (imported from types)
*/
/**
* Framework-Semantic Integration Engine
* Coordinates framework selection based on structural analysis and user preference
*/
export class FrameworkSemanticIntegration {
private frameworkManager: FrameworkManager;
private frameworkStateManager: FrameworkStateManager;
private semanticAnalyzer: ContentAnalyzer;
private logger: Logger;
private config: FrameworkSwitchingConfig;
// Phase 4: Prompt guidance coordination
private promptGuidanceService?: PromptGuidanceService;
// Framework switching state management
private lastFrameworkSwitch = new Map<string, number>();
private frameworkUsageHistory = new Map<string, FrameworkUsageMetrics>();
constructor(
frameworkManager: FrameworkManager,
frameworkStateManager: FrameworkStateManager,
semanticAnalyzer: ContentAnalyzer,
logger: Logger,
config: Partial<FrameworkSwitchingConfig> = {}
) {
this.frameworkManager = frameworkManager;
this.frameworkStateManager = frameworkStateManager;
this.semanticAnalyzer = semanticAnalyzer;
this.logger = logger;
this.config = {
enableAutomaticSwitching: config.enableAutomaticSwitching ?? true,
switchingThreshold: config.switchingThreshold ?? 0.8,
preventThrashing: config.preventThrashing ?? true,
switchingCooldownMs: config.switchingCooldownMs ?? 30000, // 30 second cooldown
blacklistedFrameworks: config.blacklistedFrameworks ?? [],
preferredFrameworks: config.preferredFrameworks ?? []
};
}
/**
* Main integration method - combines semantic analysis with framework selection
* Phase 4: Enhanced with prompt guidance coordination
*/
async analyzeWithFrameworkIntegration(
prompt: ConvertedPrompt,
userFrameworkPreference?: string,
includePromptGuidance?: boolean
): Promise<IntegratedAnalysisResult> {
const startTime = performance.now();
// NEW: Check if framework system is enabled before proceeding
if (!this.frameworkStateManager.isFrameworkSystemEnabled()) {
this.logger.debug(`Framework system disabled - returning semantic analysis only for prompt: ${prompt.id}`);
return this.createNonFrameworkIntegratedResult(prompt, startTime);
}
try {
// Step 1: Perform semantic analysis (WHAT does the prompt need?)
this.logger.debug(`Starting semantic analysis for prompt: ${prompt.id}`);
const semanticAnalysis = await this.semanticAnalyzer.analyzePrompt(prompt);
// Step 2: Check analysis capabilities and adapt accordingly
const analysisCapabilities = semanticAnalysis.capabilities;
this.logger.debug(`Analysis capabilities: semantic=${analysisCapabilities.hasSemanticUnderstanding}, framework=${analysisCapabilities.canRecommendFramework}`);
// Step 3: Enhance framework criteria with user preference and analysis mode
const executionType = semanticAnalysis.executionType;
const enhancedCriteria = this.enhanceFrameworkCriteria(
{
executionType: executionType as "template" | "chain",
complexity: semanticAnalysis.complexity
},
userFrameworkPreference,
semanticAnalysis
);
// Step 4: Framework selection adapted to analysis capabilities
this.logger.debug(`Selecting framework based on semantic criteria (mode: ${semanticAnalysis.analysisMetadata.mode})`);
const frameworkContext = this.selectOptimalFramework(
prompt,
enhancedCriteria,
semanticAnalysis
);
// Step 5: Validate framework-semantic alignment
const alignment = this.validateFrameworkAlignment(semanticAnalysis, frameworkContext);
// Step 6: Generate alternative frameworks (adapted for analysis mode)
const alternatives = this.generateAlternativeFrameworks(enhancedCriteria, frameworkContext, semanticAnalysis);
// Step 6: Build integrated result with optional prompt guidance
const result: IntegratedAnalysisResult = {
semanticAnalysis,
frameworkContext,
integration: {
frameworkSelectionReason: frameworkContext.metadata.selectionReason,
semanticFrameworkAlignment: alignment.overallAlignment,
alternativeFrameworks: alternatives,
consensusMetrics: alignment.detailedMetrics
},
recommendations: this.generateIntegratedRecommendations(
semanticAnalysis,
frameworkContext,
alignment
)
};
// Phase 4: Apply prompt guidance if requested and available
if (includePromptGuidance && this.promptGuidanceService?.isInitialized()) {
try {
const guidanceResult = await this.promptGuidanceService.applyGuidance(prompt, {
includeSystemPromptInjection: true,
includeTemplateEnhancement: true,
frameworkOverride: frameworkContext.selectedFramework.methodology,
semanticAnalysis: semanticAnalysis
});
// Enhance the result with prompt guidance information
result.promptGuidance = {
guidanceApplied: guidanceResult.guidanceApplied,
enhancedPrompt: guidanceResult.enhancedPrompt,
systemPromptInjection: guidanceResult.systemPromptInjection,
templateEnhancement: guidanceResult.templateEnhancement,
processingTimeMs: guidanceResult.processingTimeMs,
confidenceScore: guidanceResult.metadata.confidenceScore
};
this.logger.debug(`Prompt guidance applied with confidence: ${guidanceResult.metadata.confidenceScore}`);
} catch (error) {
this.logger.warn("Failed to apply prompt guidance:", error);
}
}
// Update performance tracking
this.updateFrameworkUsage(
frameworkContext.selectedFramework.id,
performance.now() - startTime,
alignment.overallAlignment
);
this.logger.info(
`Framework integration completed: ${frameworkContext.selectedFramework.name} ` +
`(alignment: ${(alignment.overallAlignment * 100).toFixed(1)}%)`
);
return result;
} catch (error) {
this.logger.error("Framework-semantic integration failed:", error);
return this.createFallbackIntegratedResult(prompt, startTime);
}
}
/**
* Get framework performance insights for optimization
*/
getFrameworkUsageInsights(): FrameworkUsageInsights {
const frameworks = this.frameworkManager.listFrameworks(true);
const insights: FrameworkUsageInsights = {
totalAnalyses: 0,
frameworkUsage: {},
recommendations: []
};
frameworks.forEach(framework => {
const metrics = this.frameworkUsageHistory.get(framework.id);
if (metrics) {
insights.frameworkUsage[framework.id] = {
framework: framework,
...metrics
};
insights.totalAnalyses += metrics.usageCount;
}
});
// Generate optimization recommendations
insights.recommendations = this.generateUsageRecommendations(insights);
return insights;
}
/**
* Intelligent framework switching based on performance and alignment
*/
async evaluateFrameworkSwitch(
prompt: ConvertedPrompt,
currentResult: IntegratedAnalysisResult
): Promise<FrameworkSwitchRecommendation | null> {
if (!this.config.enableAutomaticSwitching) {
return null;
}
// Check if framework context is available (framework system enabled)
if (!currentResult.frameworkContext) {
return null; // Cannot switch if framework system is disabled
}
const currentFramework = currentResult.frameworkContext.selectedFramework;
const alignment = currentResult.integration.semanticFrameworkAlignment;
// Check if switching is warranted
if (alignment >= this.config.switchingThreshold) {
return null; // Current framework is performing well
}
// Check cooldown period to prevent thrashing
if (this.config.preventThrashing) {
const lastSwitch = this.lastFrameworkSwitch.get(prompt.id);
if (lastSwitch && Date.now() - lastSwitch < this.config.switchingCooldownMs) {
return null; // Still in cooldown period
}
}
// Evaluate alternatives
const alternatives = currentResult.integration.alternativeFrameworks;
const bestAlternative = alternatives.find(alt =>
!this.config.blacklistedFrameworks.includes(alt.id) &&
alt.id !== currentFramework.id
);
if (!bestAlternative) {
return null; // No viable alternatives
}
return {
currentFramework: currentFramework,
recommendedFramework: bestAlternative,
reason: `Low alignment (${(alignment * 100).toFixed(1)}%) suggests ${bestAlternative.name} would be more suitable`,
expectedImprovement: this.estimateImprovementPotential(
currentFramework,
bestAlternative,
currentResult.semanticAnalysis
)
};
}
// Private implementation methods
/**
* Enhance framework criteria with user preferences, context, and analysis capabilities
*/
private enhanceFrameworkCriteria(
baseCriteria: FrameworkSelectionCriteria,
userPreference?: string,
semanticAnalysis?: ContentAnalysisResult
): FrameworkSelectionCriteria {
const enhanced = { ...baseCriteria };
// Apply user preference if provided
if (userPreference) {
enhanced.userPreference = userPreference as any;
}
// Handle analysis mode specific logic
if (semanticAnalysis) {
// In structural mode, user choice is more important
if (semanticAnalysis.analysisMetadata.mode === 'structural') {
if (!userPreference && semanticAnalysis.frameworkRecommendation.requiresUserChoice) {
// Log that user choice is needed
this.logger.info("Structural analysis mode - framework selection requires user choice or default");
}
}
// In semantic mode, use intelligent recommendations
if (semanticAnalysis.analysisMetadata.mode === 'semantic' &&
semanticAnalysis.frameworkRecommendation.shouldUseFramework) {
// We can trust the semantic recommendation more
this.logger.debug("Semantic analysis provides framework recommendation");
}
}
// Apply global preferences
if (this.config.preferredFrameworks.length > 0 && !enhanced.userPreference) {
// Don't override user preference, but suggest from preferred list
}
return enhanced;
}
/**
* Select framework using rule-based selection logic and user preference
*/
private selectOptimalFramework(
prompt: ConvertedPrompt,
criteria: FrameworkSelectionCriteria,
semanticAnalysis: ContentAnalysisResult
): FrameworkExecutionContext {
// Use framework manager's selection logic
const frameworkContext = this.frameworkManager.generateExecutionContext(prompt, criteria);
// Log selection reasoning
this.logger.debug(
`Framework selection: ${frameworkContext.selectedFramework.name} ` +
`(reason: ${frameworkContext.metadata.selectionReason})`
);
return frameworkContext;
}
/**
* Validate alignment between semantic analysis and selected framework
*/
private validateFrameworkAlignment(
semanticAnalysis: ContentAnalysisResult,
frameworkContext: FrameworkExecutionContext
): FrameworkAlignmentResult {
const framework = frameworkContext.selectedFramework;
// Calculate alignment scores
const confidenceAlignment = this.calculateConfidenceAlignment(
semanticAnalysis.confidence,
frameworkContext.metadata.confidence
);
const complexityMatch = this.calculateComplexityMatch(
semanticAnalysis.complexity,
framework
);
const executionTypeCompatibility = this.calculateExecutionTypeCompatibility(
semanticAnalysis.executionType,
framework
);
const overallAlignment = (confidenceAlignment + complexityMatch + executionTypeCompatibility) / 3;
return {
overallAlignment,
detailedMetrics: {
confidenceAlignment,
complexityMatch,
executionTypeCompatibility
}
};
}
/**
* Generate alternative framework options for consensus
*/
private generateAlternativeFrameworks(
criteria: FrameworkSelectionCriteria,
currentContext: FrameworkExecutionContext,
semanticAnalysis?: ContentAnalysisResult
): FrameworkDefinition[] {
const allFrameworks = this.frameworkManager.listFrameworks(true);
const currentFramework = currentContext.selectedFramework;
// Return frameworks that are NOT the current one, sorted by suitability
return allFrameworks
.filter(f => f.id !== currentFramework.id)
.filter(f => !this.config.blacklistedFrameworks.includes(f.id))
.slice(0, 3); // Limit to top 3 alternatives
}
/**
* Generate integrated recommendations combining semantic and framework insights
*/
private generateIntegratedRecommendations(
semanticAnalysis: ContentAnalysisResult,
frameworkContext: FrameworkExecutionContext,
alignment: FrameworkAlignmentResult
) {
return {
executionApproach: this.generateExecutionApproach(semanticAnalysis, frameworkContext),
expectedPerformance: {
processingTime: this.estimateProcessingTime(semanticAnalysis),
memoryUsage: this.estimateMemoryUsage(semanticAnalysis),
cacheable: semanticAnalysis.complexity !== "high"
},
qualityAssurance: [
...semanticAnalysis.suggestedGates,
...this.getFrameworkSpecificGates(frameworkContext.selectedFramework)
],
optimizations: this.generateOptimizationSuggestions(semanticAnalysis, frameworkContext, alignment)
};
}
// Helper methods for alignment calculations
private calculateConfidenceAlignment(semanticConfidence: number, frameworkConfidence: number): number {
// How well do the confidence scores align?
const difference = Math.abs(semanticConfidence - frameworkConfidence);
return Math.max(0, 1 - difference);
}
private calculateComplexityMatch(
semanticComplexity: string,
framework: FrameworkDefinition
): number {
// Check if framework is suitable for the complexity level
const complexityScore: Record<string, number> = {
'low': 1,
'medium': 2,
'high': 3
};
const semantic = complexityScore[semanticComplexity] || 2;
// Framework suitability based on methodology
let frameworkSuitability = 2; // Default medium
switch (framework.methodology) {
case 'CAGEERF':
frameworkSuitability = 3; // Best for high complexity
break;
case 'ReACT':
frameworkSuitability = 2.5; // Good for medium-high
break;
case '5W1H':
frameworkSuitability = 2; // Good for medium
break;
case 'SCAMPER':
frameworkSuitability = 1.5; // Best for low-medium
break;
}
const difference = Math.abs(semantic - frameworkSuitability);
return Math.max(0, 1 - difference / 3);
}
private calculateExecutionTypeCompatibility(
executionType: string,
framework: FrameworkDefinition
): number {
// Check if execution type is compatible with framework
if (framework.applicableTypes.length === 0) return 1.0; // Framework supports all types
return framework.applicableTypes.includes(executionType) ? 1.0 : 0.6;
}
// Additional helper methods
private generateExecutionApproach(
semanticAnalysis: ContentAnalysisResult,
frameworkContext: FrameworkExecutionContext
): string {
const baseApproach = `Execute as ${semanticAnalysis.executionType} using ${frameworkContext.selectedFramework.name} methodology`;
// Add mode-specific context
if (semanticAnalysis.analysisMetadata.mode === 'structural') {
return `${baseApproach} (structural analysis mode)`;
} else if (semanticAnalysis.analysisMetadata.mode === 'semantic') {
return `${baseApproach} (intelligent semantic analysis)`;
} else {
return `${baseApproach} (fallback analysis mode)`;
}
}
private getFrameworkSpecificGates(framework: FrameworkDefinition): string[] {
const gates: string[] = [];
// Use actual gate IDs from definitions directory
switch (framework.methodology) {
case 'CAGEERF':
gates.push('framework-compliance', 'technical-accuracy', 'content-structure');
break;
case 'ReACT':
gates.push('framework-compliance', 'educational-clarity');
break;
case '5W1H':
gates.push('framework-compliance', 'research-quality');
break;
case 'SCAMPER':
gates.push('framework-compliance', 'content-structure');
break;
}
return gates;
}
private generateOptimizationSuggestions(
semanticAnalysis: ContentAnalysisResult,
frameworkContext: FrameworkExecutionContext,
alignment: FrameworkAlignmentResult
): string[] {
const suggestions: string[] = [];
if (alignment.overallAlignment < 0.7) {
suggestions.push("Consider framework switching for better alignment");
}
if (semanticAnalysis.complexity === "low") {
suggestions.push("Enable parallel processing for performance improvement");
}
if (semanticAnalysis.confidence > 0.8) {
suggestions.push("Enable caching to improve repeat performance");
}
// Mode-specific suggestions
if (semanticAnalysis.analysisMetadata.mode === 'structural') {
suggestions.push("Consider enabling semantic analysis for intelligent framework recommendations");
if (semanticAnalysis.limitations.length > 0) {
suggestions.push("Enable LLM integration or Claude hooks for better analysis capabilities");
}
}
// Warning-based suggestions
if (semanticAnalysis.warnings.length > 0) {
suggestions.push("Review analysis warnings for potential configuration improvements");
}
return suggestions;
}
/**
* Estimate processing time based on semantic analysis
*/
private estimateProcessingTime(semanticAnalysis: ContentAnalysisResult): number {
let baseTime = 100; // Base processing time in ms
// Adjust based on complexity
switch (semanticAnalysis.complexity) {
case "high":
baseTime *= 3;
break;
case "medium":
baseTime *= 2;
break;
default:
break;
}
// Adjust based on execution type
switch (semanticAnalysis.executionType) {
case "chain":
// Advanced chains with workflow-like features get higher multiplier
if (semanticAnalysis.executionCharacteristics.advancedChainFeatures?.requiresAdvancedExecution) {
baseTime *= 2.5;
} else {
baseTime *= 2;
}
break;
default:
break;
}
return baseTime;
}
/**
* Estimate memory usage based on semantic analysis
*/
private estimateMemoryUsage(semanticAnalysis: ContentAnalysisResult): string {
if (semanticAnalysis.complexity === "high") {
return "high";
} else if (semanticAnalysis.complexity === "medium") {
return "medium";
} else {
return "low";
}
}
private updateFrameworkUsage(
frameworkId: string,
processingTime: number,
alignmentScore: number
): void {
let metrics = this.frameworkUsageHistory.get(frameworkId);
if (!metrics) {
metrics = {
usageCount: 0,
averageProcessingTime: 0,
averageAlignmentScore: 0,
lastUsed: new Date()
};
}
metrics.usageCount++;
metrics.averageProcessingTime = (metrics.averageProcessingTime + processingTime) / 2;
metrics.averageAlignmentScore = (metrics.averageAlignmentScore + alignmentScore) / 2;
metrics.lastUsed = new Date();
this.frameworkUsageHistory.set(frameworkId, metrics);
}
private generateUsageRecommendations(insights: FrameworkUsageInsights): string[] {
const recommendations: string[] = [];
const frameworkUsage = Object.values(insights.frameworkUsage);
if (frameworkUsage.length === 0) return recommendations;
// Find best and worst performing frameworks
const mostUsedFramework = frameworkUsage.reduce((best, current) =>
current.usageCount > best.usageCount ? current : best
);
const leastUsedFramework = frameworkUsage.reduce((worst, current) =>
current.usageCount < worst.usageCount ? current : worst
);
if (mostUsedFramework.usageCount > 10) {
recommendations.push(`Most used framework: ${mostUsedFramework.framework.name} (${mostUsedFramework.usageCount} uses)`);
}
if (leastUsedFramework.usageCount === 0) {
recommendations.push(`Unused framework: ${leastUsedFramework.framework.name} - consider if it's needed`);
}
return recommendations;
}
private estimateImprovementPotential(
currentFramework: FrameworkDefinition,
alternativeFramework: FrameworkDefinition,
semanticAnalysis: ContentAnalysisResult
): number {
// Estimate potential improvement based on framework characteristics
let improvement = 0.1; // Base improvement assumption
// Framework-specific improvements
if (semanticAnalysis.complexity === 'high' && alternativeFramework.methodology === 'CAGEERF') {
improvement += 0.2;
}
if (semanticAnalysis.executionType === 'chain' && alternativeFramework.methodology === 'ReACT') {
improvement += 0.15;
}
return Math.min(improvement, 0.4); // Cap at 40% improvement
}
private async createNonFrameworkIntegratedResult(prompt: ConvertedPrompt, startTime: number): Promise<IntegratedAnalysisResult> {
// When framework system is disabled, provide semantic analysis without framework integration
const semanticAnalysis = await this.semanticAnalyzer.analyzePrompt(prompt);
return {
semanticAnalysis,
frameworkContext: null as any, // No framework context when disabled
integration: {
frameworkSelectionReason: "Framework system disabled",
semanticFrameworkAlignment: 0,
alternativeFrameworks: [],
consensusMetrics: {
confidenceAlignment: 0,
complexityMatch: 0,
executionTypeCompatibility: 0
}
},
recommendations: {
executionApproach: `Execute as ${semanticAnalysis.executionType} without framework methodology`,
expectedPerformance: {
processingTime: this.estimateProcessingTime(semanticAnalysis),
memoryUsage: this.estimateMemoryUsage(semanticAnalysis),
cacheable: semanticAnalysis.complexity !== "high"
},
qualityAssurance: semanticAnalysis.suggestedGates,
optimizations: ["Framework system disabled - using standard execution"]
}
};
}
/**
* Phase 4: Set prompt guidance service for intelligent coordination
*/
setPromptGuidanceService(promptGuidanceService: PromptGuidanceService): void {
this.promptGuidanceService = promptGuidanceService;
this.logger.info("PromptGuidanceService integrated with FrameworkSemanticIntegration");
}
/**
* Phase 4: Check if prompt guidance is available and ready
*/
hasPromptGuidance(): boolean {
return this.promptGuidanceService?.isInitialized() ?? false;
}
/**
* Phase 4: Apply semantic-guided prompt enhancement
*/
async applySemanticGuidedEnhancement(
prompt: ConvertedPrompt,
semanticAnalysis: ContentAnalysisResult,
frameworkContext: FrameworkExecutionContext
): Promise<any> {
if (!this.promptGuidanceService?.isInitialized()) {
this.logger.debug("Prompt guidance service not available for semantic-guided enhancement");
return null;
}
try {
const guidanceResult = await this.promptGuidanceService.applyGuidance(prompt, {
includeSystemPromptInjection: true,
includeTemplateEnhancement: true,
frameworkOverride: frameworkContext.selectedFramework.methodology,
semanticAnalysis: semanticAnalysis
});
return {
enhancedPrompt: guidanceResult.enhancedPrompt,
systemPromptInjection: guidanceResult.systemPromptInjection,
templateEnhancement: guidanceResult.templateEnhancement,
guidanceMetadata: {
semanticAware: guidanceResult.metadata.semanticAware,
semanticComplexity: guidanceResult.metadata.semanticComplexity,
confidenceScore: guidanceResult.metadata.confidenceScore,
enhancementsApplied: guidanceResult.metadata.enhancementsApplied
}
};
} catch (error) {
this.logger.error("Failed to apply semantic-guided enhancement:", error);
return null;
}
}
private createFallbackIntegratedResult(prompt: ConvertedPrompt, startTime: number): IntegratedAnalysisResult {
const fallbackFramework = this.frameworkManager.listFrameworks(true)[0];
return {
semanticAnalysis: {
executionType: "template",
requiresExecution: false,
requiresFramework: false,
confidence: 0.3,
reasoning: ["Fallback analysis"],
capabilities: {
canDetectStructure: false,
canAnalyzeComplexity: false,
canRecommendFramework: false,
hasSemanticUnderstanding: false
},
limitations: ["Fallback analysis with minimal capabilities"],
warnings: ["Analysis failed - using basic fallback"],
executionCharacteristics: {
hasConditionals: false,
hasLoops: false,
hasChainSteps: false,
argumentCount: 0,
templateComplexity: 0,
hasSystemMessage: false,
hasUserTemplate: false,
hasStructuredReasoning: false,
hasMethodologyKeywords: false,
hasComplexAnalysis: false
},
complexity: "low",
suggestedGates: ["basic_validation"],
frameworkRecommendation: {
shouldUseFramework: false,
reasoning: ["Fallback analysis - framework not recommended"],
confidence: 0.9
},
analysisMetadata: {
version: "2.0.0",
mode: "structural",
analysisTime: performance.now() - startTime,
analyzer: "content",
cacheHit: false
}
},
frameworkContext: this.frameworkManager.generateExecutionContext(prompt, {
executionType: "template",
complexity: "low"
}),
integration: {
frameworkSelectionReason: "Fallback selection",
semanticFrameworkAlignment: 0.3,
alternativeFrameworks: [],
consensusMetrics: {
confidenceAlignment: 0.3,
complexityMatch: 0.3,
executionTypeCompatibility: 0.3
}
},
recommendations: {
executionApproach: "Basic template execution",
expectedPerformance: {
processingTime: 100,
memoryUsage: "low",
cacheable: true
},
qualityAssurance: ["basic_validation"],
optimizations: []
}
};
}
}
// Supporting interfaces
interface FrameworkUsageMetrics {
usageCount: number;
averageProcessingTime: number;
averageAlignmentScore: number;
lastUsed: Date;
}
interface FrameworkAlignmentResult {
overallAlignment: number;
detailedMetrics: {
confidenceAlignment: number;
complexityMatch: number;
executionTypeCompatibility: number;
};
}
// Interfaces imported from types/index.js
/**
* Create and configure framework-semantic integration with configurable analyzer
*/
export async function createFrameworkSemanticIntegration(
frameworkManager: FrameworkManager,
frameworkStateManager: FrameworkStateManager,
logger: Logger,
semanticAnalyzer: ContentAnalyzer,
config?: Partial<FrameworkSwitchingConfig>
): Promise<FrameworkSemanticIntegration> {
return new FrameworkSemanticIntegration(frameworkManager, frameworkStateManager, semanticAnalyzer, logger, config);
}
```
--------------------------------------------------------------------------------
/server/src/frameworks/prompt-guidance/template-enhancer.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Template Enhancer - Phase 3 Implementation
*
* Enhances user templates with methodology guidance and framework-specific improvements.
* Extracted from methodology guide enhancement logic for centralized template processing.
*/
import { Logger } from "../../logging/index.js";
import { ConvertedPrompt } from "../../types/index.js";
import {
IMethodologyGuide,
FrameworkDefinition,
TemplateEnhancementResult,
ProcessingGuidance,
TemplateEnhancementConfig
} from "../types/index.js";
import { ContentAnalysisResult } from "../../semantic/configurable-semantic-analyzer.js";
import { LightweightGateSystem } from "../../gates/core/index.js";
/**
* Template enhancement configuration
*/
export interface TemplateEnhancerConfig {
enableArgumentSuggestions: boolean;
enableStructureOptimization: boolean;
enableValidationIntegration: boolean;
enableQualityGates: boolean;
maxSuggestions: number;
enhancementLevel: 'minimal' | 'moderate' | 'comprehensive';
// Phase 4: Semantic awareness settings
enableSemanticAwareness: boolean;
semanticComplexityAdaptation: boolean;
semanticInsightIntegration: boolean;
semanticEnhancementStrategy: 'conservative' | 'moderate' | 'aggressive';
}
/**
* Template enhancement context
*/
export interface TemplateEnhancementContext {
promptName: string;
promptCategory: string;
promptType: string;
existingArguments: string[];
targetAudience?: string;
complexityLevel?: 'low' | 'medium' | 'high';
}
/**
* Template Enhancer
*
* Applies methodology-specific enhancements to user templates,
* providing intelligent suggestions and structural improvements.
*/
export class TemplateEnhancer {
private logger: Logger;
private config: TemplateEnhancerConfig;
private gateSystem?: LightweightGateSystem;
constructor(logger: Logger, config?: Partial<TemplateEnhancerConfig>, gateSystem?: LightweightGateSystem) {
this.logger = logger;
this.gateSystem = gateSystem;
this.config = {
enableArgumentSuggestions: true,
enableStructureOptimization: true,
enableValidationIntegration: true,
enableQualityGates: true,
maxSuggestions: 10,
enhancementLevel: 'moderate',
// Phase 4: Semantic awareness defaults
enableSemanticAwareness: true,
semanticComplexityAdaptation: true,
semanticInsightIntegration: true,
semanticEnhancementStrategy: 'moderate',
...config
};
}
/**
* Enhance template with methodology guidance
* Extracted from methodology guide.guideTemplateProcessing()
* Phase 4: Enhanced with semantic analysis awareness
*/
async enhanceTemplate(
template: string,
prompt: ConvertedPrompt,
methodologyGuide: IMethodologyGuide,
framework: FrameworkDefinition,
context?: TemplateEnhancementContext,
semanticAnalysis?: ContentAnalysisResult
): Promise<TemplateEnhancementResult> {
const startTime = Date.now();
this.logger.debug(`Enhancing template with ${framework.methodology} methodology for ${prompt.name}`);
try {
// Get methodology-specific template processing guidance
const processingGuidance = methodologyGuide.guideTemplateProcessing(
template,
prompt.executionMode || 'template'
);
// Build enhancement context with semantic analysis
const enhancementContext = this.buildEnhancementContext(prompt, context, semanticAnalysis);
// Apply enhancements based on configuration and semantic insights
const enhancedTemplate = await this.applyEnhancements(
template,
processingGuidance,
methodologyGuide,
enhancementContext,
semanticAnalysis
);
// Generate improvement suggestions with semantic insights
const suggestions = this.generateSuggestions(
template,
enhancedTemplate,
processingGuidance,
methodologyGuide,
enhancementContext,
semanticAnalysis
);
// Validate enhanced template with semantic awareness
const validation = this.validateEnhancedTemplate(
enhancedTemplate,
processingGuidance,
methodologyGuide,
semanticAnalysis
);
const result: TemplateEnhancementResult = {
originalTemplate: template,
enhancedTemplate,
suggestions,
processingGuidance,
sourceFramework: framework,
metadata: {
enhancementTime: new Date(),
enhancementLevel: this.config.enhancementLevel,
suggestionsCount: suggestions.length,
validationPassed: validation.passed,
processingTimeMs: Date.now() - startTime,
methodologyApplied: framework.methodology,
// Phase 4: Semantic analysis metadata
semanticAware: semanticAnalysis !== undefined,
semanticComplexity: semanticAnalysis?.complexity,
semanticConfidence: semanticAnalysis?.confidence,
semanticEnhancementsApplied: this.getSemanticEnhancementsApplied(semanticAnalysis)
},
validation
};
this.logger.debug(`Template enhancement completed for ${framework.methodology} in ${result.metadata.processingTimeMs}ms`);
return result;
} catch (error) {
this.logger.error(`Failed to enhance template with ${framework.methodology}:`, error);
// Return fallback result with original template
return {
originalTemplate: template,
enhancedTemplate: template,
suggestions: [],
processingGuidance: {
processingSteps: [],
templateEnhancements: {
systemPromptAdditions: [],
userPromptModifications: [],
contextualHints: []
},
executionFlow: {
preProcessingSteps: [],
postProcessingSteps: [],
validationSteps: []
}
},
sourceFramework: framework,
metadata: {
enhancementTime: new Date(),
enhancementLevel: this.config.enhancementLevel,
suggestionsCount: 0,
validationPassed: false,
processingTimeMs: Date.now() - startTime,
methodologyApplied: framework.methodology,
error: error instanceof Error ? error.message : 'Unknown error'
},
validation: {
passed: false,
score: 0,
issues: [error instanceof Error ? error.message : 'Enhancement failed'],
recommendations: ['Review template structure and methodology compatibility']
}
};
}
}
/**
* Apply methodology-specific enhancements to template
* Phase 4: Enhanced with semantic analysis awareness
*/
private async applyEnhancements(
template: string,
guidance: ProcessingGuidance,
methodologyGuide: IMethodologyGuide,
context: TemplateEnhancementContext,
semanticAnalysis?: ContentAnalysisResult
): Promise<string> {
let enhancedTemplate = template;
// Phase 4: Apply semantic-aware enhancements first
if (this.config.enableSemanticAwareness && semanticAnalysis) {
enhancedTemplate = this.applySemanticAwareEnhancements(
enhancedTemplate,
semanticAnalysis,
methodologyGuide,
context
);
}
// Apply structural improvements based on enhancement level
if (this.config.enableStructureOptimization) {
enhancedTemplate = this.applyStructuralEnhancements(
enhancedTemplate,
guidance.templateEnhancements.contextualHints,
context,
semanticAnalysis
);
}
// FIXED: Remove duplicate methodology structure addition
// The framework system prompt already provides methodology guidance
// Template enhancer should focus on structure optimization, not methodology duplication
// Integrate quality gates if enabled (with semantic complexity awareness)
if (this.config.enableQualityGates && this.shouldApplyQualityGates(semanticAnalysis)) {
enhancedTemplate = await this.integrateQualityGates(
enhancedTemplate,
guidance.executionFlow.validationSteps,
context,
semanticAnalysis
);
}
return enhancedTemplate;
}
/**
* Apply structural enhancements to template
* Phase 4: Enhanced with semantic analysis awareness
*/
private applyStructuralEnhancements(
template: string,
suggestions: string[],
context: TemplateEnhancementContext,
semanticAnalysis?: ContentAnalysisResult
): string {
let enhanced = template;
// Phase 4: Use semantic analysis to guide structural improvements
if (semanticAnalysis && this.config.enableSemanticAwareness) {
// Add structure based on semantic complexity
if (!this.hasStructuredSections(template) && this.shouldAddStructure(semanticAnalysis)) {
enhanced = this.addSemanticAwareStructure(enhanced, context, semanticAnalysis);
}
// Apply suggestions based on semantic characteristics
const semanticFilteredSuggestions = this.filterSuggestionsBySemanticAnalysis(
suggestions,
semanticAnalysis
);
for (const suggestion of semanticFilteredSuggestions.slice(0, this.config.maxSuggestions)) {
enhanced = this.applySuggestion(enhanced, suggestion, context);
}
} else {
// Fallback to original logic
if (!this.hasStructuredSections(template)) {
enhanced = this.addBasicStructure(enhanced, context);
}
for (const suggestion of suggestions.slice(0, this.config.maxSuggestions)) {
enhanced = this.applySuggestion(enhanced, suggestion, context);
}
}
return enhanced;
}
/**
* Add methodology-specific structure to template
* Phase 4: Enhanced with semantic analysis awareness
*/
private addMethodologyStructure(
template: string,
methodologyGuide: IMethodologyGuide,
context: TemplateEnhancementContext,
semanticAnalysis?: ContentAnalysisResult
): string {
const methodology = methodologyGuide.methodology;
let enhanced = template;
// Phase 4: Determine methodology structure complexity based on semantic analysis
const structureLevel = this.determineMethodologyStructureLevel(semanticAnalysis);
// Add methodology-specific sections based on type and semantic complexity
switch (methodology) {
case "CAGEERF":
enhanced = this.addCAGEERFStructure(enhanced, context, structureLevel);
break;
case "ReACT":
enhanced = this.addReACTStructure(enhanced, context, structureLevel);
break;
case "5W1H":
enhanced = this.add5W1HStructure(enhanced, context, structureLevel);
break;
case "SCAMPER":
enhanced = this.addSCAMPERStructure(enhanced, context, structureLevel);
break;
}
return enhanced;
}
/**
* Add CAGEERF methodology structure
* Phase 4: Enhanced with semantic structure levels
*/
private addCAGEERFStructure(
template: string,
context: TemplateEnhancementContext,
structureLevel: 'minimal' | 'moderate' | 'comprehensive' = 'moderate'
): string {
if (template.includes('## Context') || template.includes('## Analysis')) {
return template; // Already has CAGEERF structure
}
// Phase 4: Adapt CAGEERF structure based on semantic complexity
let cageerfSections = '';
switch (structureLevel) {
case 'minimal':
cageerfSections = `
## Context & Analysis
Provide context and analyze the situation.
## Goals & Execution
Define objectives and outline the approach.
## Evaluation
Assess the effectiveness of the solution.
`;
break;
case 'comprehensive':
cageerfSections = `
## Context
Please provide the situational context and background information.
*Consider stakeholders, constraints, and environmental factors.*
## Analysis
Conduct systematic analysis of the situation or problem.
*Use analytical frameworks and identify root causes.*
## Goals
Define specific, measurable objectives and desired outcomes.
*Ensure goals are SMART (Specific, Measurable, Achievable, Relevant, Time-bound).*
## Execution
Outline the implementation approach and action steps.
*Include timelines, resources, and risk mitigation strategies.*
## Evaluation
Assess the effectiveness and quality of the solution.
*Define metrics and evaluation criteria.*
## Refinement
Identify improvement opportunities and optimization strategies.
*Consider feedback loops and continuous improvement.*
## Framework
Document the methodology and approach used.
*Reflect on the CAGEERF process and lessons learned.*
`;
break;
case 'moderate':
default:
cageerfSections = `
## Context
Please provide the situational context and background information.
## Analysis
Conduct systematic analysis of the situation or problem.
## Goals
Define specific, measurable objectives and desired outcomes.
## Execution
Outline the implementation approach and action steps.
## Evaluation
Assess the effectiveness and quality of the solution.
## Refinement
Identify improvement opportunities and optimization strategies.
## Framework
Document the methodology and approach used.
`;
break;
}
return template + cageerfSections;
}
/**
* Add ReACT methodology structure
*/
private addReACTStructure(template: string, context: TemplateEnhancementContext, structureLevel: 'minimal' | 'moderate' | 'comprehensive' = 'moderate'): string {
if (template.includes('## Reasoning') || template.includes('## Action')) {
return template; // Already has ReACT structure
}
const reactSections = `
## Reasoning
Think through the problem systematically and logically.
## Action
Take specific, targeted actions based on the reasoning.
## Observation
Observe the results and gather feedback from actions taken.
`;
return template + reactSections;
}
/**
* Add 5W1H methodology structure
*/
private add5W1HStructure(template: string, context: TemplateEnhancementContext, structureLevel: 'minimal' | 'moderate' | 'comprehensive' = 'moderate'): string {
if (template.includes('## Who') || template.includes('## What')) {
return template; // Already has 5W1H structure
}
const fiveW1HSections = `
## Who
Identify the stakeholders, people involved, and target audience.
## What
Define what needs to be accomplished or addressed.
## When
Establish timelines, deadlines, and scheduling considerations.
## Where
Specify locations, environments, or contexts where this applies.
## Why
Understand the underlying reasons, motivations, and objectives.
## How
Outline the methods, processes, and approaches to be used.
`;
return template + fiveW1HSections;
}
/**
* Add SCAMPER methodology structure
*/
private addSCAMPERStructure(template: string, context: TemplateEnhancementContext, structureLevel: 'minimal' | 'moderate' | 'comprehensive' = 'moderate'): string {
if (template.includes('## Substitute') || template.includes('## Combine')) {
return template; // Already has SCAMPER structure
}
const scamperSections = `
## Substitute
What can be substituted or replaced to improve the solution?
## Combine
What ideas, processes, or elements can be combined?
## Adapt
What can be adapted from other contexts or solutions?
## Modify
What can be modified, magnified, or emphasized?
## Put to Other Uses
How can this be used differently or for other purposes?
## Eliminate
What can be removed, simplified, or minimized?
## Reverse
What can be reversed, rearranged, or approached differently?
`;
return template + scamperSections;
}
/**
* Generate improvement suggestions based on methodology
*/
private generateSuggestions(
originalTemplate: string,
enhancedTemplate: string,
guidance: ProcessingGuidance,
methodologyGuide: IMethodologyGuide,
context: TemplateEnhancementContext,
semanticAnalysis?: ContentAnalysisResult
): string[] {
const suggestions: string[] = [];
// Add argument suggestions if enabled
if (this.config.enableArgumentSuggestions) {
suggestions.push(...guidance.templateEnhancements.userPromptModifications);
}
// Add methodology-specific suggestions
suggestions.push(...this.generateMethodologySpecificSuggestions(
originalTemplate,
methodologyGuide,
context
));
// Add structural suggestions
suggestions.push(...guidance.templateEnhancements.contextualHints);
// Limit suggestions based on configuration
return suggestions.slice(0, this.config.maxSuggestions);
}
/**
* Generate methodology-specific suggestions
*/
private generateMethodologySpecificSuggestions(
template: string,
methodologyGuide: IMethodologyGuide,
context: TemplateEnhancementContext
): string[] {
const suggestions: string[] = [];
const methodology = methodologyGuide.methodology;
// Common suggestions for all methodologies
if (!template.includes('{{')) {
suggestions.push("Consider adding template variables using {{variable}} syntax for dynamic content");
}
if (context.complexityLevel === 'high' && !template.includes('## ')) {
suggestions.push("For complex prompts, consider adding structured sections with markdown headers");
}
// Methodology-specific suggestions
switch (methodology) {
case "CAGEERF":
if (!template.toLowerCase().includes('context')) {
suggestions.push("Consider adding a Context section to establish situational background");
}
if (!template.toLowerCase().includes('goal')) {
suggestions.push("Define specific Goals to guide the analysis and execution");
}
break;
case "ReACT":
if (!template.toLowerCase().includes('reason')) {
suggestions.push("Include reasoning steps to make thought processes explicit");
}
if (!template.toLowerCase().includes('action')) {
suggestions.push("Specify concrete actions to take based on reasoning");
}
break;
case "5W1H":
const missing5W1H = ['who', 'what', 'when', 'where', 'why', 'how'].filter(
w => !template.toLowerCase().includes(w)
);
if (missing5W1H.length > 0) {
suggestions.push(`Consider addressing: ${missing5W1H.join(', ')} for comprehensive analysis`);
}
break;
case "SCAMPER":
if (!template.toLowerCase().includes('creative')) {
suggestions.push("Emphasize creative thinking and alternative approaches");
}
break;
}
return suggestions;
}
/**
* Integrate quality gates into template (Phase 2 enhancement)
*/
private async integrateQualityGates(
template: string,
qualityGates: string[],
context: TemplateEnhancementContext,
semanticAnalysis?: ContentAnalysisResult
): Promise<string> {
if (qualityGates.length === 0) {
return template;
}
// Load actual gate guidance if gate system is available
let gateGuidance: string[] = [];
if (this.gateSystem) {
try {
gateGuidance = await this.gateSystem.getGuidanceText(
qualityGates,
{
promptCategory: context.promptCategory,
framework: "CAGEERF", // Default framework for gate context
explicitRequest: true
}
);
} catch (error) {
this.logger.warn("Failed to load gate guidance:", error);
// Fallback to gate IDs if guidance loading fails
gateGuidance = qualityGates.map(gateId => `Gate: ${gateId}`);
}
} else {
// Fallback: use gate IDs when no gate system available
gateGuidance = qualityGates.map(gateId => `Quality criterion: ${gateId}`);
}
const qualitySection = `
## Quality Validation
Please ensure the following quality criteria are met:
${gateGuidance.map(guidance => `- ${guidance}`).join('\n')}
`;
return template + qualitySection;
}
/**
* Validate enhanced template
*/
private validateEnhancedTemplate(
template: string,
guidance: ProcessingGuidance,
methodologyGuide: IMethodologyGuide,
semanticAnalysis?: ContentAnalysisResult
): {
passed: boolean;
score: number;
issues: string[];
recommendations: string[];
} {
const issues: string[] = [];
const recommendations: string[] = [];
let score = 100;
// Check template length
if (template.length < 50) {
issues.push("Template is too short for effective guidance");
score -= 20;
}
if (template.length > 5000) {
issues.push("Template is very long and may be difficult to use");
score -= 10;
recommendations.push("Consider breaking into smaller, focused sections");
}
// Check for template variables
const variableCount = (template.match(/\{\{[^}]+\}\}/g) || []).length;
if (variableCount === 0 && this.config.enableArgumentSuggestions) {
issues.push("No template variables found - template may not be dynamic enough");
score -= 15;
recommendations.push("Add {{variable}} placeholders for user input");
}
// Check for structure
if (!this.hasStructuredSections(template)) {
issues.push("Template lacks clear structure");
score -= 15;
recommendations.push("Add section headers to organize content");
}
// Check methodology integration
const methodology = methodologyGuide.methodology.toLowerCase();
if (!template.toLowerCase().includes(methodology)) {
issues.push(`Methodology ${methodologyGuide.methodology} not clearly integrated`);
score -= 10;
}
// Ensure minimum score
score = Math.max(score, 0);
return {
passed: issues.length === 0,
score,
issues,
recommendations
};
}
/**
* Build enhancement context from prompt and user context
* Phase 4: Enhanced with semantic analysis integration
*/
private buildEnhancementContext(
prompt: ConvertedPrompt,
userContext?: TemplateEnhancementContext,
semanticAnalysis?: ContentAnalysisResult
): TemplateEnhancementContext {
return {
promptName: prompt.name || 'Unnamed Prompt',
promptCategory: prompt.category || 'general',
promptType: prompt.executionMode || 'template',
existingArguments: prompt.arguments?.map(arg => arg.name) || [],
complexityLevel: this.assessComplexityWithSemantics(prompt, semanticAnalysis),
...userContext
};
}
/**
* Assess prompt complexity
*/
private assessComplexity(prompt: ConvertedPrompt): 'low' | 'medium' | 'high' {
const argCount = prompt.arguments?.length || 0;
const contentLength = prompt.userMessageTemplate?.length || 0;
if (argCount >= 5 || contentLength > 1000) return 'high';
if (argCount >= 3 || contentLength > 500) return 'medium';
return 'low';
}
/**
* Check if template has structured sections
*/
private hasStructuredSections(template: string): boolean {
return /^##\s+/.test(template) || template.includes('\n## ');
}
/**
* Add basic structure to unstructured template
*/
private addBasicStructure(template: string, context: TemplateEnhancementContext): string {
return `## ${context.promptName}
${template}
## Output Requirements
Please provide a comprehensive response that addresses all aspects of this prompt.
`;
}
/**
* Apply a specific suggestion to template
*/
private applySuggestion(template: string, suggestion: string, context: TemplateEnhancementContext): string {
// This is a simplified implementation - in practice, this would contain
// more sophisticated suggestion application logic
return template;
}
/**
* Update enhancer configuration
*/
updateConfig(config: Partial<TemplateEnhancerConfig>): void {
this.config = { ...this.config, ...config };
this.logger.debug('TemplateEnhancer configuration updated', config);
}
/**
* Get current enhancer configuration
*/
getConfig(): TemplateEnhancerConfig {
return { ...this.config };
}
// Phase 4: Semantic-aware enhancement methods
/**
* Apply semantic-aware enhancements based on analysis results
*/
private applySemanticAwareEnhancements(
template: string,
semanticAnalysis: ContentAnalysisResult,
methodologyGuide: IMethodologyGuide,
context: TemplateEnhancementContext
): string {
let enhanced = template;
// Apply complexity-based enhancements
switch (semanticAnalysis.complexity) {
case 'high':
enhanced = this.applyHighComplexityEnhancements(enhanced, semanticAnalysis, context);
break;
case 'medium':
enhanced = this.applyMediumComplexityEnhancements(enhanced, semanticAnalysis, context);
break;
case 'low':
enhanced = this.applyLowComplexityEnhancements(enhanced, semanticAnalysis, context);
break;
}
// Apply execution characteristic-based enhancements
if (semanticAnalysis.executionCharacteristics.hasStructuredReasoning) {
enhanced = this.addReasoningStructure(enhanced);
}
if (semanticAnalysis.executionCharacteristics.hasComplexAnalysis) {
enhanced = this.addAnalysisStructure(enhanced, methodologyGuide);
}
return enhanced;
}
/**
* Determine methodology structure level based on semantic analysis
*/
private determineMethodologyStructureLevel(
semanticAnalysis?: ContentAnalysisResult
): 'minimal' | 'moderate' | 'comprehensive' {
if (!semanticAnalysis || !this.config.enableSemanticAwareness) {
return this.config.enhancementLevel;
}
// Base decision on semantic complexity and confidence
const complexityScore = this.calculateSemanticComplexityScore(semanticAnalysis);
if (complexityScore >= 0.8) {
return 'comprehensive';
} else if (complexityScore >= 0.5) {
return 'moderate';
} else {
return 'minimal';
}
}
/**
* Calculate semantic complexity score for structure decisions
*/
private calculateSemanticComplexityScore(semanticAnalysis: ContentAnalysisResult): number {
let score = 0;
// Base complexity mapping
switch (semanticAnalysis.complexity) {
case 'high': score += 0.6; break;
case 'medium': score += 0.4; break;
case 'low': score += 0.2; break;
}
// Execution characteristics influence
const chars = semanticAnalysis.executionCharacteristics;
if (chars.hasStructuredReasoning) score += 0.1;
if (chars.hasComplexAnalysis) score += 0.1;
if (chars.hasChainSteps) score += 0.1;
if (chars.argumentCount > 3) score += 0.1;
// Confidence influence
score += (semanticAnalysis.confidence * 0.2);
return Math.min(score, 1.0);
}
/**
* Assess complexity with semantic analysis integration
*/
private assessComplexityWithSemantics(
prompt: ConvertedPrompt,
semanticAnalysis?: ContentAnalysisResult
): 'low' | 'medium' | 'high' {
if (semanticAnalysis && this.config.semanticComplexityAdaptation) {
return semanticAnalysis.complexity;
}
// Fallback to original assessment
return this.assessComplexity(prompt);
}
/**
* Determine if structure should be added based on semantic analysis
*/
private shouldAddStructure(semanticAnalysis: ContentAnalysisResult): boolean {
// Always add structure for high complexity
if (semanticAnalysis.complexity === 'high') return true;
// Add structure if has structured reasoning characteristics
if (semanticAnalysis.executionCharacteristics.hasStructuredReasoning) return true;
// Add structure if has complex analysis patterns
if (semanticAnalysis.executionCharacteristics.hasComplexAnalysis) return true;
// Add structure for medium complexity with high confidence
if (semanticAnalysis.complexity === 'medium' && semanticAnalysis.confidence > 0.8) return true;
return false;
}
/**
* Add semantic-aware structure to template
*/
private addSemanticAwareStructure(
template: string,
context: TemplateEnhancementContext,
semanticAnalysis: ContentAnalysisResult
): string {
const structureType = this.determineOptimalStructureType(semanticAnalysis);
switch (structureType) {
case 'analytical':
return this.addAnalyticalStructure(template, context);
case 'procedural':
return this.addProceduralStructure(template, context);
case 'creative':
return this.addCreativeStructure(template, context);
default:
return this.addBasicStructure(template, context);
}
}
/**
* Filter suggestions based on semantic analysis
*/
private filterSuggestionsBySemanticAnalysis(
suggestions: string[],
semanticAnalysis: ContentAnalysisResult
): string[] {
// Prioritize suggestions based on semantic characteristics
const prioritizedSuggestions = suggestions.map(suggestion => ({
suggestion,
priority: this.calculateSuggestionPriority(suggestion, semanticAnalysis)
}));
return prioritizedSuggestions
.sort((a, b) => b.priority - a.priority)
.map(item => item.suggestion);
}
/**
* Calculate suggestion priority based on semantic analysis
*/
private calculateSuggestionPriority(
suggestion: string,
semanticAnalysis: ContentAnalysisResult
): number {
let priority = 1;
// Higher priority for structure suggestions if template has structural reasoning
if (suggestion.includes('structure') && semanticAnalysis.executionCharacteristics.hasStructuredReasoning) {
priority += 2;
}
// Higher priority for analysis suggestions if template has complex analysis
if (suggestion.includes('analysis') && semanticAnalysis.executionCharacteristics.hasComplexAnalysis) {
priority += 2;
}
// Higher priority for variable suggestions based on argument count
if (suggestion.includes('variable') && semanticAnalysis.executionCharacteristics.argumentCount > 2) {
priority += 1;
}
return priority;
}
/**
* Determine if quality gates should be applied based on semantic analysis
*/
private shouldApplyQualityGates(semanticAnalysis?: ContentAnalysisResult): boolean {
if (!semanticAnalysis || !this.config.enableSemanticAwareness) {
return this.config.enableQualityGates && this.config.enhancementLevel === 'comprehensive';
}
// Apply quality gates for high complexity or high confidence scenarios
return (
semanticAnalysis.complexity === 'high' ||
(semanticAnalysis.complexity === 'medium' && semanticAnalysis.confidence > 0.8) ||
semanticAnalysis.executionCharacteristics.hasComplexAnalysis
);
}
/**
* Get semantic enhancements applied for metadata
*/
private getSemanticEnhancementsApplied(semanticAnalysis?: ContentAnalysisResult): string[] {
if (!semanticAnalysis || !this.config.enableSemanticAwareness) {
return [];
}
const enhancements = [];
if (this.config.semanticComplexityAdaptation) {
enhancements.push(`complexity-${semanticAnalysis.complexity}`);
}
if (semanticAnalysis.executionCharacteristics.hasStructuredReasoning) {
enhancements.push('structured-reasoning');
}
if (semanticAnalysis.executionCharacteristics.hasComplexAnalysis) {
enhancements.push('complex-analysis');
}
if (semanticAnalysis.confidence > 0.8) {
enhancements.push('high-confidence');
}
return enhancements;
}
// Helper methods for complexity-based enhancements
private applyHighComplexityEnhancements(
template: string,
semanticAnalysis: ContentAnalysisResult,
context: TemplateEnhancementContext
): string {
// Add comprehensive structure and validation for high complexity
return template;
}
private applyMediumComplexityEnhancements(
template: string,
semanticAnalysis: ContentAnalysisResult,
context: TemplateEnhancementContext
): string {
// Add moderate structure and guidance for medium complexity
return template;
}
private applyLowComplexityEnhancements(
template: string,
semanticAnalysis: ContentAnalysisResult,
context: TemplateEnhancementContext
): string {
// Apply minimal enhancements for low complexity
return template;
}
private addReasoningStructure(template: string): string {
if (!template.includes('## Reasoning') && !template.includes('## Analysis')) {
return template + '\n\n## Reasoning\nPlease think through this step-by-step:\n\n1. \n2. \n3. ';
}
return template;
}
private addAnalysisStructure(template: string, methodologyGuide: IMethodologyGuide): string {
if (!template.includes('## Analysis')) {
return template + `\n\n## Analysis\nApply ${methodologyGuide.methodology} systematic analysis:\n\n- \n- \n- `;
}
return template;
}
private determineOptimalStructureType(semanticAnalysis: ContentAnalysisResult): string {
if (semanticAnalysis.executionCharacteristics.hasComplexAnalysis) return 'analytical';
if (semanticAnalysis.executionCharacteristics.hasChainSteps) return 'procedural';
if (semanticAnalysis.executionCharacteristics.hasMethodologyKeywords) return 'creative';
return 'basic';
}
private addAnalyticalStructure(template: string, context: TemplateEnhancementContext): string {
return `## ${context.promptName} - Analytical Framework
${template}
## Analysis Steps
1. Define the problem or question
2. Gather relevant information
3. Apply analytical methods
4. Draw conclusions
5. Validate results
## Expected Output
Provide a structured analysis with clear reasoning and evidence.
`;
}
private addProceduralStructure(template: string, context: TemplateEnhancementContext): string {
return `## ${context.promptName} - Procedural Framework
${template}
## Process Steps
1. Preparation
2. Execution
3. Validation
4. Documentation
## Expected Output
Provide step-by-step results with clear progression.
`;
}
private addCreativeStructure(template: string, context: TemplateEnhancementContext): string {
return `## ${context.promptName} - Creative Framework
${template}
## Creative Process
1. Explore possibilities
2. Generate alternatives
3. Evaluate options
4. Refine solutions
## Expected Output
Provide innovative solutions with creative reasoning.
`;
}
}
/**
* Create and configure a TemplateEnhancer instance
*/
export function createTemplateEnhancer(
logger: Logger,
config?: Partial<TemplateEnhancerConfig>,
gateSystem?: LightweightGateSystem
): TemplateEnhancer {
return new TemplateEnhancer(logger, config, gateSystem);
}
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/prompt-manager/core/manager.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Consolidated Prompt Manager - Modular Architecture Orchestration Layer
*
* This class maintains 100% backwards compatibility with the original API
* while delegating operations to specialized modules for improved maintainability.
*/
import { Logger } from "../../../logging/index.js";
import { ConfigManager } from "../../../config/index.js";
import {
ToolResponse,
ConvertedPrompt,
PromptData,
Category
} from "../../../types/index.js";
import {
ValidationError,
PromptError,
handleError as utilsHandleError
} from "../../../utils/index.js";
import { ContentAnalyzer } from "../../../semantic/configurable-semantic-analyzer.js";
import { FrameworkStateManager } from "../../../frameworks/framework-state-manager.js";
import { FrameworkManager } from "../../../frameworks/framework-manager.js";
import { createPromptResponse, createErrorResponse } from "../../shared/structured-response-builder.js";
// Modular components
import {
PromptManagerDependencies,
PromptManagerData,
PromptClassification
} from "./types.js";
import { validateRequiredFields } from "../utils/validation.js";
import { PromptAnalyzer } from "../analysis/prompt-analyzer.js";
import { ComparisonEngine } from "../analysis/comparison-engine.js";
import { GateAnalyzer } from "../analysis/gate-analyzer.js";
import { FilterParser } from "../search/filter-parser.js";
import { PromptMatcher } from "../search/prompt-matcher.js";
import { FileOperations } from "../operations/file-operations.js";
/**
* Consolidated Prompt Manager - Modular Architecture
*/
export class ConsolidatedPromptManager {
private logger: Logger;
private mcpServer: any;
private configManager: ConfigManager;
private semanticAnalyzer: ContentAnalyzer;
private frameworkStateManager?: FrameworkStateManager;
private frameworkManager?: FrameworkManager;
private onRefresh: () => Promise<void>;
private onRestart: (reason: string) => Promise<void>;
// Modular components
private promptAnalyzer: PromptAnalyzer;
private comparisonEngine: ComparisonEngine;
private gateAnalyzer: GateAnalyzer;
private filterParser: FilterParser;
private promptMatcher: PromptMatcher;
private fileOperations: FileOperations;
// Data references
private promptsData: PromptData[] = [];
private convertedPrompts: ConvertedPrompt[] = [];
private categories: Category[] = [];
constructor(
logger: Logger,
mcpServer: any,
configManager: ConfigManager,
semanticAnalyzer: ContentAnalyzer,
frameworkStateManager: FrameworkStateManager | undefined,
frameworkManager: FrameworkManager | undefined,
onRefresh: () => Promise<void>,
onRestart: (reason: string) => Promise<void>
) {
this.logger = logger;
this.mcpServer = mcpServer;
this.configManager = configManager;
this.semanticAnalyzer = semanticAnalyzer;
this.frameworkStateManager = frameworkStateManager;
this.frameworkManager = frameworkManager;
this.onRefresh = onRefresh;
this.onRestart = onRestart;
// Initialize modular components
const dependencies: PromptManagerDependencies = {
logger,
mcpServer,
configManager,
semanticAnalyzer,
frameworkStateManager,
frameworkManager,
onRefresh,
onRestart
};
this.promptAnalyzer = new PromptAnalyzer(dependencies);
this.comparisonEngine = new ComparisonEngine(logger);
this.gateAnalyzer = new GateAnalyzer(dependencies);
this.filterParser = new FilterParser(logger);
this.promptMatcher = new PromptMatcher(logger);
this.fileOperations = new FileOperations(dependencies);
this.logger.debug("ConsolidatedPromptManager initialized with modular architecture");
}
/**
* Update data references
*/
updateData(
promptsData: PromptData[],
convertedPrompts: ConvertedPrompt[],
categories: Category[]
): void {
this.promptsData = promptsData;
this.convertedPrompts = convertedPrompts;
this.categories = categories;
// Update modular components that need data references
const data: PromptManagerData = {
promptsData,
convertedPrompts,
categories
};
// Components handle their own data updates if needed
this.logger.debug(`Updated data references: ${promptsData.length} prompts, ${categories.length} categories`);
}
/**
* Set framework state manager (called during initialization)
*/
setFrameworkStateManager(frameworkStateManager: FrameworkStateManager): void {
this.frameworkStateManager = frameworkStateManager;
this.logger.debug("Framework state manager set in PromptManager");
}
/**
* Set framework manager (called during initialization)
*/
setFrameworkManager(frameworkManager: FrameworkManager): void {
this.frameworkManager = frameworkManager;
this.logger.debug("Framework manager set in PromptManager");
}
/**
* Main action handler - Routes to appropriate modules
*/
public async handleAction(args: {
action: "create" | "create_prompt" | "create_template" | "analyze_type" | "migrate_type" | "update" | "delete" | "modify" | "reload" | "list" | "analyze_gates" | "suggest_temporary_gates" | "create_with_gates" | "update_gates" | "add_temporary_gates";
[key: string]: any;
}, extra: any): Promise<ToolResponse> {
const { action } = args;
// USING ERROR LEVEL FOR GUARANTEED VISIBILITY IN LOGS
this.logger.error(`[GATE-TRACE] 🚀 ENTRY POINT: handleAction called with action "${action}"`);
this.logger.error(`[GATE-TRACE] Gate config present: ${!!args.gate_configuration}, Type: ${typeof args.gate_configuration}`);
this.logger.info(`📝 Prompt Manager: Executing action "${action}"`);
try {
switch (action) {
case "create":
return await this.createPrompt(args);
case "create_prompt":
return await this.createBasicPrompt(args);
case "create_template":
return await this.createFrameworkTemplate(args);
case "analyze_type":
return await this.analyzePromptType(args);
case "migrate_type":
return await this.migratePromptType(args);
case "update":
return await this.updatePrompt(args);
case "delete":
return await this.deletePrompt(args);
case "modify":
return await this.modifyPrompt(args);
case "reload":
return await this.reloadPrompts(args);
case "list":
return await this.listPrompts(args);
case "analyze_gates":
return await this.analyzePromptGates(args);
case "suggest_temporary_gates":
return await this.suggestTemporaryGates(args);
case "create_with_gates":
return await this.createPromptWithGates(args);
case "update_gates":
return await this.updatePromptGates(args);
case "add_temporary_gates":
return await this.addTemporaryGates(args);
default:
throw new ValidationError(`Unknown action: ${action}`);
}
} catch (error) {
return this.handleError(error, action);
}
}
/**
* Create new prompt (delegates to file operations and analysis)
*/
private async createPrompt(args: any): Promise<ToolResponse> {
validateRequiredFields(args, ['id', 'name', 'description', 'user_message_template']);
// Create prompt data with enhanced gate configuration support
const promptData: any = {
id: args.id,
name: args.name,
category: args.category || 'general',
description: args.description,
systemMessage: args.system_message,
userMessageTemplate: args.user_message_template,
arguments: args.arguments || [],
isChain: args.is_chain || false,
chainSteps: args.chain_steps || [],
gateConfiguration: args.gate_configuration || args.gates
};
// USING ERROR LEVEL FOR GUARANTEED VISIBILITY
this.logger.error(`[GATE-TRACE] 📋 createPrompt constructed promptData for ${args.id}`);
this.logger.error(`[GATE-TRACE] promptData final structure:`, {
id: promptData.id,
hasGateConfiguration: !!promptData.gateConfiguration,
gateConfigType: typeof promptData.gateConfiguration,
gateConfigValue: promptData.gateConfiguration,
argsGateConfig: args.gate_configuration,
argsGates: args.gates
});
this.logger.error(`[GATE-TRACE] 📁 Calling fileOperations.updatePromptImplementation for ${args.id}`);
const result = await this.fileOperations.updatePromptImplementation(promptData);
// Perform intelligent analysis
const analysis = await this.promptAnalyzer.analyzePromptIntelligence(promptData);
let response = `✅ **Prompt Created**: ${args.name} (${args.id})\n`;
response += `📝 ${args.description}\n`;
response += `${analysis.feedback}`;
if (analysis.suggestions.length > 0) {
response += `💡 ${analysis.suggestions.join(' • ')}\n`;
}
// Enhanced: Gate configuration analysis and suggestions
if (promptData.gateConfiguration) {
response += `\n🔒 **Gate Configuration Applied**:\n`;
if (promptData.gateConfiguration.include) {
response += `- Include Gates: ${promptData.gateConfiguration.include.join(', ')}\n`;
}
if (promptData.gateConfiguration.temporary_gates) {
response += `- Temporary Gates: ${promptData.gateConfiguration.temporary_gates.length} defined\n`;
}
} else if (this.semanticAnalyzer.isLLMEnabled()) {
// Suggest gate configuration for prompts without gates (only when API analysis is enabled)
try {
const gateAnalysis = await this.gateAnalyzer.analyzePromptForGates({
id: promptData.id,
name: promptData.name,
category: promptData.category,
description: promptData.description,
userMessageTemplate: promptData.userMessageTemplate,
systemMessage: promptData.systemMessage,
arguments: promptData.arguments || []
});
if (gateAnalysis.recommendedGates.length > 0) {
response += `\n💡 **Suggested Gates**: Consider adding these gates:\n`;
gateAnalysis.recommendedGates.slice(0, 3).forEach(gate => {
response += `- ${gate}\n`;
});
response += `Use \`update_gates\` action to add gate configuration.\n`;
}
} catch (error) {
this.logger.warn('Failed to analyze gates for new prompt:', error);
}
}
await this.handleSystemRefresh(args.full_restart, `Prompt created: ${args.id}`);
return createPromptResponse(response, "create", {
promptId: args.id,
category: args.category,
analysisResult: analysis,
affectedFiles: [`${args.id}.md`]
});
}
/**
* Update existing prompt (delegates to file operations and comparison)
*/
private async updatePrompt(args: any): Promise<ToolResponse> {
validateRequiredFields(args, ['id']);
// Get current prompt for comparison
const currentPrompt = this.convertedPrompts.find(p => p.id === args.id);
let beforeAnalysis: PromptClassification | null = null;
if (currentPrompt) {
beforeAnalysis = await this.promptAnalyzer.analyzePrompt(currentPrompt);
}
// Update prompt data with enhanced gate configuration support
const promptData: any = {
id: args.id,
name: args.name || currentPrompt?.name || args.id,
category: args.category || currentPrompt?.category || 'general',
description: args.description || currentPrompt?.description || '',
systemMessage: args.system_message || currentPrompt?.systemMessage,
userMessageTemplate: args.user_message_template || currentPrompt?.userMessageTemplate || '',
arguments: args.arguments || currentPrompt?.arguments || [],
chainSteps: args.chain_steps || currentPrompt?.chainSteps || [],
gateConfiguration: args.gate_configuration || args.gates || currentPrompt?.gateConfiguration
};
const result = await this.fileOperations.updatePromptImplementation(promptData);
// Perform analysis comparison
const afterAnalysis = await this.promptAnalyzer.analyzePromptIntelligence(promptData);
let response = `✅ **Prompt Updated**: ${promptData.name} (${args.id})\n\n`;
response += `${result.message}\n\n`;
response += `${afterAnalysis.feedback}\n`;
// Add comparison if we have before analysis
if (beforeAnalysis) {
const comparison = this.comparisonEngine.compareAnalyses(beforeAnalysis, afterAnalysis.classification, args.id);
const displaySummary = this.comparisonEngine.generateDisplaySummary(comparison);
if (displaySummary) {
response += `\n${displaySummary}\n`;
}
}
if (afterAnalysis.suggestions.length > 0) {
response += `\n💡 **Improvement Suggestions**:\n`;
afterAnalysis.suggestions.forEach((suggestion, i) => {
response += `${i + 1}. ${suggestion}\n`;
});
}
await this.handleSystemRefresh(args.full_restart, `Prompt updated: ${args.id}`);
return createPromptResponse(response, "update", {
promptId: args.id,
category: promptData.category,
analysisResult: afterAnalysis,
affectedFiles: [`${args.id}.md`]
});
}
/**
* Delete prompt with safety checks (delegates to file operations)
*/
private async deletePrompt(args: any): Promise<ToolResponse> {
validateRequiredFields(args, ['id']);
const promptToDelete = this.promptsData.find(p => p.id === args.id);
if (!promptToDelete) {
throw new PromptError(`Prompt not found: ${args.id}`);
}
// Safety check - analyze dependencies
const dependencies = this.findPromptDependencies(args.id);
let response = `🗑️ **Deleting Prompt**: ${promptToDelete.name} (${args.id})\n\n`;
if (dependencies.length > 0) {
response += `⚠️ **Warning**: This prompt is referenced by ${dependencies.length} other prompts:\n`;
dependencies.forEach(dep => {
response += `- ${dep.name} (${dep.id})\n`;
});
response += `\nDeleting will break these chain references.\n\n`;
}
const result = await this.fileOperations.deletePromptImplementation(args.id);
response += `${result.message}\n\n`;
response += `✅ **Prompt successfully removed from system**\n`;
await this.handleSystemRefresh(args.full_restart, `Prompt deleted: ${args.id}`);
return createPromptResponse(response, "delete", {
promptId: args.id,
category: promptToDelete.category,
affectedFiles: [`${args.id}.md`]
});
}
/**
* List prompts with intelligent filtering (delegates to search modules)
*/
private async listPrompts(args: any): Promise<ToolResponse> {
console.log(`[DEBUG] List prompts called with search_query: "${args.search_query || ''}"`);
const filters = this.filterParser.parseIntelligentFilters(args.search_query || '');
console.log(`[DEBUG] Parsed filters:`, filters);
const matchingPrompts: Array<{
prompt: any;
classification: any;
}> = [];
// Process all prompts using matcher
console.log(`[DEBUG] Processing ${this.convertedPrompts.length} prompts`);
for (const prompt of this.convertedPrompts) {
try {
const classification = await this.promptAnalyzer.analyzePrompt(prompt);
console.log(`[DEBUG] Analyzing prompt ${prompt.id}, type: ${classification.executionType}`);
// Apply filters using matcher
const matches = await this.promptMatcher.matchesFilters(prompt, filters, classification);
console.log(`[DEBUG] Prompt ${prompt.id} matches: ${matches}`);
if (matches) {
matchingPrompts.push({ prompt, classification });
}
} catch (error) {
this.logger.warn(`Failed to analyze prompt ${prompt.id}:`, error);
}
}
// Sort by relevance
matchingPrompts.sort((a, b) => {
const scoreA = this.promptMatcher.calculateRelevanceScore(a.prompt, a.classification, filters);
const scoreB = this.promptMatcher.calculateRelevanceScore(b.prompt, b.classification, filters);
return scoreB - scoreA; // Higher scores first
});
if (matchingPrompts.length === 0) {
return createPromptResponse(
`📭 No prompts found matching filter: "${args.search_query || 'all'}"\n\n💡 Try broader search terms or use filters like 'type:template', 'category:analysis'`,
"list",
{
promptId: "none",
category: "all",
affectedFiles: []
}
);
}
// Generate response using existing format
let result = `📚 **Prompt Library** (${matchingPrompts.length} prompts)\n\n`;
// Group by category for better organization
const groupedByCategory = matchingPrompts.reduce((acc, item) => {
const category = item.prompt.category || 'uncategorized';
if (!acc[category]) acc[category] = [];
acc[category].push(item);
return acc;
}, {} as Record<string, typeof matchingPrompts>);
for (const [category, prompts] of Object.entries(groupedByCategory)) {
result += `\n## 📁 ${category.toUpperCase()}\n`;
for (const { prompt, classification } of prompts) {
const executionIcon = this.getExecutionTypeIcon(classification.executionType);
const frameworkIcon = classification.requiresFramework ? '🧠' : '⚡';
result += `\n**${executionIcon} ${prompt.name}** \`${prompt.id}\`\n`;
result += ` ${frameworkIcon} **Type**: ${classification.executionType}\n`;
if (prompt.description) {
const shortDesc = prompt.description.length > 80
? prompt.description.substring(0, 80) + '...'
: prompt.description;
result += ` 📝 ${shortDesc}\n`;
}
if (prompt.arguments?.length > 0) {
result += ` 🔧 **Args**: ${prompt.arguments.map((arg: any) => arg.name).join(', ')}\n`;
}
}
}
// Add filter summary if filters were applied
if (args.filter) {
const filterDescriptions = this.filterParser.buildFilterDescription(filters);
if (filterDescriptions.length > 0) {
result += `\n\n🔍 **Applied Filters**:\n`;
filterDescriptions.forEach(desc => {
result += `- ${desc}\n`;
});
}
}
result += `\n\n💡 **Usage Tips**:\n`;
result += `• Use \`>>prompt_id\` to execute prompts\n`;
result += `• Use \`analyze_type\` to get type recommendations\n`;
result += `• Use \`migrate_type\` to convert between prompt/template\n`;
return createPromptResponse(result, "list_intelligent", {
promptId: "multiple",
category: "all"
});
}
/**
* Analyze prompt type (delegates to analysis module)
*/
private async analyzePromptType(args: any): Promise<ToolResponse> {
validateRequiredFields(args, ['id']);
const prompt = this.convertedPrompts.find(p => p.id === args.id);
if (!prompt) {
return createErrorResponse(`Prompt not found: ${args.id}`, {
tool: "prompt_manager",
operation: "analyze_type",
errorType: "validation",
severity: "medium"
});
}
const analysis = await this.promptAnalyzer.analyzePrompt(prompt);
let recommendation = `🔍 **Prompt Type Analysis**: ${prompt.name}\n\n`;
recommendation += `📊 **Current Execution Type**: ${analysis.executionType}\n`;
recommendation += `🧠 **Framework Recommended**: ${analysis.requiresFramework ? 'Yes' : 'No'}\n\n`;
recommendation += `📋 **Analysis Details**:\n`;
analysis.reasoning.forEach((reason, i) => {
recommendation += `${i + 1}. ${reason}\n`;
});
recommendation += `\n🔄 **Recommendations**:\n`;
if (analysis.executionType === 'prompt' && analysis.requiresFramework) {
recommendation += `⬆️ **Consider upgrading to template**: This prompt would benefit from framework guidance\n`;
recommendation += `💡 **Migration**: Use \`migrate_type\` action to convert to template\n`;
} else if (analysis.executionType === 'template' && !analysis.requiresFramework) {
recommendation += `⬇️ **Consider simplifying to prompt**: This might be over-engineered for its use case\n`;
recommendation += `💡 **Migration**: Use \`migrate_type\` action to convert to basic prompt\n`;
} else {
recommendation += `✅ **Well-aligned**: Current execution type matches content appropriately\n`;
}
if (analysis.suggestedGates.length > 0) {
recommendation += `\n🔒 **Suggested Quality Gates**: ${analysis.suggestedGates.join(', ')}\n`;
}
return createPromptResponse(recommendation, "analyze_type", {
promptId: args.id,
analysisResult: { classification: analysis, feedback: '', suggestions: [] }
});
}
// Additional helper methods (maintaining original API)
private async createBasicPrompt(args: any): Promise<ToolResponse> {
// Implementation delegated to createPrompt with specific mode
return this.createPrompt({
...args,
executionMode: 'prompt'
});
}
private async createFrameworkTemplate(args: any): Promise<ToolResponse> {
// Implementation delegated to createPrompt with framework context
return this.createPrompt({
...args,
executionMode: 'template'
});
}
private async migratePromptType(args: any): Promise<ToolResponse> {
// Simplified implementation - could be expanded with migration module
validateRequiredFields(args, ['id', 'target_type']);
const prompt = this.convertedPrompts.find(p => p.id === args.id);
if (!prompt) {
return createErrorResponse(`Prompt not found: ${args.id}`, {
tool: "prompt_manager",
operation: "migrate_type",
errorType: "validation",
severity: "medium"
});
}
return createPromptResponse(
`🔄 Migration from ${prompt.id} to ${args.target_type} would be implemented here`,
"migrate_type",
{ promptId: args.id }
);
}
private async modifyPrompt(args: any): Promise<ToolResponse> {
// Simplified implementation - full modify logic could be in operations module
validateRequiredFields(args, ['id', 'section_name', 'new_content']);
return createPromptResponse(
`✏️ **Section Modified**: ${args.section_name} in ${args.id}`,
"modify",
{ promptId: args.id }
);
}
private async reloadPrompts(args: any): Promise<ToolResponse> {
const reason = args.reason || "Manual reload requested";
let response = `🔄 **Reloading Prompts System**\n\n`;
response += `**Reason**: ${reason}\n`;
response += `**Mode**: ${args.full_restart ? 'Full Server Restart' : 'Hot Reload'}\n\n`;
if (args.full_restart) {
setTimeout(() => this.onRestart(reason), 1000);
response += `⚡ **Server restart initiated**... Please wait for reconnection.\n`;
} else {
await this.onRefresh();
response += `✅ **Hot reload completed** - All prompts refreshed from disk.\n`;
}
return createPromptResponse(response, "reload", {
promptId: "system",
affectedFiles: args.full_restart ? ["server"] : ["prompts"]
});
}
// Helper methods
private findPromptDependencies(promptId: string): ConvertedPrompt[] {
return this.convertedPrompts.filter(prompt => {
if (!prompt.chainSteps || prompt.chainSteps.length === 0) return false;
return prompt.chainSteps.some((step: any) => step.promptId === promptId);
});
}
private getExecutionTypeIcon(executionType: string): string {
switch (executionType) {
case 'prompt': return '⚡';
case 'template': return '🧠';
case 'chain': return '🔗';
default: return '❓';
}
}
private async handleSystemRefresh(fullRestart: boolean = false, reason: string): Promise<void> {
if (fullRestart) {
setTimeout(() => this.onRestart(reason), 1000);
} else {
await this.onRefresh();
}
}
/**
* Analyze prompt gates and provide recommendations
*/
private async analyzePromptGates(args: any): Promise<ToolResponse> {
validateRequiredFields(args, ['id']);
const prompt = this.convertedPrompts.find(p => p.id === args.id);
if (!prompt) {
return createErrorResponse(`Prompt not found: ${args.id}`, {
tool: "prompt_manager",
operation: "analyze_gates",
errorType: "validation",
severity: "medium"
});
}
const analysis = await this.gateAnalyzer.analyzePromptForGates(prompt);
let response = `🔒 **Gate Analysis**: ${prompt.name}\n\n`;
response += `📊 **Analysis Summary**:\n`;
response += `- **Confidence**: ${Math.round(analysis.confidence * 100)}%\n`;
response += `- **Recommended Gates**: ${analysis.recommendedGates.length}\n`;
response += `- **Suggested Temporary Gates**: ${analysis.suggestedTemporaryGates.length}\n\n`;
if (analysis.recommendedGates.length > 0) {
response += `🎯 **Recommended Persistent Gates**:\n`;
analysis.recommendedGates.forEach(gate => {
response += `- ${gate}\n`;
});
response += `\n`;
}
if (analysis.suggestedTemporaryGates.length > 0) {
response += `⚡ **Suggested Temporary Gates**:\n`;
analysis.suggestedTemporaryGates.forEach(gate => {
response += `- **${gate.name}** (${gate.type}, ${gate.scope})\n`;
response += ` ${gate.description}\n`;
});
response += `\n`;
}
if (analysis.reasoning.length > 0) {
response += `🧠 **Analysis Reasoning**:\n`;
analysis.reasoning.forEach((reason, i) => {
response += `${i + 1}. ${reason}\n`;
});
response += `\n`;
}
response += `📋 **Suggested Gate Configuration**:\n`;
response += `\`\`\`json\n${JSON.stringify(analysis.gateConfigurationPreview, null, 2)}\n\`\`\`\n`;
return createPromptResponse(response, "analyze_gates", {
promptId: args.id,
category: prompt.category,
analysisResult: analysis
});
}
/**
* Suggest temporary gates for execution context
*/
private async suggestTemporaryGates(args: any): Promise<ToolResponse> {
validateRequiredFields(args, ['execution_context']);
const context = args.execution_context;
const suggestedGates = await this.gateAnalyzer.suggestGatesForContext(context);
let response = `⚡ **Temporary Gate Suggestions**\n\n`;
response += `📋 **Context**: ${context.executionType} execution in ${context.category} category\n`;
response += `🎚️ **Complexity**: ${context.complexity}\n\n`;
if (suggestedGates.length > 0) {
response += `🔒 **Suggested Gates**:\n`;
suggestedGates.forEach((gate, i) => {
response += `${i + 1}. ${gate}\n`;
});
} else {
response += `ℹ️ No specific gate suggestions for this context - default gates will apply.\n`;
}
response += `\n💡 **Usage**: Use these suggestions when creating or updating prompts to ensure appropriate quality gates are applied.\n`;
return createPromptResponse(response, "suggest_temporary_gates", {
promptId: "context-based",
category: context.category || "general",
analysisResult: { suggestions: suggestedGates }
});
}
/**
* Create prompt with enhanced gate configuration
*/
private async createPromptWithGates(args: any): Promise<ToolResponse> {
// USING ERROR LEVEL FOR GUARANTEED VISIBILITY
this.logger.error(`[GATE-TRACE] 🎯 createPromptWithGates called for prompt: ${args.id}`);
this.logger.error(`[GATE-TRACE] Gate config raw data:`, {
hasGateConfig: !!args.gate_configuration,
gateConfigType: typeof args.gate_configuration,
gateConfigRaw: args.gate_configuration,
hasSuggestedGates: !!args.suggested_gates
});
validateRequiredFields(args, ['id', 'name', 'description', 'user_message_template']);
// Validate and parse gate configuration
let gateConfiguration: any = null;
if (args.gate_configuration) {
this.logger.info(`[GATE-DEBUG] Processing gate_configuration for ${args.id}`);
try {
gateConfiguration = typeof args.gate_configuration === 'string'
? JSON.parse(args.gate_configuration)
: args.gate_configuration;
this.logger.debug(`[GATE-DEBUG] Parsed gate configuration:`, gateConfiguration);
} catch (error) {
this.logger.error(`[GATE-DEBUG] Failed to parse gate configuration:`, error);
throw new ValidationError(`Invalid gate configuration JSON: ${error instanceof Error ? error.message : String(error)}`);
}
} else if (args.suggested_gates) {
this.logger.info(`[GATE-DEBUG] Auto-generating from suggested_gates for ${args.id}`);
// Auto-generate basic gate configuration from suggested gates
// Extract gate names from gate objects
const gateNames = Array.isArray(args.suggested_gates)
? args.suggested_gates.map((gate: any) => gate.name)
: [args.suggested_gates.name];
gateConfiguration = {
include: gateNames,
framework_gates: true
};
this.logger.debug(`[GATE-DEBUG] Auto-generated gate configuration with extracted names:`, gateConfiguration);
} else {
this.logger.warn(`[GATE-DEBUG] No gate configuration or suggested gates found for ${args.id}`);
}
// Create prompt with gates
const enhancedArgs = {
...args,
gate_configuration: gateConfiguration
};
this.logger.debug(`[GATE-DEBUG] Enhanced args being passed to createPrompt:`, {
id: enhancedArgs.id,
hasGateConfig: !!enhancedArgs.gate_configuration,
gateConfigContent: enhancedArgs.gate_configuration
});
return await this.createPrompt(enhancedArgs);
}
/**
* Update gate configuration for existing prompt
*/
private async updatePromptGates(args: any): Promise<ToolResponse> {
validateRequiredFields(args, ['id']);
const currentPrompt = this.convertedPrompts.find(p => p.id === args.id);
if (!currentPrompt) {
throw new PromptError(`Prompt not found: ${args.id}`);
}
// Parse new gate configuration
let gateConfiguration: any = null;
if (args.gate_configuration) {
try {
gateConfiguration = typeof args.gate_configuration === 'string'
? JSON.parse(args.gate_configuration)
: args.gate_configuration;
} catch (error) {
throw new ValidationError(`Invalid gate configuration JSON: ${error instanceof Error ? error.message : String(error)}`);
}
}
// Update only the gate configuration
const updateArgs = {
id: args.id,
gate_configuration: gateConfiguration
};
const result = await this.updatePrompt(updateArgs);
let response = `🔧 **Gate Configuration Updated**: ${currentPrompt.name} (${args.id})\n\n`;
response += `✅ Gate configuration has been updated successfully.\n`;
if (gateConfiguration) {
response += `📋 **Applied Configuration**:\n`;
if (gateConfiguration.include) {
response += `- Include Gates: ${gateConfiguration.include.join(', ')}\n`;
}
if (gateConfiguration.exclude) {
response += `- Exclude Gates: ${gateConfiguration.exclude.join(', ')}\n`;
}
if (gateConfiguration.temporary_gates) {
response += `- Temporary Gates: ${gateConfiguration.temporary_gates.length} gates defined\n`;
}
response += `- Framework Gates: ${gateConfiguration.framework_gates !== false ? 'Enabled' : 'Disabled'}\n`;
}
return createPromptResponse(response, "update_gates", {
promptId: args.id,
category: currentPrompt.category,
analysisResult: { gateConfiguration }
});
}
/**
* Add temporary gates to existing prompt configuration
* Phase 3 Fix: This now adds gates to in-memory configuration only (no file writes)
* Gates are truly temporary and will be activated during prompt execution
*/
private async addTemporaryGates(args: any): Promise<ToolResponse> {
validateRequiredFields(args, ['id', 'temporary_gates']);
const currentPrompt = this.convertedPrompts.find(p => p.id === args.id);
if (!currentPrompt) {
throw new PromptError(`Prompt not found: ${args.id}`);
}
// Parse temporary gates
let temporaryGates: any[];
try {
temporaryGates = typeof args.temporary_gates === 'string'
? JSON.parse(args.temporary_gates)
: args.temporary_gates;
if (!Array.isArray(temporaryGates)) {
throw new Error("temporary_gates must be an array");
}
} catch (error) {
throw new ValidationError(`Invalid temporary gates configuration: ${error instanceof Error ? error.message : String(error)}`);
}
// Phase 3 Fix: Update in-memory configuration only - NO FILE WRITES
// This makes gates truly temporary - they exist only in memory and expire/cleanup automatically
// Use enhancedGateConfiguration which supports temporary_gates
const existingGateConfig = currentPrompt.enhancedGateConfiguration || currentPrompt.gateConfiguration || {};
currentPrompt.enhancedGateConfiguration = {
...existingGateConfig,
temporary_gates: temporaryGates,
gate_scope: args.gate_scope || 'execution',
inherit_chain_gates: args.inherit_chain_gates !== false
};
this.logger.info(`[TEMP GATES] Added ${temporaryGates.length} temporary gates to ${args.id} (in-memory only, no file write)`, {
promptId: args.id,
gateCount: temporaryGates.length,
scope: args.gate_scope || 'execution'
});
let response = `⚡ **Temporary Gates Added (In-Memory)**: ${currentPrompt.name} (${args.id})\n\n`;
response += `✅ ${temporaryGates.length} temporary gates added to in-memory configuration.\n`;
response += `⚠️ **Note**: Gates are temporary and will NOT be written to disk. They expire after use.\n\n`;
response += `🔒 **Added Temporary Gates**:\n`;
temporaryGates.forEach((gate, i) => {
response += `${i + 1}. **${gate.name}** (${gate.type}, ${gate.scope})\n`;
response += ` - ${gate.description}\n`;
});
response += `\n📋 **Configuration**:\n`;
response += `- Gate Scope: ${args.gate_scope || 'execution'}\n`;
response += `- Inherit Chain Gates: ${args.inherit_chain_gates !== false ? 'Yes' : 'No'}\n`;
response += `- Persistence: In-memory only (no file writes)\n`;
response += `- Lifecycle: Will be auto-activated on next prompt execution\n`;
return createPromptResponse(response, "add_temporary_gates", {
promptId: args.id,
category: currentPrompt.category,
analysisResult: {
temporaryGatesAdded: temporaryGates.length,
inMemoryOnly: true,
gateConfiguration: currentPrompt.enhancedGateConfiguration
}
});
}
private handleError(error: unknown, context: string): ToolResponse {
const { message, isError } = utilsHandleError(error, context, this.logger);
return createErrorResponse(message, {
tool: "prompt_manager",
operation: context,
errorType: "system",
severity: "medium"
});
}
}
/**
* Create consolidated prompt manager - maintains original factory function API
*/
export function createConsolidatedPromptManager(
logger: Logger,
mcpServer: any,
configManager: ConfigManager,
semanticAnalyzer: ContentAnalyzer,
frameworkStateManager: FrameworkStateManager | undefined,
frameworkManager: FrameworkManager | undefined,
onRefresh: () => Promise<void>,
onRestart: (reason: string) => Promise<void>
): ConsolidatedPromptManager {
return new ConsolidatedPromptManager(
logger,
mcpServer,
configManager,
semanticAnalyzer,
frameworkStateManager,
frameworkManager,
onRefresh,
onRestart
);
}
```
--------------------------------------------------------------------------------
/plans/nunjucks-dynamic-chain-orchestration.md:
--------------------------------------------------------------------------------
```markdown
# Nunjucks Dynamic Chain Orchestration - Comprehensive Implementation Plan
**Created**: 2025-10-05
**Status**: Planning
**Priority**: High - Strategic Architecture Enhancement
**Impact**: Enables result-based adaptive prompts, quality-driven chains, dynamic execution flows
## Executive Summary
**Critical Discovery**: Nunjucks templates render on EACH chain step with access to previous step results. This enables powerful result-based conditional logic and adaptive prompt instructions that we're currently not leveraging.
**Core Opportunity**: Transform static chain steps into intelligent, adaptive prompts that modify their behavior based on:
- Previous step quality scores
- Validation results from earlier steps
- Accumulated complexity metrics
- Error conditions and recovery needs
- Content characteristics discovered during execution
**Strategic Goal**: Build a sophisticated chain orchestration system where prompts intelligently adapt their instructions, depth, and approach based on runtime results.
---
## Table of Contents
1. [Current State Analysis](#current-state-analysis)
2. [Nunjucks Capabilities in Chains](#nunjucks-capabilities-in-chains)
3. [Result-Based Conditional Patterns](#result-based-conditional-patterns)
4. [Quality-Driven Adaptive Prompts](#quality-driven-adaptive-prompts)
5. [Implementation Strategy](#implementation-strategy)
6. [Example Transformations](#example-transformations)
7. [Best Practices & Patterns](#best-practices--patterns)
8. [Performance Considerations](#performance-considerations)
9. [Future Enhancements](#future-enhancements)
---
## Current State Analysis
### What We Have Now
**Chain Execution Flow (Actual)**:
```
Step 1: analysis_step
→ Load template "analysis_step.md"
→ Render with Nunjucks (variables: {input: "user data"})
→ Execute with LLM
→ Output: {analysis: "detailed analysis", confidence: 0.85}
Step 2: validation_step
→ Load template "validation_step.md"
→ Render with Nunjucks (variables: {
analysis: "detailed analysis",
confidence: 0.85,
quality_threshold: 0.8
})
→ Execute with LLM
→ Output: {validation_score: 0.6, issues: ["accuracy", "citations"]}
Step 3: refinement_step
→ Load template "refinement_step.md"
→ Render with Nunjucks (variables: {
analysis: "detailed analysis",
validation_score: 0.6,
issues: ["accuracy", "citations"]
})
→ Execute with LLM
→ Output: {refined_analysis: "improved analysis"}
```
**Key Insight**: Each step receives ALL previous step outputs as variables!
### What We're NOT Using
**Current Prompt Pattern** (Passive):
```markdown
# Refinement Step
Refine this analysis: {{analysis}}
Previous validation score: {{validation_score}}
Issues identified: {{issues}}
Please improve the analysis addressing the identified issues.
```
**What Nunjucks Enables** (Active):
```markdown
# Refinement Step
Refine this analysis: {{analysis}}
{% if validation_score < 0.7 %}
## ⚠️ CRITICAL QUALITY ISSUES DETECTED
Validation Score: {{validation_score}} (Target: ≥0.80)
### Priority Issues Requiring Immediate Attention:
{% for issue in issues %}
- **{{issue}}**: Apply comprehensive remediation
{% endfor %}
### Enhanced Refinement Protocol:
1. **Evidence Strengthening**: Add authoritative citations for all claims
2. **Accuracy Verification**: Cross-reference facts against reliable sources
3. **Clarity Enhancement**: Restructure unclear sections with examples
4. **Completeness Check**: Address all gaps identified in validation
5. **Quality Validation**: Self-assess against original standards
**Target Outcome**: Achieve validation score ≥0.80 with zero critical issues.
{% elif validation_score < 0.9 %}
## Moderate Improvement Required
Validation Score: {{validation_score}} (Good, targeting excellence)
### Issues to Address:
{% for issue in issues %}
- {{issue}}
{% endfor %}
Apply targeted refinements:
- Enhance clarity where needed
- Add supporting examples for complex concepts
- Strengthen key arguments with additional evidence
{% else %}
## Excellent Quality - Final Polish
Validation Score: {{validation_score}} (Excellent!)
Apply publication-ready polish:
- Fine-tune language for professional tone
- Ensure consistent terminology
- Add visual formatting enhancements
- Optimize for reader comprehension
{% endif %}
---
**Original Analysis:**
{{analysis}}
**Refinement Instructions**: Focus your improvements based on the quality level indicated above.
```
**The Difference**:
- **Passive**: LLM sees data, decides what to do
- **Active**: Template provides specific, quality-appropriate instructions
---
## Nunjucks Capabilities in Chains
### 1. Result-Based Conditionals
**Access Previous Step Outputs**:
```nunjucks
{% if previous_step_output.contains("error") %}
{# Error handling instructions #}
{% elif previous_step_output.quality_score < threshold %}
{# Quality improvement instructions #}
{% else %}
{# Standard processing instructions #}
{% endif %}
```
**Available in Step Context**:
- All outputs from previous steps (mapped by outputMapping)
- Original input variables
- Chain configuration parameters
- Step execution metadata
### 2. Complexity-Driven Adaptation
**Calculate from Accumulated State**:
```nunjucks
{% set total_items = sources|length + topics|length + constraints|length %}
{% set complexity_level = "low" %}
{% if total_items > 20 %}
{% set complexity_level = "maximum" %}
{% elif total_items > 10 %}
{% set complexity_level = "high" %}
{% elif total_items > 5 %}
{% set complexity_level = "standard" %}
{% endif %}
{% if complexity_level == "maximum" %}
## 🔥 MAXIMUM COMPLEXITY ANALYSIS REQUIRED
With {{total_items}} factors to consider, apply systematic framework:
### Phase 1: Categorization
- Group sources by type and relevance
- Map topic relationships and dependencies
- Prioritize constraints by impact
### Phase 2: Deep Analysis
[Detailed complex analysis instructions...]
### Phase 3: Synthesis
[Complex synthesis instructions...]
{% elif complexity_level == "high" %}
## ⚡ HIGH COMPLEXITY ANALYSIS
{{total_items}} factors identified. Apply structured analysis:
[Moderate complexity instructions...]
{% else %}
## 📊 STANDARD ANALYSIS
Focus on core insights from {{total_items}} key factors:
[Simple analysis instructions...]
{% endif %}
```
### 3. Quality-Based Instruction Customization
**Adapt Depth Based on Previous Quality**:
```nunjucks
{% if step2_quality_score > 0.9 %}
{# High quality - proceed with advanced analysis #}
Apply sophisticated analytical frameworks and advanced methodologies...
{% elif step2_quality_score > 0.7 %}
{# Moderate quality - provide structured guidance #}
Follow this systematic approach to build upon the foundation...
{% else %}
{# Low quality - provide detailed step-by-step instructions #}
Use this detailed framework with explicit examples at each step...
{% endif %}
```
### 4. Error Recovery and Adaptive Routing
**Handle Validation Failures**:
```nunjucks
{% if validation_result.passed == false %}
## 🚨 VALIDATION FAILURE - RECOVERY MODE ACTIVATED
**Failed Checks**:
{% for check in validation_result.failed_checks %}
- {{check.name}}: {{check.reason}}
{% endfor %}
### Recovery Protocol:
{% if "accuracy" in validation_result.failed_checks|map(attribute='name') %}
**Accuracy Issues Detected**
1. Verify all factual claims against authoritative sources
2. Remove or qualify uncertain statements
3. Add citations for key claims
{% endif %}
{% if "completeness" in validation_result.failed_checks|map(attribute='name') %}
**Completeness Issues Detected**
1. Review requirements checklist: {{validation_result.requirements}}
2. Identify and address gaps
3. Ensure comprehensive coverage
{% endif %}
[Additional recovery instructions based on specific failures...]
{% else %}
{# Validation passed - proceed normally #}
{% endif %}
```
### 5. Accumulated State Tracking
**Use History from Multiple Steps**:
```nunjucks
{# Step 5 has access to outputs from Steps 1-4 #}
{% if step1_analysis.insights|length > 10 and step3_validation.score > 0.8 %}
{# High quality, rich content - apply advanced synthesis #}
{% elif step2_research.sources|length < 3 %}
{# Limited sources - acknowledge and adapt #}
Note: Analysis based on {{step2_research.sources|length}} sources.
Apply appropriate confidence qualifiers...
{% endif %}
```
---
## Result-Based Conditional Patterns
### Pattern 1: Quality Score Adaptation
**Use Case**: Adjust refinement depth based on validation results
**Chain Definition**:
```json
{
"steps": [
{
"promptId": "initial_analysis",
"outputMapping": {"analysis": "initial_output"}
},
{
"promptId": "quality_validation",
"inputMapping": {"content": "initial_output"},
"outputMapping": {"score": "quality_score", "issues": "quality_issues"}
},
{
"promptId": "adaptive_refinement",
"inputMapping": {
"original": "initial_output",
"score": "quality_score",
"issues": "quality_issues"
}
}
]
}
```
**Prompt Template** (`adaptive_refinement.md`):
```nunjucks
# Adaptive Refinement
Original Content: {{original}}
Quality Score: {{score}}
{% if score < 0.6 %}
## 🔴 COMPREHENSIVE REBUILD REQUIRED
Score: {{score}}/1.0 - Below acceptable threshold
### Critical Issues:
{% for issue in issues %}
- {{issue.category}}: {{issue.description}}
**Action Required**: {{issue.remedy}}
{% endfor %}
### Rebuild Protocol:
1. Restart analysis from first principles
2. Apply rigorous methodology for each issue category
3. Implement all recommended remedies
4. Self-validate before submission
Expected Outcome: Achieve minimum score of 0.75
{% elif score < 0.8 %}
## 🟡 TARGETED IMPROVEMENTS NEEDED
Score: {{score}}/1.0 - Good foundation, needs enhancement
### Focus Areas:
{% for issue in issues %}
- {{issue.category}}: {{issue.description}}
{% endfor %}
### Improvement Strategy:
1. Address each issue systematically
2. Enhance clarity and supporting evidence
3. Strengthen weak areas identified above
Target Score: ≥0.85
{% else %}
## 🟢 MINOR REFINEMENTS
Score: {{score}}/1.0 - Excellent quality
Polish for publication:
- Fine-tune language precision
- Enhance readability and flow
- Add final professional touches
{% endif %}
```
### Pattern 2: Error-Driven Recovery
**Use Case**: Adapt to errors in previous steps
**Template Pattern**:
```nunjucks
{% if previous_error %}
## Error Recovery Mode
Error Type: {{previous_error.type}}
Error Message: {{previous_error.message}}
{% if previous_error.type == "missing_data" %}
### Data Recovery Strategy:
1. Identify alternative data sources
2. Proceed with available information
3. Clearly document limitations
4. Provide qualified conclusions
{% elif previous_error.type == "validation_failure" %}
### Validation Recovery:
1. Review failed validation criteria: {{previous_error.failed_criteria}}
2. Address each criterion systematically
3. Re-validate after corrections
{% elif previous_error.type == "timeout" %}
### Timeout Recovery:
Previous step timed out. Simplify approach:
1. Reduce scope to essential elements
2. Apply streamlined methodology
3. Focus on high-priority outputs
{% endif %}
{% else %}
{# No error - proceed normally #}
[Standard instructions]
{% endif %}
```
### Pattern 3: Complexity Escalation
**Use Case**: Increase analysis depth if initial attempt is insufficient
**Multi-Step Chain**:
```json
{
"steps": [
{"promptId": "quick_analysis", "outputMapping": {"result": "quick_result", "complexity": "detected_complexity"}},
{"promptId": "assessment", "outputMapping": {"adequate": "is_sufficient"}},
{"promptId": "deep_analysis_conditional", "inputMapping": {
"quick_result": "quick_result",
"adequate": "is_sufficient",
"complexity": "detected_complexity"
}}
]
}
```
**Template** (`deep_analysis_conditional.md`):
```nunjucks
{% if adequate == false or detected_complexity > 7 %}
## Deep Analysis Required
Initial analysis: {{quick_result}}
Complexity Level: {{detected_complexity}}/10
Assessment: Insufficient depth
### Enhanced Analysis Framework:
{% if detected_complexity > 8 %}
**MAXIMUM DEPTH ANALYSIS**
1. Multi-dimensional examination
2. Cross-referencing from multiple perspectives
3. Advanced pattern recognition
4. Predictive implications analysis
{% else %}
**STANDARD DEEP ANALYSIS**
1. Comprehensive examination
2. Relationship mapping
3. Implication analysis
{% endif %}
{% else %}
## Quick Analysis Sufficient
Initial result meets requirements:
{{quick_result}}
Apply minor enhancements only.
{% endif %}
```
### Pattern 4: Format Adaptation
**Use Case**: Change output format based on content characteristics
**Template**:
```nunjucks
{% set content_type = "unknown" %}
{% if "code" in step1_output or "function" in step1_output %}
{% set content_type = "technical" %}
{% elif "story" in step1_output or "narrative" in step1_output %}
{% set content_type = "narrative" %}
{% elif "data" in step1_output or "metric" in step1_output %}
{% set content_type = "analytical" %}
{% endif %}
{% if content_type == "technical" %}
## Technical Documentation Format
Content: {{step1_output}}
Structure as:
- Code examples with syntax highlighting
- API reference format
- Technical specifications table
{% elif content_type == "narrative" %}
## Narrative Format
Content: {{step1_output}}
Structure as:
- Story-driven presentation
- Chronological flow
- Engaging narrative elements
{% elif content_type == "analytical" %}
## Analytical Report Format
Content: {{step1_output}}
Structure as:
- Executive summary
- Data visualizations
- Statistical analysis
- Recommendations
{% endif %}
```
---
## Quality-Driven Adaptive Prompts
### Architecture
**Quality Assessment → Adaptive Instructions → Validated Output**
```
┌─────────────────┐
│ Input Data │
└────────┬────────┘
↓
┌─────────────────┐
│ Step 1: │
│ Initial Work │
└────────┬────────┘
↓
┌─────────────────┐
│ Step 2: │
│ Quality Check │
│ (outputs score)│
└────────┬────────┘
↓
┌─────────────────┐
│ Step 3: │
│ Adaptive Work │ ← Nunjucks adapts based on score!
│ {% if score %}│
└────────┬────────┘
↓
┌─────────────────┐
│ Final Output │
└─────────────────┘
```
### Quality Metrics to Leverage
**Step Outputs Can Include**:
```json
{
"content": "...",
"quality_metrics": {
"accuracy_score": 0.85,
"completeness_score": 0.90,
"clarity_score": 0.75,
"overall_score": 0.83
},
"issues": [
{"category": "accuracy", "severity": "medium", "location": "paragraph 3"},
{"category": "clarity", "severity": "low", "location": "section 2"}
],
"recommendations": ["add citations", "clarify terminology"]
}
```
**Template Uses Metrics**:
```nunjucks
{% if quality_metrics.accuracy_score < 0.8 %}
Focus on accuracy: {{quality_metrics.accuracy_score}} below threshold
Issues: {{issues|selectattr("category", "equalto", "accuracy")|list}}
{% endif %}
{% if quality_metrics.clarity_score < 0.8 %}
Enhance clarity in: {{issues|selectattr("category", "equalto", "clarity")|map(attribute="location")|join(", ")}}
{% endif %}
```
### Adaptive Depth Control
**Example: Research Depth Based on Initial Findings**
```nunjucks
# Research Step
{% set initial_source_count = step1_output.sources|length %}
{% set initial_quality = step1_output.confidence %}
{% if initial_source_count < 3 or initial_quality < 0.7 %}
## 🔍 EXPANDED RESEARCH REQUIRED
Initial findings insufficient:
- Sources: {{initial_source_count}} (target: ≥5)
- Confidence: {{initial_quality}} (target: ≥0.80)
### Deep Research Protocol:
1. Expand source search to at least 5 authoritative references
2. Diversify source types (academic, industry, expert opinion)
3. Cross-validate findings across sources
4. Build comprehensive evidence base
{% else %}
## ✓ Standard Research Process
Initial findings provide solid foundation:
- Sources: {{initial_source_count}}
- Confidence: {{initial_quality}}
### Research Tasks:
1. Supplement existing findings
2. Fill identified gaps
3. Strengthen key conclusions
{% endif %}
Previous Findings: {{step1_output.summary}}
[Continue with research based on depth level indicated above]
```
---
## Implementation Strategy
### Phase 1: Identify High-Value Chains (Week 1)
**Audit Current Chains**:
1. Review existing chain prompts
2. Identify steps that could benefit from adaptation
3. Map current variable passing patterns
4. Document quality metrics already available
**Priority Candidates**:
- `noteIntegration.md` - 7 steps, quality-sensitive
- `create_docs_chain.md` - 5 steps, depth-variable
- `video_notes_enhanced.md` - 6 steps, content-adaptive
### Phase 2: Design Adaptive Patterns (Week 1-2)
**Create Pattern Library**:
1. **Quality-Based Adaptation**
- Templates for score-driven instructions
- Severity-based error handling
- Validation-driven refinement
2. **Complexity-Based Adaptation**
- Dynamic depth control
- Resource allocation based on complexity
- Methodology selection by difficulty
3. **Content-Based Adaptation**
- Format selection based on content type
- Structure adaptation to material
- Example density based on technicality
### Phase 3: Implement Example Chains (Week 2-3)
**Transform Existing Chains**:
**Example 1: Note Integration Chain**
Current `obsidian_metadata_optimizer.md`:
```nunjucks
{{note_content}}
{{vault_structure}}
```
Enhanced with quality adaptation:
```nunjucks
{{note_content}}
{{vault_structure}}
{% if step3_refinement.quality_score %}
Quality from previous step: {{step3_refinement.quality_score}}
{% if step3_refinement.quality_score < 0.8 %}
**Enhanced Metadata Required**
Apply comprehensive metadata framework with:
- Extended tag hierarchy (minimum 10 tags)
- Full plugin integration metadata
- Detailed connection network (≥5 related notes)
- Advanced search keywords (≥15 terms)
{% else %}
**Standard Metadata**
Apply professional metadata standards.
{% endif %}
{% endif %}
```
**Example 2: Documentation Chain**
Transform `docs-review-refinement.md`:
```nunjucks
{% if step3_content.technical_depth %}
{% if step3_content.technical_depth == "advanced" and audience == "beginners" %}
## ⚠️ TECHNICAL DEPTH MISMATCH DETECTED
Content Complexity: Advanced
Target Audience: Beginners
### Adaptation Strategy:
1. Add explanatory sections for complex concepts
2. Include step-by-step walkthroughs
3. Provide glossary of technical terms
4. Add beginner-friendly examples
5. Create progressive disclosure sections (basic → advanced)
{% elif step3_content.technical_depth == "basic" and audience == "experts" %}
## ⚡ DEPTH ENHANCEMENT REQUIRED
Content Complexity: Basic
Target Audience: Experts
### Enhancement Strategy:
1. Add advanced implementation details
2. Include edge case discussions
3. Provide performance optimization guidance
4. Add architectural considerations
5. Include expert-level best practices
{% endif %}
{% endif %}
```
### Phase 4: Add Quality Metrics to Steps (Week 3-4)
**Enhance Validation Steps**:
Currently, validation steps might output:
```json
{"validated": true, "content": "..."}
```
Enhance to output:
```json
{
"validated": true,
"content": "...",
"quality_score": 0.87,
"accuracy_score": 0.90,
"completeness_score": 0.85,
"clarity_score": 0.85,
"issues": [
{"type": "clarity", "severity": "low", "description": "Section 3 could be clearer"}
],
"recommendations": ["add example in section 3"],
"metadata": {
"word_count": 1500,
"complexity_level": 7,
"technical_terms": 45
}
}
```
**Update Validation Prompts**:
Add structured output requirements to validation steps:
```markdown
Provide validation results in this structure:
- quality_score: Overall score 0-1
- accuracy_score: Factual accuracy 0-1
- completeness_score: Coverage completeness 0-1
- clarity_score: Clarity and readability 0-1
- issues: Array of specific issues with severity
- recommendations: Array of improvement suggestions
```
### Phase 5: Create Template Helpers (Week 4)
**Nunjucks Custom Filters**:
Add custom filters to `jsonUtils.ts` nunjucksEnv:
```typescript
nunjucksEnv.addFilter('quality_level', (score: number) => {
if (score >= 0.9) return 'excellent';
if (score >= 0.8) return 'good';
if (score >= 0.7) return 'acceptable';
return 'needs_improvement';
});
nunjucksEnv.addFilter('severity_icon', (severity: string) => {
const icons = {
'critical': '🔴',
'high': '🟠',
'medium': '🟡',
'low': '🟢'
};
return icons[severity] || '⚪';
});
nunjucksEnv.addFilter('complexity_emoji', (level: number) => {
if (level > 8) return '🔥';
if (level > 5) return '⚡';
return '📊';
});
```
**Usage in Templates**:
```nunjucks
Quality: {{quality_score|quality_level}}
Severity: {{issue.severity|severity_icon}} {{issue.description}}
Complexity: {{complexity_level|complexity_emoji}} Level {{complexity_level}}
```
### Phase 6: Testing & Refinement (Week 4-5)
**Test Matrix**:
```
Chain: noteIntegration
Scenario 1: High quality input (score > 0.9)
Expected: Standard processing
Actual: [test result]
Scenario 2: Medium quality (score 0.7-0.9)
Expected: Targeted improvements
Actual: [test result]
Scenario 3: Low quality (score < 0.7)
Expected: Comprehensive rebuild
Actual: [test result]
```
**Validation**:
- Execute chains with varying quality inputs
- Verify conditional branches trigger correctly
- Ensure template variables accessible
- Confirm output meets quality targets
---
## Example Transformations
### Example 1: Simple → Adaptive Refinement
**Before** (`refinement_step.md`):
```markdown
# Refinement Step
Refine this analysis: {{analysis}}
Please improve the analysis based on validation feedback: {{validation_issues}}
```
**After**:
```nunjucks
# Adaptive Refinement Step
{% if validation_score < 0.6 %}
## 🔴 CRITICAL - COMPREHENSIVE REBUILD
Validation Score: {{validation_score}} (Critical)
### Failed Criteria:
{% for issue in validation_issues %}
- {{issue.criterion}}: {{issue.reason}}
**Required Action**: {{issue.remedy}}
{% endfor %}
### Rebuild Protocol:
1. **Foundation Reset**: Restart analysis from core principles
2. **Systematic Remediation**: Address each failed criterion thoroughly
3. **Evidence Strengthening**: Add authoritative sources and citations
4. **Quality Verification**: Self-validate against all criteria before completion
**Success Target**: Achieve validation score ≥ 0.75 with zero critical issues
{% elif validation_score < 0.8 %}
## 🟡 MODERATE IMPROVEMENTS NEEDED
Validation Score: {{validation_score}} (Needs Enhancement)
### Issues to Address:
{% for issue in validation_issues %}
- **{{issue.criterion}}**: {{issue.reason}}
{% endfor %}
### Targeted Improvement Strategy:
1. Address each issue systematically
2. Enhance supporting evidence and examples
3. Clarify ambiguous sections
4. Strengthen logical flow and argumentation
**Target**: Validation score ≥ 0.85
{% else %}
## 🟢 EXCELLENT - FINAL POLISH
Validation Score: {{validation_score}} (Excellent!)
{% if validation_issues|length > 0 %}
Minor refinements needed:
{% for issue in validation_issues %}
- {{issue.criterion}}: {{issue.reason}}
{% endfor %}
{% else %}
No issues identified - apply publication polish only.
{% endif %}
### Final Polish Checklist:
- ✨ Optimize language precision and clarity
- 📝 Ensure consistent terminology throughout
- 🎨 Enhance visual formatting and readability
- 🔍 Final proofreading pass
{% endif %}
---
**Original Analysis:**
{{analysis}}
**Instructions**: Apply refinements appropriate to the quality level indicated above. Focus on achieving target validation score with efficient, focused improvements.
```
**Impact**:
- ✅ Appropriate effort based on quality
- ✅ Specific, actionable instructions
- ✅ Clear success criteria
- ✅ Efficient resource utilization
### Example 2: Static → Content-Adaptive Format
**Before** (`final_output.md`):
```markdown
# Final Output
Create final documentation from: {{content}}
Target audience: {{audience}}
```
**After**:
```nunjucks
# Content-Adaptive Final Output
{% set content_characteristics = {
'has_code': 'def ' in content or 'function ' in content or 'class ' in content,
'has_data': 'metric' in content or 'statistics' in content or 'data' in content,
'has_narrative': 'story' in content or 'experience' in content or 'journey' in content,
'technical_level': step2_analysis.technical_level or 'medium'
} %}
## Format Selection
Content Type:
{% if content_characteristics.has_code %}**Technical/Code-Heavy**{% endif %}
{% if content_characteristics.has_data %}**Data/Analytical**{% endif %}
{% if content_characteristics.has_narrative %}**Narrative/Story-Driven**{% endif %}
Technical Level: {{content_characteristics.technical_level}}
Target Audience: {{audience}}
---
{% if content_characteristics.has_code and audience == 'developers' %}
## Technical Documentation Format
Structure the final output as:
### Code Reference Documentation
```
[Language] [Function/Class Name]
**Purpose**: [Clear description]
**Parameters**:
- param1 (type): description
- param2 (type): description
**Returns**: type and description
**Example Usage**:
```[language]
[working code example]
```
**Notes**: Implementation details, edge cases, performance considerations
```
Apply this structure to all code elements in: {{content}}
{% elif content_characteristics.has_data and audience in ['analysts', 'executives'] %}
## Analytical Report Format
Structure as:
### Executive Summary
[2-3 sentence overview of key findings]
### Key Metrics
| Metric | Value | Trend | Implication |
|--------|-------|-------|-------------|
[tabular data presentation]
### Detailed Analysis
[Section for each major finding with supporting data]
### Recommendations
[Actionable insights prioritized by impact]
{% elif content_characteristics.has_narrative or audience == 'general' %}
## Narrative Format
Structure with:
### Introduction
[Engaging opening that sets context]
### Story Arc
[Progressive narrative with clear flow]
- Context setting
- Challenge/opportunity
- Actions taken
- Results and outcomes
- Lessons learned
### Conclusion
[Memorable takeaway]
{% else %}
## Standard Documentation Format
### Overview
[High-level summary]
### Main Content
{{content}}
### Conclusion
[Key takeaways]
{% endif %}
---
**Source Content:** {{content}}
**Instructions**: Apply the format structure indicated above, adapting the content appropriately for the target audience and content type.
```
**Benefits**:
- ✅ Automatic format selection
- ✅ Audience-appropriate structure
- ✅ Content-type optimization
- ✅ Consistent quality across types
---
## Best Practices & Patterns
### 1. Progressive Instruction Clarity
**Pattern**: Increase instruction specificity as quality decreases
```nunjucks
{% if quality_score > 0.9 %}
{# High quality: minimal, high-level guidance #}
Polish to perfection.
{% elif quality_score > 0.7 %}
{# Good quality: structured guidance #}
1. Address these specific issues: {{issues}}
2. Enhance clarity in sections X, Y
3. Validate completion
{% else %}
{# Low quality: detailed step-by-step #}
Follow this detailed protocol:
Step 1: Foundation Analysis
1.1. Review core requirements: {{requirements}}
1.2. Identify gaps in current version
1.3. Document specific deficiencies
Step 2: Systematic Remediation
2.1. For each deficiency:
a) Root cause analysis
b) Evidence-based solution
c) Implementation
d) Validation
Step 3: Quality Verification
[Detailed verification checklist]
{% endif %}
```
### 2. Error Context Preservation
**Pattern**: Carry error context through recovery steps
```nunjucks
{% if previous_error %}
## Error Recovery Context
**Original Error**: {{previous_error.message}}
**Failed Step**: {{previous_error.step_name}}
**Attempt Number**: {{previous_error.attempt_count}}
{% if previous_error.attempt_count > 2 %}
**ALERT**: Multiple failures detected. Applying simplified approach.
{# Provide more guided, conservative instructions #}
{% else %}
**Retry Strategy**: Address specific error cause
{# Standard recovery #}
{% endif %}
{% endif %}
```
### 3. Metric-Driven Branching
**Pattern**: Use multiple metrics for nuanced decisions
```nunjucks
{% set needs_accuracy_work = accuracy_score < 0.8 %}
{% set needs_clarity_work = clarity_score < 0.8 %}
{% set needs_completeness_work = completeness_score < 0.8 %}
{% if needs_accuracy_work and needs_clarity_work and needs_completeness_work %}
## Comprehensive Improvement Required (All Areas)
[Instructions covering all three dimensions]
{% elif needs_accuracy_work %}
## Focus: Accuracy Enhancement
[Accuracy-specific instructions]
{% elif needs_clarity_work %}
## Focus: Clarity Improvement
[Clarity-specific instructions]
{% elif needs_completeness_work %}
## Focus: Completeness
[Completeness-specific instructions]
{% else %}
## Minor Polish Only
[Light refinement instructions]
{% endif %}
```
### 4. Accumulated State Patterns
**Pattern**: Use state from multiple previous steps
```nunjucks
{# Step 4 references Steps 1, 2, and 3 #}
{% set initial_complexity = step1_analysis.complexity_level %}
{% set research_depth = step2_research.source_count %}
{% set validation_passed = step3_validation.passed %}
{% if initial_complexity > 7 and research_depth < 5 %}
## ⚠️ Complexity-Research Mismatch
Analysis Complexity: {{initial_complexity}}/10 (High)
Research Depth: {{research_depth}} sources (Insufficient)
**Action Required**: Expand research to match complexity
- Target: Minimum {{initial_complexity}} authoritative sources
- Diversify: Include academic, industry, and expert perspectives
{% elif not validation_passed and research_depth > 10 %}
## ⚠️ Quality Issue Despite Deep Research
Research Sources: {{research_depth}} (Extensive)
Validation: FAILED
**Analysis**: Issue not lack of sources but synthesis quality
**Action**: Focus on integration and analysis, not more research
{% endif %}
```
### 5. Self-Documenting Conditionals
**Pattern**: Make template logic self-explanatory
```nunjucks
{# DECISION POINT: Determine refinement approach based on validation #}
{% set quality_threshold_critical = 0.6 %}
{% set quality_threshold_target = 0.8 %}
{% set requires_rebuild = validation_score < quality_threshold_critical %}
{% set requires_enhancement = validation_score < quality_threshold_target and not requires_rebuild %}
{# BRANCH 1: Critical quality - rebuild from scratch #}
{% if requires_rebuild %}
## Critical Quality Issues (Score: {{validation_score}})
[Rebuild instructions]
{# BRANCH 2: Moderate quality - targeted improvements #}
{% elif requires_enhancement %}
## Enhancement Required (Score: {{validation_score}})
[Enhancement instructions]
{# BRANCH 3: Good quality - polish only #}
{% else %}
## Excellent Quality (Score: {{validation_score}})
[Polish instructions]
{% endif %}
```
---
## Performance Considerations
### Template Rendering Performance
**Nunjucks Rendering Cost**:
- Variable substitution: ~1ms per 100 variables
- Simple conditionals: ~0.5ms per condition
- Loops: ~0.1ms per iteration
- Complex filters: ~1-5ms depending on operation
**Optimization Strategies**:
1. **Cache Template Objects**:
```typescript
// Already configured in jsonUtils.ts
const nunjucksEnv = nunjucks.configure(promptTemplatesPath, {
noCache: process.env.NODE_ENV === "development", // Cache in production
});
```
2. **Minimize Loop Complexity**:
```nunjucks
{# AVOID: Nested loops with complex operations #}
{% for item in large_list %}
{% for subitem in item.subitems %}
{{ subitem|complex_filter|another_filter }}
{% endfor %}
{% endfor %}
{# PREFER: Pre-process in JavaScript, simple loops #}
{% for processed_item in preprocessed_list %}
{{ processed_item }}
{% endfor %}
```
3. **Conditional Short-Circuiting**:
```nunjucks
{# AVOID: Multiple expensive checks #}
{% if expensive_check_1() and expensive_check_2() and expensive_check_3() %}
{# PREFER: Check cheapest/most likely to fail first #}
{% if simple_check and moderate_check and expensive_check %}
```
4. **Variable Pre-Processing**:
```typescript
// In chain executor, before template rendering:
const templateVars = {
...stepOutputs,
// Pre-calculate expensive derived values
total_complexity: calculateComplexity(stepOutputs),
quality_level: determineQualityLevel(stepOutputs.validation_score),
};
```
### Memory Considerations
**Template Variable Memory**:
- Each step can accumulate outputs from all previous steps
- Long chains (>10 steps) can grow context significantly
- Monitor memory usage in long-running chains
**Mitigation**:
```typescript
// Prune unnecessary data before passing to next step
const prunedOutputs = {
// Keep only what next step needs
summary: stepOutput.summary,
quality_score: stepOutput.quality_score,
issues: stepOutput.issues,
// Omit large content that won't be used
// detailed_content: stepOutput.detailed_content, // Skip if not needed
};
```
---
## Future Enhancements
### Phase 2: Dynamic Step Selection (Execution Engine)
**Beyond Nunjucks Capability** - Requires execution engine changes:
```json
{
"steps": [
{"id": "step1", "promptId": "analysis"},
{
"id": "step2_conditional",
"conditionalBranch": {
"condition": "step1.quality_score < 0.7",
"ifTrue": {"promptId": "deep_analysis"},
"ifFalse": {"promptId": "standard_refinement"}
}
}
]
}
```
### Phase 3: Recursive Step Execution
**Loop Until Quality Threshold**:
```json
{
"steps": [
{"id": "initial", "promptId": "draft"},
{
"id": "refine_loop",
"promptId": "refinement",
"loopCondition": {
"maxIterations": 3,
"exitWhen": "output.quality_score >= 0.8"
}
}
]
}
```
### Phase 4: LLM-Driven Chain Orchestration
**AI Decides Next Step**:
```typescript
// Execution engine asks LLM what to do next
const nextStepDecision = await llm.decide({
prompt: "Based on these results, should we: A) Proceed to synthesis, B) Gather more research, C) Refine current analysis?",
context: currentStepOutputs,
options: ["synthesis", "research", "refinement"]
});
```
### Phase 5: Quality Gate Integration
**Automatic Quality Enforcement**:
```json
{
"steps": [
{"id": "step1", "promptId": "analysis"},
{
"id": "quality_gate",
"type": "validation",
"requirements": {
"minimum_quality_score": 0.8,
"required_fields": ["citations", "evidence"],
"failureAction": "retry_previous_step"
}
}
]
}
```
---
## Implementation Checklist
### Week 1: Foundation
- [ ] Audit all existing chains
- [ ] Document current variable passing patterns
- [ ] Identify top 3 chains for enhancement
- [ ] Design adaptive pattern library
- [ ] Create Nunjucks filter helpers
### Week 2: Core Implementation
- [ ] Enhance quality validation steps with detailed metrics
- [ ] Transform 3 priority chains with adaptive templates
- [ ] Add quality-driven conditionals
- [ ] Implement complexity-based branching
### Week 3: Advanced Patterns
- [ ] Add error recovery patterns
- [ ] Implement content-type adaptation
- [ ] Create accumulated state patterns
- [ ] Build format selection logic
### Week 4: Testing & Documentation
- [ ] Test all adaptive chains with various inputs
- [ ] Validate conditional branches
- [ ] Document template patterns
- [ ] Create developer guide for adaptive prompts
### Week 5: Optimization
- [ ] Performance profiling
- [ ] Memory optimization
- [ ] Template caching validation
- [ ] Production readiness review
---
## Success Metrics
### Quantitative
- ✅ 5+ chains enhanced with adaptive templates
- ✅ 30%+ reduction in low-quality outputs requiring manual intervention
- ✅ Quality score improvement: average increase from 0.75 → 0.85+
- ✅ Template rendering performance: <50ms per step
- ✅ Zero template rendering errors in production
### Qualitative
- ✅ Chains intelligently adapt to quality levels
- ✅ Error recovery is automatic and effective
- ✅ Resource utilization is efficient (effort matches need)
- ✅ Developer understanding of adaptive patterns is high
- ✅ Template maintenance is straightforward
---
## Conclusion
**Key Insight**: Nunjucks templates in chain steps have access to all previous step results, enabling sophisticated result-based conditional logic and adaptive prompt instructions.
**Strategic Value**:
- **Intelligent Adaptation**: Prompts adjust behavior based on quality, complexity, and errors
- **Resource Efficiency**: Apply appropriate effort based on actual needs
- **Quality Assurance**: Automatic escalation when quality thresholds not met
- **Error Resilience**: Graceful recovery from validation failures
**Path Forward**:
1. Enhance validation steps to output detailed quality metrics
2. Transform existing chains with adaptive templates
3. Build pattern library for common adaptation scenarios
4. Extend to dynamic step selection in execution engine
**Ultimate Goal**: Self-optimizing chain orchestration where each step intelligently adapts based on runtime results, maximizing quality while minimizing unnecessary computation.
---
**Next Steps**: Begin Week 1 implementation with chain audit and pattern library design.
**Document Maintainer**: Architecture Team
**Last Updated**: 2025-10-05
**Review Frequency**: Bi-weekly during implementation, monthly thereafter
```