mcp-ai-agent-guidelines
Version:
A comprehensive Model Context Protocol server providing professional tools, resources, and prompts for implementing AI agent best practices
282 lines • 12.5 kB
JavaScript
// Pivot Module - Deterministic decision making for strategic design changes
import { z } from "zod";
import { constraintManager } from "./constraint-manager.js";
const _PivotRequestSchema = z.object({
sessionState: z.any(), // DesignSessionState
currentContent: z.string(),
triggerReason: z.string().optional(),
forceEvaluation: z.boolean().optional().default(false),
});
class PivotModuleImpl {
// Note: microMethods reserved for future complexity analysis features
// private microMethods: string[] = [];
async initialize() {
// this.microMethods = constraintManager.getMicroMethods("pivot");
// Note: microMethods initialization reserved for future complexity analysis features
}
async evaluatePivotNeed(request) {
const { sessionState, currentContent, triggerReason, forceEvaluation } = request;
const thresholds = constraintManager.getCoverageThresholds();
// Execute micro-methods for deterministic analysis
const complexityScore = await this.calculateComplexityScore(sessionState, currentContent);
const entropyLevel = await this.measureEntropyLevel(sessionState, currentContent);
// Check if pivot should be triggered
const triggered = forceEvaluation ||
complexityScore > thresholds.pivot_thresholds.complexity_threshold ||
entropyLevel > thresholds.pivot_thresholds.entropy_threshold ||
this.checkCoverageDrop(sessionState);
let reason = triggerReason || "Manual evaluation requested";
if (complexityScore > thresholds.pivot_thresholds.complexity_threshold) {
reason = `High complexity score (${complexityScore}) exceeds threshold (${thresholds.pivot_thresholds.complexity_threshold})`;
}
else if (entropyLevel > thresholds.pivot_thresholds.entropy_threshold) {
reason = `High entropy level (${entropyLevel}) exceeds threshold (${thresholds.pivot_thresholds.entropy_threshold})`;
}
// Generate alternatives if pivot is recommended
const alternatives = triggered
? await this.generateAlternatives(sessionState, complexityScore, entropyLevel)
: [];
const recommendation = this.generateRecommendation(complexityScore, entropyLevel, alternatives);
return {
triggered,
reason,
complexity: complexityScore,
entropy: entropyLevel,
threshold: Math.max(thresholds.pivot_thresholds.complexity_threshold, thresholds.pivot_thresholds.entropy_threshold),
alternatives,
recommendation,
};
}
// Backwards-compatible helper expected by tests
async generateRecommendations(sessionState) {
await this.initialize();
const sampleContent = `${sessionState.config.context} ${sessionState.config.goal}`;
const complexity = await this.calculateComplexityScore(sessionState, sampleContent);
const entropy = await this.measureEntropyLevel(sessionState, sampleContent);
const alts = await this.generateAlternatives(sessionState, complexity, entropy);
return [this.generateRecommendation(complexity, entropy, alts), ...alts];
}
async calculateComplexityScore(sessionState, content) {
const factors = this.analyzeComplexityFactors(sessionState, content);
// Weighted complexity calculation
const weights = {
technicalComplexity: 0.3,
businessComplexity: 0.2,
integrationComplexity: 0.25,
userComplexity: 0.15,
maintenanceComplexity: 0.1,
};
let weightedScore = 0;
for (const [factor, value] of Object.entries(factors)) {
weightedScore += value * (weights[factor] || 0);
}
return Math.min(weightedScore, 100);
}
async measureEntropyLevel(sessionState, content) {
const factors = this.analyzeEntropyFactors(sessionState, content);
// Weighted entropy calculation
const weights = {
requirementUncertainty: 0.25,
technicalUncertainty: 0.25,
timelineUncertainty: 0.2,
resourceUncertainty: 0.15,
stakeholderAlignment: 0.15,
};
let weightedScore = 0;
for (const [factor, value] of Object.entries(factors)) {
weightedScore += value * (weights[factor] || 0);
}
return Math.min(weightedScore, 100);
}
analyzeComplexityFactors(_sessionState, content) {
const contentLower = content.toLowerCase();
// Technical complexity indicators
const technicalKeywords = [
"api",
"database",
"microservice",
"integration",
"protocol",
"algorithm",
];
const technicalComplexity = this.calculateKeywordComplexity(contentLower, technicalKeywords, 20);
// Business complexity indicators
const businessKeywords = [
"stakeholder",
"compliance",
"regulation",
"process",
"workflow",
"approval",
];
const businessComplexity = this.calculateKeywordComplexity(contentLower, businessKeywords, 15);
// Integration complexity indicators
const integrationKeywords = [
"external",
"third-party",
"legacy",
"migration",
"sync",
"federation",
];
const integrationComplexity = this.calculateKeywordComplexity(contentLower, integrationKeywords, 25);
// User complexity indicators
const userKeywords = [
"interface",
"experience",
"personalization",
"accessibility",
"localization",
];
const userComplexity = this.calculateKeywordComplexity(contentLower, userKeywords, 10);
// Maintenance complexity indicators
const maintenanceKeywords = [
"monitoring",
"logging",
"deployment",
"scaling",
"backup",
"security",
];
const maintenanceComplexity = this.calculateKeywordComplexity(contentLower, maintenanceKeywords, 12);
return {
technicalComplexity,
businessComplexity,
integrationComplexity,
userComplexity,
maintenanceComplexity,
};
}
analyzeEntropyFactors(_sessionState, content) {
const contentLower = content.toLowerCase();
// Uncertainty indicators
const uncertaintyKeywords = [
"unclear",
"unknown",
"tbd",
"pending",
"investigate",
"research",
];
const requirementUncertainty = this.calculateKeywordComplexity(contentLower, uncertaintyKeywords, 30);
const technicalUncertaintyKeywords = [
"prototype",
"experiment",
"proof of concept",
"feasibility",
"spike",
];
const technicalUncertainty = this.calculateKeywordComplexity(contentLower, technicalUncertaintyKeywords, 25);
const timelineUncertaintyKeywords = [
"estimate",
"roughly",
"approximately",
"depends",
"variable",
];
const timelineUncertainty = this.calculateKeywordComplexity(contentLower, timelineUncertaintyKeywords, 20);
const resourceUncertaintyKeywords = [
"resource",
"capacity",
"availability",
"allocation",
"constraint",
];
const resourceUncertainty = this.calculateKeywordComplexity(contentLower, resourceUncertaintyKeywords, 15);
// Stakeholder alignment (inverse of conflict indicators)
const conflictKeywords = [
"disagree",
"conflict",
"dispute",
"concern",
"objection",
"blocker",
];
const conflictLevel = this.calculateKeywordComplexity(contentLower, conflictKeywords, 20);
const stakeholderAlignment = 100 - conflictLevel; // Higher conflict = lower alignment
return {
requirementUncertainty,
technicalUncertainty,
timelineUncertainty,
resourceUncertainty,
stakeholderAlignment,
};
}
calculateKeywordComplexity(content, keywords, baseScore) {
let matches = 0;
let totalOccurrences = 0;
for (const keyword of keywords) {
const occurrences = (content.match(new RegExp(keyword, "g")) || [])
.length;
if (occurrences > 0) {
matches++;
totalOccurrences += occurrences;
}
}
// Calculate complexity based on keyword density and variety
const keywordDensity = (totalOccurrences / content.split(" ").length) * 1000; // per 1000 words
const keywordVariety = (matches / keywords.length) * 100;
return Math.min(baseScore + keywordDensity * 2 + keywordVariety * 0.5, 100);
}
checkCoverageDrop(sessionState) {
const thresholds = constraintManager.getCoverageThresholds();
// Check if coverage has dropped significantly compared to previous phases
const coverageHistory = sessionState.history
.filter((event) => event.type === "coverage-update")
.map((event) => event.data?.coverage)
.filter(Boolean);
if (coverageHistory.length < 2)
return false;
const current = coverageHistory[coverageHistory.length - 1];
const previous = coverageHistory[coverageHistory.length - 2];
const drop = previous - current;
return drop > thresholds.pivot_thresholds.coverage_drop_threshold;
}
async generateAlternatives(_sessionState, complexity, entropy) {
const alternatives = [];
// Generate alternatives based on complexity and entropy levels
if (complexity > 80) {
alternatives.push("Break down into smaller, more manageable phases");
alternatives.push("Simplify architecture by reducing component interactions");
alternatives.push("Use proven technologies instead of cutting-edge solutions");
alternatives.push("Implement MVP approach with iterative enhancement");
}
if (entropy > 70) {
alternatives.push("Conduct additional research and stakeholder interviews");
alternatives.push("Create prototypes to validate uncertain assumptions");
alternatives.push("Implement phased approach with regular checkpoint reviews");
alternatives.push("Establish clearer requirements through workshops");
}
if (complexity > 70 && entropy > 60) {
alternatives.push("Consider off-the-shelf solutions instead of custom development");
alternatives.push("Reduce scope to core functionality only");
alternatives.push("Split into multiple independent projects");
}
// Ensure we always have some alternatives
if (alternatives.length === 0) {
alternatives.push("Continue with current approach while monitoring complexity");
alternatives.push("Schedule regular design reviews to catch issues early");
}
return alternatives;
}
generateRecommendation(complexity, entropy, _alternatives) {
if (complexity > 85 && entropy > 75) {
return "STRONG PIVOT RECOMMENDED: Both complexity and uncertainty are very high. Consider fundamental redesign or scope reduction.";
}
if (complexity > 85) {
return "PIVOT RECOMMENDED: High complexity detected. Simplify architecture or break into smaller components.";
}
if (entropy > 75) {
return "PIVOT RECOMMENDED: High uncertainty detected. Gather more information before proceeding.";
}
if (complexity > 70 || entropy > 60) {
return "CAUTION: Monitor complexity and uncertainty closely. Consider alternative approaches.";
}
return "CONTINUE: Complexity and uncertainty are within acceptable ranges.";
}
}
// Export singleton instance
export const pivotModule = new PivotModuleImpl();
// Module Implementation Status Sentinel
export const IMPLEMENTATION_STATUS = "IMPLEMENTED";
//# sourceMappingURL=pivot-module.js.map