when-optimizing-prompts-use-prompt-architect

Prompt Architect - Evidence-Based Prompt Engineering

Overview

Comprehensive framework for analyzing, creating, and refining prompts for AI systems (Claude, GPT, etc.). Applies structural optimization, self-consistency patterns, and anti-pattern detection to transform prompts into highly effective versions.

When to Use This Skill

• Creating new prompts for AI systems
• Existing prompts produce poor results
• Inconsistent AI outputs
• Need to improve prompt clarity
• Applying evidence-based prompt engineering
• Optimizing agent instructions
• Building prompt libraries

Theoretical Foundation

Evidence-Based Techniques

1. Chain-of-Thought (CoT): Explicit reasoning steps
2. Self-Consistency: Multiple reasoning paths
3. ReAct: Reasoning + Acting pattern
4. Program-of-Thought: Structured logic
5. Plan-and-Solve: Decomposition strategy
6. Role-Playing: Persona assignment
7. Few-Shot Learning: Example-based instruction

Prompt Structure Principles

[System Context] → [Role Definition] → [Task Description] →
[Constraints] → [Format Specification] → [Examples] → [Quality Criteria]

Phase 1: Analyze Current Prompt

Objective

Identify weaknesses and improvement opportunities

Agent: Researcher

Step 1.1: Structural Analysis

const promptAnalysis = {
  components: {
    hasSystemContext: checkForContext(prompt),
    hasRoleDefinition: checkForRole(prompt),
    hasTaskDescription: checkForTask(prompt),
    hasConstraints: checkForConstraints(prompt),
    hasFormatSpec: checkForFormat(prompt),
    hasExamples: checkForExamples(prompt),
    hasQualityCriteria: checkForCriteria(prompt)
  },
  metrics: {
    length: prompt.length,
    clarity: calculateClarity(prompt),
    specificity: calculateSpecificity(prompt),
    completeness: calculateCompleteness(prompt)
  },
  antiPatterns: detectAntiPatterns(prompt)
};

await memory.store('prompt-architect/analysis', promptAnalysis);

Step 1.2: Detect Anti-Patterns

const antiPatterns = [
  {
    name: 'Vague Instructions',
    pattern: /please|try to|maybe|possibly/gi,
    severity: 'HIGH',
    fix: 'Use imperative commands: "Analyze...", "Generate...", "Create..."'
  },
  {
    name: 'Missing Context',
    pattern: absence of background info,
    severity: 'HIGH',
    fix: 'Add system context and domain information'
  },
  {
    name: 'No Output Format',
    pattern: absence of format specification,
    severity: 'MEDIUM',
    fix: 'Specify exact output format (JSON, markdown, etc.)'
  },
  {
    name: 'Conflicting Instructions',
    pattern: detectContradictions(prompt),
    severity: 'HIGH',
    fix: 'Resolve contradictions, prioritize requirements'
  },
  {
    name: 'Implicit Assumptions',
    pattern: detectImplicitAssumptions(prompt),
    severity: 'MEDIUM',
    fix: 'Make all assumptions explicit'
  }
];

const foundAntiPatterns = antiPatterns.filter(ap =>
  ap.pattern.test ? ap.pattern.test(prompt) : ap.pattern
);

await memory.store('prompt-architect/anti-patterns', foundAntiPatterns);

Step 1.3: Identify Missing Components

const missingComponents = [];

if (!promptAnalysis.components.hasSystemContext) {
  missingComponents.push({
    component: 'System Context',
    importance: 'HIGH',
    recommendation: 'Add background info, domain knowledge, constraints'
  });
}

if (!promptAnalysis.components.hasExamples) {
  missingComponents.push({
    component: 'Examples',
    importance: 'MEDIUM',
    recommendation: 'Add 2-3 examples showing desired behavior'
  });
}

// ... check other components

await memory.store('prompt-architect/missing', missingComponents);

Validation Criteria

• [ ] All 7 components checked
• [ ] Anti-patterns identified
• [ ] Missing components listed
• [ ] Severity assigned to issues

Hooks Integration

npx claude-flow@alpha hooks pre-task \
  --description "Analyze prompt structure and quality" \
  --complexity "medium"

npx claude-flow@alpha hooks post-task \
  --task-id "prompt-analysis" \
  --output "analysis-report.json"

Phase 2: Structure Optimization

Objective

Reorganize prompt for logical flow and clarity

Agent: Coder (Prompt Specialist)

Step 2.1: Apply Template Structure

const optimizedStructure = {
  systemContext: {
    domain: extractDomain(prompt),
    background: generateContextualBackground(),
    constraints: extractOrInferConstraints(prompt)
  },
  roleDefinition: {
    persona: definePersona(task),
    expertise: listRequiredExpertise(),
    perspective: defineWorkingPerspective()
  },
  taskDescription: {
    primary: extractPrimaryTask(prompt),
    secondary: extractSecondaryTasks(prompt),
    scope: defineScope(),
    outOfScope: defineWhatNotToDo()
  },
  constraints: {
    required: extractRequirements(prompt),
    forbidden: extractProhibitions(prompt),
    optional: extractPreferences(prompt)
  },
  formatSpecification: {
    outputFormat: specifyFormat(),
    structure: defineStructure(),
    examples: []
  },
  qualityCriteria: {
    success: defineSuccessCriteria(),
    validation: defineValidationMethod(),
    metrics: defineMetrics()
  }
};

await memory.store('prompt-architect/structure', optimizedStructure);

Step 2.2: Build Optimized Prompt

# System Context
${optimizedStructure.systemContext.background}

Domain: ${optimizedStructure.systemContext.domain}
Constraints: ${optimizedStructure.systemContext.constraints.join(', ')}

# Role
You are ${optimizedStructure.roleDefinition.persona} with expertise in:
${optimizedStructure.roleDefinition.expertise.map(e => `- ${e}`).join('\n')}

Your perspective: ${optimizedStructure.roleDefinition.perspective}

# Task
Primary objective: ${optimizedStructure.taskDescription.primary}

${optimizedStructure.taskDescription.secondary.length > 0 ?
  'Secondary objectives:\n' + optimizedStructure.taskDescription.secondary.map(t => `- ${t}`).join('\n') : ''}

Scope: ${optimizedStructure.taskDescription.scope}
Out of scope: ${optimizedStructure.taskDescription.outOfScope.join(', ')}

# Constraints
MUST: ${optimizedStructure.constraints.required.map(r => `- ${r}`).join('\n')}
MUST NOT: ${optimizedStructure.constraints.forbidden.map(f => `- ${f}`).join('\n')}
PREFER: ${optimizedStructure.constraints.optional.map(o => `- ${o}`).join('\n')}

# Output Format
${optimizedStructure.formatSpecification.outputFormat}

Structure:
${optimizedStructure.formatSpecification.structure}

# Quality Criteria
Success is defined as:
${optimizedStructure.qualityCriteria.success.map(s => `- ${s}`).join('\n')}

Validation method: ${optimizedStructure.qualityCriteria.validation}

Step 2.3: Add Progressive Disclosure

// For complex prompts, use hierarchical structure
const progressivePrompt = {
  essential: generateEssentialInstructions(),
  details: generateDetailedGuidance(),
  advanced: generateAdvancedTechniques(),
  examples: generateExamples(),
  troubleshooting: generateTroubleshootingGuide()
};

// Structure with collapsible sections
const enhancedPrompt = `
${progressivePrompt.essential}

<details>
<summary>Detailed Guidance</summary>
${progressivePrompt.details}
</details>

<details>
<summary>Advanced Techniques</summary>
${progressivePrompt.advanced}
</details>

<details>
<summary>Examples</summary>
${progressivePrompt.examples}
</details>
`;

Validation Criteria

• [ ] All 7 components present
• [ ] Logical flow established
• [ ] Progressive disclosure applied
• [ ] Clear hierarchy visible

Script Template

#!/bin/bash
# optimize-structure.sh

INPUT_PROMPT="$1"
OUTPUT_PROMPT="$2"

# Analyze structure
ANALYSIS=$(npx claude-flow@alpha agent-spawn \
  --type researcher \
  --task "Analyze prompt structure: $(cat $INPUT_PROMPT)")

# Optimize
OPTIMIZED=$(npx claude-flow@alpha agent-spawn \
  --type coder \
  --task "Restructure prompt based on analysis: $ANALYSIS")

echo "$OPTIMIZED" > "$OUTPUT_PROMPT"

npx c