hyntx 2.2.1 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -414,7 +414,8 @@ declare function getAllProviders(config: EnvConfig): readonly AnalysisProvider[]
414
414
 
415
415
  /**
416
416
  * Checks if this is the first run of Hyntx.
417
- * First run is detected when HYNTX_SERVICES is not set.
417
+ * First run is detected when HYNTX_SERVICES is not set in process.env
418
+ * AND no configuration exists in the shell config file.
418
419
  *
419
420
  * @returns true if this is the first run
420
421
  */
package/dist/api/index.js CHANGED
@@ -389,63 +389,178 @@ var ISSUE_TAXONOMY = {
389
389
  vague: {
390
390
  name: "Vague Request",
391
391
  severity: "high",
392
- suggestion: "Be more specific about what you need",
392
+ suggestion: "Be more specific about what you need - include function names, file paths, error messages, or specific behaviors",
393
393
  exampleBefore: "Help me with my code",
394
- exampleAfter: "Help me debug this TypeScript function that returns undefined"
394
+ exampleAfter: "Help me debug the calculateTotal() function in utils.ts that returns undefined when called with an empty array"
395
395
  },
396
396
  "no-context": {
397
397
  name: "Missing Context",
398
398
  severity: "high",
399
- suggestion: "Provide relevant background information",
399
+ suggestion: "Provide relevant background information - include file paths, function names, error messages, or code snippets",
400
400
  exampleBefore: "Fix the bug",
401
- exampleAfter: "Fix the bug in the authentication flow where users are logged out after 5 minutes"
401
+ exampleAfter: "Fix the bug in src/auth/login.ts where users are logged out after 5 minutes due to token expiration logic"
402
402
  },
403
403
  "too-broad": {
404
404
  name: "Too Broad",
405
405
  severity: "medium",
406
- suggestion: "Break down into smaller, focused requests",
407
- exampleBefore: "Build me an app",
408
- exampleAfter: "Create a React component for displaying user profiles with avatar and bio"
406
+ suggestion: "Break down into smaller, focused requests - focus on one task or clearly order multiple related tasks",
407
+ exampleBefore: "Build me an app with authentication, database, and API",
408
+ exampleAfter: "Create a React login component with email/password authentication using JWT tokens"
409
409
  },
410
410
  "no-goal": {
411
411
  name: "No Clear Goal",
412
412
  severity: "high",
413
- suggestion: "State what outcome you want to achieve",
413
+ suggestion: "State what outcome you want to achieve - specify success criteria and desired behavior",
414
414
  exampleBefore: "Look at this file",
415
- exampleAfter: "Review this file for security vulnerabilities in the authentication logic"
415
+ exampleAfter: "Review src/auth/login.ts for security vulnerabilities, focusing on input validation and SQL injection risks"
416
416
  },
417
417
  imperative: {
418
418
  name: "Command Without Context",
419
419
  severity: "low",
420
- suggestion: "Explain why you need this",
420
+ suggestion: "Explain why you need this - provide context about the use case and requirements",
421
421
  exampleBefore: "Add a button",
422
- exampleAfter: 'Add a "Submit" button to trigger form validation and API submission'
422
+ exampleAfter: 'Add a "Submit" button to the login form that triggers validation and calls the authentication API'
423
+ },
424
+ "missing-technical-details": {
425
+ name: "Missing Technical Details",
426
+ severity: "medium",
427
+ suggestion: "Include technical details - file paths, function signatures, error messages, stack traces, or code snippets",
428
+ exampleBefore: "The function crashes sometimes",
429
+ exampleAfter: `The validateUser() function in src/utils/auth.ts crashes with "Cannot read property 'email' of null" when called with undefined`
430
+ },
431
+ "unclear-priorities": {
432
+ name: "Unclear Priorities",
433
+ severity: "low",
434
+ suggestion: "Order multiple requests by priority or split into separate prompts for clarity",
435
+ exampleBefore: "Add error handling and logging and also optimize performance and add tests",
436
+ exampleAfter: "First, add comprehensive error handling with try-catch blocks. Then, add logging for debugging. Finally, optimize database queries."
437
+ },
438
+ "insufficient-constraints": {
439
+ name: "Insufficient Constraints",
440
+ severity: "low",
441
+ suggestion: "Specify requirements and constraints - edge cases, performance needs, compatibility requirements",
442
+ exampleBefore: "Make it faster",
443
+ exampleAfter: "Optimize the database query to reduce response time to under 100ms, maintaining backward compatibility with existing API clients"
423
444
  }
424
445
  };
425
446
  var SYSTEM_PROMPT_MINIMAL = `You analyze prompts for quality issues.
426
447
  Respond with JSON only: {"issues": ["issue-id", ...], "score": 0-100}
427
448
 
428
- Valid issue IDs: vague, no-context, too-broad, no-goal, imperative
449
+ Valid issue IDs: vague, no-context, too-broad, no-goal, imperative, missing-technical-details, unclear-priorities, insufficient-constraints
450
+
451
+ Issue definitions:
452
+ - vague: Generic requests without specifics ("help", "fix", "improve")
453
+ - no-context: Missing background info (uses "this", "it", "the bug" without context)
454
+ - too-broad: Requests covering multiple unrelated topics
455
+ - no-goal: Ambiguous success criteria or desired outcome
456
+ - imperative: Commands without explanation or reasoning
457
+ - missing-technical-details: No file paths, function names, or error messages
458
+ - unclear-priorities: Multiple requests without ordering
459
+ - insufficient-constraints: No requirements or edge cases mentioned
460
+
461
+ Scoring: 0-100 (100=perfect, 90+=excellent, 70-89=good, 50-69=fair, <50=poor)
429
462
 
430
463
  Examples:
431
464
  Input: "Help me with code"
432
- Output: {"issues": ["vague", "no-context"], "score": 40}
465
+ Output: {"issues": ["vague", "no-context"], "score": 35}
433
466
 
434
467
  Input: "Debug this TypeScript function that returns undefined"
435
- Output: {"issues": [], "score": 85}`;
436
- var SYSTEM_PROMPT_SIMPLE = `Analyze prompts for quality issues. Return ONLY JSON, no other text.
468
+ Output: {"issues": ["missing-technical-details"], "score": 70}
469
+
470
+ Input: "Debug calculateTotal() in utils.ts that returns undefined when called with empty array"
471
+ Output: {"issues": [], "score": 90}`;
472
+ var SYSTEM_PROMPT_FULL = `You are an expert prompt quality analyst specializing in code-related prompts for AI assistants like Claude. Your task is to analyze prompts and identify patterns that reduce their effectiveness, providing actionable improvements.
473
+
474
+ CRITICAL: Return ONLY valid JSON following the exact schema below. No markdown, no explanations, no code fences - just pure JSON.
437
475
 
438
476
  Schema:
439
- {"issues":[{"name":"issue name","example":"bad prompt","fix":"better prompt"}],"score":75,"tip":"main suggestion"}
477
+ {
478
+ "patterns": [
479
+ {
480
+ "id": "kebab-case-id",
481
+ "name": "Human-Readable Issue Name",
482
+ "frequency": 3,
483
+ "severity": "high|medium|low",
484
+ "examples": ["example prompt 1", "example prompt 2"],
485
+ "suggestion": "Actionable advice to fix this pattern",
486
+ "beforeAfter": {
487
+ "before": "Original problematic prompt",
488
+ "after": "Improved version addressing the issue"
489
+ }
490
+ }
491
+ ],
492
+ "stats": {
493
+ "totalPrompts": 10,
494
+ "promptsWithIssues": 7,
495
+ "overallScore": 65
496
+ },
497
+ "topSuggestion": "Single most impactful recommendation"
498
+ }
499
+
500
+ QUALITY DIMENSIONS TO EVALUATE:
501
+
502
+ 1. SPECIFICITY (High Priority)
503
+ - Vague: "help me", "fix this", "improve code" without specifics
504
+ - Good: Includes function names, file paths, error messages, specific behaviors
505
+ - Look for: Generic verbs without objects, pronouns without referents
440
506
 
441
- Rules:
442
- - issues: array of problems found (empty if none)
443
- - score: 0-100 quality score (100=perfect)
444
- - tip: single most important suggestion
445
- - name: short issue name (e.g. "vague request", "missing context")
446
- - example: actual prompt text showing the issue
447
- - fix: improved version of that prompt`;
448
- var SYSTEM_PROMPT_FULL = SYSTEM_PROMPT_SIMPLE;
507
+ 2. CONTEXT PROVISION (High Priority)
508
+ - Missing: References to "this code", "the bug", "it" without background
509
+ - Good: Provides file paths, function signatures, relevant code snippets, error stack traces
510
+ - Look for: Unclear referents, assumptions of shared knowledge
511
+
512
+ 3. GOAL CLARITY (High Priority)
513
+ - Unclear: "Look at this", "Review my code", "What's wrong?"
514
+ - Good: Explicitly states desired outcome: "Find security vulnerabilities", "Optimize for performance", "Fix the null pointer exception"
515
+ - Look for: Ambiguous success criteria, open-ended questions
516
+
517
+ 4. SCOPE APPROPRIATENESS (Medium Priority)
518
+ - Too broad: "Build me an app", "Refactor everything", multiple unrelated tasks
519
+ - Too narrow: Overly specific constraints that limit solution space unnecessarily
520
+ - Good: Focused single task or clearly ordered multiple tasks
521
+ - Look for: Multiple "and" clauses, unrelated requests, scope creep
522
+
523
+ 5. ACTIONABILITY (Medium Priority)
524
+ - Low: "What do you think?", "Is this good?", purely exploratory
525
+ - Good: Clear action requested: "Fix", "Implement", "Refactor", "Add"
526
+ - Look for: Vague intentions, exploration without purpose
527
+
528
+ 6. TECHNICAL RICHNESS (Medium Priority)
529
+ - Missing: No code examples, file paths, function names, error messages
530
+ - Good: Includes relevant code, stack traces, configuration, environment details
531
+ - Look for: Purely conceptual descriptions without technical details
532
+
533
+ 7. CONSTRAINT DEFINITION (Low Priority)
534
+ - Missing: No requirements, edge cases, or constraints mentioned
535
+ - Good: Specifies requirements, edge cases, performance needs, compatibility needs
536
+ - Look for: Requests that could have many valid interpretations
537
+
538
+ SEVERITY GUIDELINES:
539
+ - high: Significantly impairs prompt effectiveness (vague, missing context, no goal)
540
+ - medium: Moderate impact on effectiveness (too broad, lacks technical details)
541
+ - low: Minor improvement opportunity (missing constraints, could be more specific)
542
+
543
+ SCORING GUIDELINES (0-100):
544
+ - 90-100: Excellent prompts - specific, contextual, actionable, well-scoped
545
+ - 75-89: Good prompts - minor improvements possible
546
+ - 60-74: Fair prompts - needs more context, clarity, or specificity
547
+ - 40-59: Poor prompts - multiple significant issues, partially actionable
548
+ - 20-39: Very poor - barely actionable, missing critical information
549
+ - 0-19: Extremely poor - cannot be meaningfully acted upon
550
+
551
+ PATTERN IDENTIFICATION:
552
+ - Group similar issues together (same root cause)
553
+ - Count frequency: how many prompts exhibit this pattern
554
+ - Provide 1-3 real examples from the actual prompts analyzed
555
+ - Create meaningful before/after pairs that clearly show improvement
556
+ - Ensure beforeAfter.before matches one of the examples
557
+
558
+ IMPROVEMENT PRIORITIES:
559
+ 1. High severity patterns (vague, missing context, no goal) should appear first
560
+ 2. More frequent patterns should rank higher
561
+ 3. topSuggestion should address the most common high-severity issue
562
+
563
+ Remember: The goal is actionable feedback. Focus on patterns that, when fixed, would meaningfully improve prompt effectiveness for AI code assistants.`;
449
564
  var VALID_PATTERN_IDS = Object.keys(ISSUE_TAXONOMY);
450
565
  function applyRulesConfig(rules, baseTaxonomy = ISSUE_TAXONOMY) {
451
566
  if (!rules || Object.keys(rules).length === 0) {
@@ -1822,6 +1937,32 @@ function extractRealExamples(issueId, prompts, limit = 3) {
1822
1937
  case "imperative":
1823
1938
  isMatch = trimmed.length < 20 && wordCount <= 3 && /^(add|delete|remove|update|change|modify)\b/.exec(lowerPrompt) !== null && !lowerPrompt.includes("?");
1824
1939
  break;
1940
+ case "missing-technical-details": {
1941
+ const hasFileRef = /\w+\.(ts|js|tsx|jsx|py|go|java|rb|php|json|yaml|yml)\b/.exec(
1942
+ lowerPrompt
1943
+ ) !== null;
1944
+ const hasFunctionRef = /function|def |class |const |let |var |(\.\w+\()/.exec(
1945
+ lowerPrompt
1946
+ ) !== null;
1947
+ const hasErrorRef = /error|exception|failed|crash|undefined|null/.exec(lowerPrompt) !== null;
1948
+ isMatch = !hasFileRef && !hasFunctionRef && !hasErrorRef && wordCount >= 3;
1949
+ break;
1950
+ }
1951
+ case "unclear-priorities": {
1952
+ const andMatches = lowerPrompt.match(/\band\b/g);
1953
+ const orMatches = lowerPrompt.match(/\bor\b/g);
1954
+ const alsoMatches = lowerPrompt.match(/\balso\b/g);
1955
+ const conjunctionCount = (andMatches?.length ?? 0) + (orMatches?.length ?? 0) + (alsoMatches?.length ?? 0);
1956
+ isMatch = conjunctionCount >= 2 && !/\b(first|second|third|then|next|finally|after|before)\b/.exec(
1957
+ lowerPrompt
1958
+ ) && wordCount >= 10;
1959
+ break;
1960
+ }
1961
+ case "insufficient-constraints":
1962
+ isMatch = !/\b(constraint|requirement|must|should|edge case|boundary|limit|performance|compatib)\b/.exec(
1963
+ lowerPrompt
1964
+ ) && !/\b(<|>|<=|>=|\d+ms|\d+mb|\d+kb)\b/.exec(lowerPrompt) && (lowerPrompt.includes("optimize") || lowerPrompt.includes("improve") || lowerPrompt.includes("make") || lowerPrompt.includes("add")) && wordCount >= 4;
1965
+ break;
1825
1966
  default:
1826
1967
  isMatch = false;
1827
1968
  }
@@ -2730,6 +2871,52 @@ function getAllProviders(config) {
2730
2871
  }
2731
2872
  return config.services.map((type) => createProvider(type, config));
2732
2873
  }
2874
+ var START_MARKER = "# >>> hyntx config >>>";
2875
+ var END_MARKER = "# <<< hyntx config <<<";
2876
+ function findMarkerPositions(content) {
2877
+ const startIndex = content.indexOf(START_MARKER);
2878
+ const endIndex = content.indexOf(END_MARKER);
2879
+ if (startIndex === -1 && endIndex === -1) {
2880
+ return { startIndex: -1, endIndex: -1, isValid: true };
2881
+ }
2882
+ if (startIndex !== -1 && endIndex === -1) {
2883
+ return { startIndex, endIndex: -1, isValid: false, issue: "missing_end" };
2884
+ }
2885
+ if (startIndex === -1 && endIndex !== -1) {
2886
+ return { startIndex: -1, endIndex, isValid: false, issue: "missing_start" };
2887
+ }
2888
+ if (startIndex > endIndex) {
2889
+ return { startIndex, endIndex, isValid: false, issue: "wrong_order" };
2890
+ }
2891
+ return { startIndex, endIndex, isValid: true };
2892
+ }
2893
+ function detectShellConfigFile() {
2894
+ const home = homedir();
2895
+ const shell = process.env["SHELL"] ?? "";
2896
+ if (shell.includes("zsh")) {
2897
+ return {
2898
+ shellType: "zsh",
2899
+ configFile: join(home, ".zshrc")
2900
+ };
2901
+ }
2902
+ if (shell.includes("bash")) {
2903
+ return {
2904
+ shellType: "bash",
2905
+ configFile: join(home, ".bashrc")
2906
+ };
2907
+ }
2908
+ if (shell.includes("fish")) {
2909
+ return {
2910
+ shellType: "fish",
2911
+ configFile: join(home, ".config", "fish", "config.fish")
2912
+ };
2913
+ }
2914
+ const defaultShell = process.platform === "darwin" ? "zsh" : "bash";
2915
+ return {
2916
+ shellType: defaultShell,
2917
+ configFile: join(home, `.${defaultShell}rc`)
2918
+ };
2919
+ }
2733
2920
 
2734
2921
  // src/utils/env.ts
2735
2922
  var VALID_PROVIDERS = [
@@ -2738,7 +2925,21 @@ var VALID_PROVIDERS = [
2738
2925
  "google"
2739
2926
  ];
2740
2927
  function isFirstRun() {
2741
- return !process.env["HYNTX_SERVICES"];
2928
+ if (process.env["HYNTX_SERVICES"]) {
2929
+ return false;
2930
+ }
2931
+ try {
2932
+ const { configFile } = detectShellConfigFile();
2933
+ if (existsSync(configFile)) {
2934
+ const content = readFileSync(configFile, "utf-8");
2935
+ const positions = findMarkerPositions(content);
2936
+ if (positions.startIndex !== -1 && positions.endIndex !== -1 && positions.isValid) {
2937
+ return false;
2938
+ }
2939
+ }
2940
+ } catch {
2941
+ }
2942
+ return true;
2742
2943
  }
2743
2944
  function parseServices(services) {
2744
2945
  if (!services || services.trim() === "") {
package/dist/cli.d.ts CHANGED
@@ -175,9 +175,10 @@ declare function connectProviderWithSpinner(isJsonMode: boolean): Promise<Analys
175
175
  * @param rules - Optional rules configuration
176
176
  * @param isJsonMode - Whether JSON output mode is active
177
177
  * @param noCache - Whether to bypass cache
178
+ * @param extractedPrompts - Optional extracted prompts for cache lookup
178
179
  * @returns Analysis result
179
180
  */
180
- declare function analyzeWithProgress(provider: AnalysisProvider, prompts: readonly string[], date: string, context: ProjectContext | undefined, rules: RulesConfig | undefined, isJsonMode: boolean, noCache?: boolean): Promise<AnalysisResult>;
181
+ declare function analyzeWithProgress(provider: AnalysisProvider, prompts: readonly string[], date: string, context: ProjectContext | undefined, rules: RulesConfig | undefined, isJsonMode: boolean, noCache?: boolean, extractedPrompts?: readonly ExtractedPrompt[]): Promise<AnalysisResult>;
181
182
  /**
182
183
  * Runs watch mode for real-time prompt analysis.
183
184
  *
package/dist/cli.js CHANGED
@@ -489,13 +489,28 @@ var CACHE_DEFAULTS = {
489
489
  };
490
490
 
491
491
  // src/utils/env.ts
492
+ init_shell_config();
492
493
  var VALID_PROVIDERS = [
493
494
  "ollama",
494
495
  "anthropic",
495
496
  "google"
496
497
  ];
497
498
  function isFirstRun() {
498
- return !process.env["HYNTX_SERVICES"];
499
+ if (process.env["HYNTX_SERVICES"]) {
500
+ return false;
501
+ }
502
+ try {
503
+ const { configFile } = detectShellConfigFile();
504
+ if (existsSync(configFile)) {
505
+ const content = readFileSync(configFile, "utf-8");
506
+ const positions = findMarkerPositions(content);
507
+ if (positions.startIndex !== -1 && positions.endIndex !== -1 && positions.isValid) {
508
+ return false;
509
+ }
510
+ }
511
+ } catch {
512
+ }
513
+ return true;
499
514
  }
500
515
  function parseServices(services) {
501
516
  if (!services || services.trim() === "") {
@@ -530,7 +545,10 @@ var HYNTX_HISTORY_DIR = process.env["HYNTX_HISTORY_DIR"] ?? join(HOME, ".hyntx",
530
545
  var HYNTX_CACHE_DIR = process.env["HYNTX_CACHE_DIR"] ?? join(HOME, ".hyntx-cache");
531
546
  var CACHE_ANALYSIS_DIR = join(HYNTX_CACHE_DIR, "analysis");
532
547
  var CACHE_META_FILE = join(CACHE_ANALYSIS_DIR, ".metadata.json");
533
- process.env["HYNTX_RESULTS_DIR"] ?? join(HOME, ".hyntx", "results");
548
+ var HYNTX_RESULTS_DIR = process.env["HYNTX_RESULTS_DIR"] ?? join(HOME, ".hyntx", "results");
549
+ function getResultsDateDir(date) {
550
+ return join(HYNTX_RESULTS_DIR, date);
551
+ }
534
552
 
535
553
  // src/core/schema-validator.ts
536
554
  var SUPPORTED_VERSIONS = ["1.0"];
@@ -1432,63 +1450,178 @@ var ISSUE_TAXONOMY = {
1432
1450
  vague: {
1433
1451
  name: "Vague Request",
1434
1452
  severity: "high",
1435
- suggestion: "Be more specific about what you need",
1453
+ suggestion: "Be more specific about what you need - include function names, file paths, error messages, or specific behaviors",
1436
1454
  exampleBefore: "Help me with my code",
1437
- exampleAfter: "Help me debug this TypeScript function that returns undefined"
1455
+ exampleAfter: "Help me debug the calculateTotal() function in utils.ts that returns undefined when called with an empty array"
1438
1456
  },
1439
1457
  "no-context": {
1440
1458
  name: "Missing Context",
1441
1459
  severity: "high",
1442
- suggestion: "Provide relevant background information",
1460
+ suggestion: "Provide relevant background information - include file paths, function names, error messages, or code snippets",
1443
1461
  exampleBefore: "Fix the bug",
1444
- exampleAfter: "Fix the bug in the authentication flow where users are logged out after 5 minutes"
1462
+ exampleAfter: "Fix the bug in src/auth/login.ts where users are logged out after 5 minutes due to token expiration logic"
1445
1463
  },
1446
1464
  "too-broad": {
1447
1465
  name: "Too Broad",
1448
1466
  severity: "medium",
1449
- suggestion: "Break down into smaller, focused requests",
1450
- exampleBefore: "Build me an app",
1451
- exampleAfter: "Create a React component for displaying user profiles with avatar and bio"
1467
+ suggestion: "Break down into smaller, focused requests - focus on one task or clearly order multiple related tasks",
1468
+ exampleBefore: "Build me an app with authentication, database, and API",
1469
+ exampleAfter: "Create a React login component with email/password authentication using JWT tokens"
1452
1470
  },
1453
1471
  "no-goal": {
1454
1472
  name: "No Clear Goal",
1455
1473
  severity: "high",
1456
- suggestion: "State what outcome you want to achieve",
1474
+ suggestion: "State what outcome you want to achieve - specify success criteria and desired behavior",
1457
1475
  exampleBefore: "Look at this file",
1458
- exampleAfter: "Review this file for security vulnerabilities in the authentication logic"
1476
+ exampleAfter: "Review src/auth/login.ts for security vulnerabilities, focusing on input validation and SQL injection risks"
1459
1477
  },
1460
1478
  imperative: {
1461
1479
  name: "Command Without Context",
1462
1480
  severity: "low",
1463
- suggestion: "Explain why you need this",
1481
+ suggestion: "Explain why you need this - provide context about the use case and requirements",
1464
1482
  exampleBefore: "Add a button",
1465
- exampleAfter: 'Add a "Submit" button to trigger form validation and API submission'
1483
+ exampleAfter: 'Add a "Submit" button to the login form that triggers validation and calls the authentication API'
1484
+ },
1485
+ "missing-technical-details": {
1486
+ name: "Missing Technical Details",
1487
+ severity: "medium",
1488
+ suggestion: "Include technical details - file paths, function signatures, error messages, stack traces, or code snippets",
1489
+ exampleBefore: "The function crashes sometimes",
1490
+ exampleAfter: `The validateUser() function in src/utils/auth.ts crashes with "Cannot read property 'email' of null" when called with undefined`
1491
+ },
1492
+ "unclear-priorities": {
1493
+ name: "Unclear Priorities",
1494
+ severity: "low",
1495
+ suggestion: "Order multiple requests by priority or split into separate prompts for clarity",
1496
+ exampleBefore: "Add error handling and logging and also optimize performance and add tests",
1497
+ exampleAfter: "First, add comprehensive error handling with try-catch blocks. Then, add logging for debugging. Finally, optimize database queries."
1498
+ },
1499
+ "insufficient-constraints": {
1500
+ name: "Insufficient Constraints",
1501
+ severity: "low",
1502
+ suggestion: "Specify requirements and constraints - edge cases, performance needs, compatibility requirements",
1503
+ exampleBefore: "Make it faster",
1504
+ exampleAfter: "Optimize the database query to reduce response time to under 100ms, maintaining backward compatibility with existing API clients"
1466
1505
  }
1467
1506
  };
1468
1507
  var SYSTEM_PROMPT_MINIMAL = `You analyze prompts for quality issues.
1469
1508
  Respond with JSON only: {"issues": ["issue-id", ...], "score": 0-100}
1470
1509
 
1471
- Valid issue IDs: vague, no-context, too-broad, no-goal, imperative
1510
+ Valid issue IDs: vague, no-context, too-broad, no-goal, imperative, missing-technical-details, unclear-priorities, insufficient-constraints
1511
+
1512
+ Issue definitions:
1513
+ - vague: Generic requests without specifics ("help", "fix", "improve")
1514
+ - no-context: Missing background info (uses "this", "it", "the bug" without context)
1515
+ - too-broad: Requests covering multiple unrelated topics
1516
+ - no-goal: Ambiguous success criteria or desired outcome
1517
+ - imperative: Commands without explanation or reasoning
1518
+ - missing-technical-details: No file paths, function names, or error messages
1519
+ - unclear-priorities: Multiple requests without ordering
1520
+ - insufficient-constraints: No requirements or edge cases mentioned
1521
+
1522
+ Scoring: 0-100 (100=perfect, 90+=excellent, 70-89=good, 50-69=fair, <50=poor)
1472
1523
 
1473
1524
  Examples:
1474
1525
  Input: "Help me with code"
1475
- Output: {"issues": ["vague", "no-context"], "score": 40}
1526
+ Output: {"issues": ["vague", "no-context"], "score": 35}
1476
1527
 
1477
1528
  Input: "Debug this TypeScript function that returns undefined"
1478
- Output: {"issues": [], "score": 85}`;
1479
- var SYSTEM_PROMPT_SIMPLE = `Analyze prompts for quality issues. Return ONLY JSON, no other text.
1529
+ Output: {"issues": ["missing-technical-details"], "score": 70}
1530
+
1531
+ Input: "Debug calculateTotal() in utils.ts that returns undefined when called with empty array"
1532
+ Output: {"issues": [], "score": 90}`;
1533
+ var SYSTEM_PROMPT_FULL = `You are an expert prompt quality analyst specializing in code-related prompts for AI assistants like Claude. Your task is to analyze prompts and identify patterns that reduce their effectiveness, providing actionable improvements.
1534
+
1535
+ CRITICAL: Return ONLY valid JSON following the exact schema below. No markdown, no explanations, no code fences - just pure JSON.
1480
1536
 
1481
1537
  Schema:
1482
- {"issues":[{"name":"issue name","example":"bad prompt","fix":"better prompt"}],"score":75,"tip":"main suggestion"}
1538
+ {
1539
+ "patterns": [
1540
+ {
1541
+ "id": "kebab-case-id",
1542
+ "name": "Human-Readable Issue Name",
1543
+ "frequency": 3,
1544
+ "severity": "high|medium|low",
1545
+ "examples": ["example prompt 1", "example prompt 2"],
1546
+ "suggestion": "Actionable advice to fix this pattern",
1547
+ "beforeAfter": {
1548
+ "before": "Original problematic prompt",
1549
+ "after": "Improved version addressing the issue"
1550
+ }
1551
+ }
1552
+ ],
1553
+ "stats": {
1554
+ "totalPrompts": 10,
1555
+ "promptsWithIssues": 7,
1556
+ "overallScore": 65
1557
+ },
1558
+ "topSuggestion": "Single most impactful recommendation"
1559
+ }
1560
+
1561
+ QUALITY DIMENSIONS TO EVALUATE:
1562
+
1563
+ 1. SPECIFICITY (High Priority)
1564
+ - Vague: "help me", "fix this", "improve code" without specifics
1565
+ - Good: Includes function names, file paths, error messages, specific behaviors
1566
+ - Look for: Generic verbs without objects, pronouns without referents
1567
+
1568
+ 2. CONTEXT PROVISION (High Priority)
1569
+ - Missing: References to "this code", "the bug", "it" without background
1570
+ - Good: Provides file paths, function signatures, relevant code snippets, error stack traces
1571
+ - Look for: Unclear referents, assumptions of shared knowledge
1572
+
1573
+ 3. GOAL CLARITY (High Priority)
1574
+ - Unclear: "Look at this", "Review my code", "What's wrong?"
1575
+ - Good: Explicitly states desired outcome: "Find security vulnerabilities", "Optimize for performance", "Fix the null pointer exception"
1576
+ - Look for: Ambiguous success criteria, open-ended questions
1577
+
1578
+ 4. SCOPE APPROPRIATENESS (Medium Priority)
1579
+ - Too broad: "Build me an app", "Refactor everything", multiple unrelated tasks
1580
+ - Too narrow: Overly specific constraints that limit solution space unnecessarily
1581
+ - Good: Focused single task or clearly ordered multiple tasks
1582
+ - Look for: Multiple "and" clauses, unrelated requests, scope creep
1583
+
1584
+ 5. ACTIONABILITY (Medium Priority)
1585
+ - Low: "What do you think?", "Is this good?", purely exploratory
1586
+ - Good: Clear action requested: "Fix", "Implement", "Refactor", "Add"
1587
+ - Look for: Vague intentions, exploration without purpose
1588
+
1589
+ 6. TECHNICAL RICHNESS (Medium Priority)
1590
+ - Missing: No code examples, file paths, function names, error messages
1591
+ - Good: Includes relevant code, stack traces, configuration, environment details
1592
+ - Look for: Purely conceptual descriptions without technical details
1593
+
1594
+ 7. CONSTRAINT DEFINITION (Low Priority)
1595
+ - Missing: No requirements, edge cases, or constraints mentioned
1596
+ - Good: Specifies requirements, edge cases, performance needs, compatibility needs
1597
+ - Look for: Requests that could have many valid interpretations
1598
+
1599
+ SEVERITY GUIDELINES:
1600
+ - high: Significantly impairs prompt effectiveness (vague, missing context, no goal)
1601
+ - medium: Moderate impact on effectiveness (too broad, lacks technical details)
1602
+ - low: Minor improvement opportunity (missing constraints, could be more specific)
1603
+
1604
+ SCORING GUIDELINES (0-100):
1605
+ - 90-100: Excellent prompts - specific, contextual, actionable, well-scoped
1606
+ - 75-89: Good prompts - minor improvements possible
1607
+ - 60-74: Fair prompts - needs more context, clarity, or specificity
1608
+ - 40-59: Poor prompts - multiple significant issues, partially actionable
1609
+ - 20-39: Very poor - barely actionable, missing critical information
1610
+ - 0-19: Extremely poor - cannot be meaningfully acted upon
1611
+
1612
+ PATTERN IDENTIFICATION:
1613
+ - Group similar issues together (same root cause)
1614
+ - Count frequency: how many prompts exhibit this pattern
1615
+ - Provide 1-3 real examples from the actual prompts analyzed
1616
+ - Create meaningful before/after pairs that clearly show improvement
1617
+ - Ensure beforeAfter.before matches one of the examples
1618
+
1619
+ IMPROVEMENT PRIORITIES:
1620
+ 1. High severity patterns (vague, missing context, no goal) should appear first
1621
+ 2. More frequent patterns should rank higher
1622
+ 3. topSuggestion should address the most common high-severity issue
1483
1623
 
1484
- Rules:
1485
- - issues: array of problems found (empty if none)
1486
- - score: 0-100 quality score (100=perfect)
1487
- - tip: single most important suggestion
1488
- - name: short issue name (e.g. "vague request", "missing context")
1489
- - example: actual prompt text showing the issue
1490
- - fix: improved version of that prompt`;
1491
- var SYSTEM_PROMPT_FULL = SYSTEM_PROMPT_SIMPLE;
1624
+ Remember: The goal is actionable feedback. Focus on patterns that, when fixed, would meaningfully improve prompt effectiveness for AI code assistants.`;
1492
1625
  var VALID_PATTERN_IDS = Object.keys(ISSUE_TAXONOMY);
1493
1626
  function applyRulesConfig(rules, baseTaxonomy = ISSUE_TAXONOMY) {
1494
1627
  if (!rules || Object.keys(rules).length === 0) {
@@ -2551,6 +2684,118 @@ ${chalk6.dim(entry.name)}`,
2551
2684
  function formatRulesListJson(entries, compact = false) {
2552
2685
  return compact ? JSON.stringify(entries) : JSON.stringify(entries, null, 2);
2553
2686
  }
2687
+ init_logger_base();
2688
+ function getPromptResultHash(prompt, metadata) {
2689
+ const systemPromptHash = hashSystemPrompt();
2690
+ const input = [
2691
+ prompt,
2692
+ metadata.date,
2693
+ metadata.project ?? "",
2694
+ metadata.model,
2695
+ metadata.schemaType,
2696
+ systemPromptHash
2697
+ ].join("\0");
2698
+ return hashString(input);
2699
+ }
2700
+ async function getPromptResult(prompt, metadata) {
2701
+ const hash = getPromptResultHash(prompt, metadata);
2702
+ const dateDir = getResultsDateDir(metadata.date);
2703
+ const filePath = join(dateDir, `${hash}.json`);
2704
+ if (!existsSync(filePath)) {
2705
+ logger.debug(
2706
+ `Cache miss for prompt on ${metadata.date} (hash: ${hash.slice(0, 8)}...)`,
2707
+ "results"
2708
+ );
2709
+ return null;
2710
+ }
2711
+ try {
2712
+ const content = await readFile(filePath, "utf-8");
2713
+ const data = JSON.parse(content);
2714
+ if (!data.result || !data.metadata) {
2715
+ logger.debug(
2716
+ `Invalid cached result for hash ${hash.slice(0, 8)}...`,
2717
+ "results"
2718
+ );
2719
+ return null;
2720
+ }
2721
+ logger.debug(
2722
+ `Cache hit for prompt on ${metadata.date} (hash: ${hash.slice(0, 8)}...)`,
2723
+ "results"
2724
+ );
2725
+ return data.result;
2726
+ } catch (error) {
2727
+ const errorMessage = error instanceof Error ? error.message : String(error);
2728
+ logger.debug(
2729
+ `Failed to read cached result ${hash.slice(0, 8)}...: ${errorMessage}`,
2730
+ "results"
2731
+ );
2732
+ return null;
2733
+ }
2734
+ }
2735
+ async function ensureDateDir(date) {
2736
+ const dateDir = getResultsDateDir(date);
2737
+ await mkdir(dateDir, { recursive: true, mode: 448 });
2738
+ }
2739
+ async function savePromptResult(prompt, result, metadata) {
2740
+ try {
2741
+ await ensureDateDir(metadata.date);
2742
+ const hash = getPromptResultHash(prompt, metadata);
2743
+ const promptHash = hashString(prompt);
2744
+ const fullMetadata = {
2745
+ ...metadata,
2746
+ promptHash,
2747
+ analyzedAt: Date.now()
2748
+ };
2749
+ const promptResult = {
2750
+ result,
2751
+ metadata: fullMetadata
2752
+ };
2753
+ const dateDir = getResultsDateDir(metadata.date);
2754
+ const filePath = join(dateDir, `${hash}.json`);
2755
+ const content = JSON.stringify(promptResult, null, 2);
2756
+ const tmpFile = `${filePath}.tmp`;
2757
+ await writeFile(tmpFile, content, "utf-8");
2758
+ await rename(tmpFile, filePath);
2759
+ logger.debug(
2760
+ `Saved result for prompt on ${metadata.date} (hash: ${hash.slice(0, 8)}...)`,
2761
+ "results"
2762
+ );
2763
+ } catch (error) {
2764
+ const errorMessage = error instanceof Error ? error.message : String(error);
2765
+ logger.warn(
2766
+ `Failed to save prompt result for ${metadata.date}: ${errorMessage}`,
2767
+ "results"
2768
+ );
2769
+ }
2770
+ }
2771
+ async function getPromptsWithCache(prompts3, model, schemaType) {
2772
+ const cacheResults = await Promise.all(
2773
+ prompts3.map(async (prompt) => {
2774
+ const result = await getPromptResult(prompt.content, {
2775
+ date: prompt.date,
2776
+ project: prompt.project,
2777
+ model,
2778
+ schemaType
2779
+ });
2780
+ return { prompt, result };
2781
+ })
2782
+ );
2783
+ const cached = /* @__PURE__ */ new Map();
2784
+ const toAnalyze = [];
2785
+ for (const { prompt, result } of cacheResults) {
2786
+ if (result) {
2787
+ cached.set(prompt.content, result);
2788
+ } else {
2789
+ toAnalyze.push(prompt);
2790
+ }
2791
+ }
2792
+ const hitRate = prompts3.length > 0 ? (cached.size / prompts3.length * 100).toFixed(1) : "0.0";
2793
+ logger.debug(
2794
+ `Cache: ${String(cached.size)} hits, ${String(toAnalyze.length)} misses (${hitRate}% hit rate)`,
2795
+ "results"
2796
+ );
2797
+ return { cached, toAnalyze };
2798
+ }
2554
2799
 
2555
2800
  // src/providers/index.ts
2556
2801
  init_logger_base();
@@ -2606,6 +2851,32 @@ function extractRealExamples(issueId, prompts3, limit = 3) {
2606
2851
  case "imperative":
2607
2852
  isMatch = trimmed.length < 20 && wordCount <= 3 && /^(add|delete|remove|update|change|modify)\b/.exec(lowerPrompt) !== null && !lowerPrompt.includes("?");
2608
2853
  break;
2854
+ case "missing-technical-details": {
2855
+ const hasFileRef = /\w+\.(ts|js|tsx|jsx|py|go|java|rb|php|json|yaml|yml)\b/.exec(
2856
+ lowerPrompt
2857
+ ) !== null;
2858
+ const hasFunctionRef = /function|def |class |const |let |var |(\.\w+\()/.exec(
2859
+ lowerPrompt
2860
+ ) !== null;
2861
+ const hasErrorRef = /error|exception|failed|crash|undefined|null/.exec(lowerPrompt) !== null;
2862
+ isMatch = !hasFileRef && !hasFunctionRef && !hasErrorRef && wordCount >= 3;
2863
+ break;
2864
+ }
2865
+ case "unclear-priorities": {
2866
+ const andMatches = lowerPrompt.match(/\band\b/g);
2867
+ const orMatches = lowerPrompt.match(/\bor\b/g);
2868
+ const alsoMatches = lowerPrompt.match(/\balso\b/g);
2869
+ const conjunctionCount = (andMatches?.length ?? 0) + (orMatches?.length ?? 0) + (alsoMatches?.length ?? 0);
2870
+ isMatch = conjunctionCount >= 2 && !/\b(first|second|third|then|next|finally|after|before)\b/.exec(
2871
+ lowerPrompt
2872
+ ) && wordCount >= 10;
2873
+ break;
2874
+ }
2875
+ case "insufficient-constraints":
2876
+ isMatch = !/\b(constraint|requirement|must|should|edge case|boundary|limit|performance|compatib)\b/.exec(
2877
+ lowerPrompt
2878
+ ) && !/\b(<|>|<=|>=|\d+ms|\d+mb|\d+kb)\b/.exec(lowerPrompt) && (lowerPrompt.includes("optimize") || lowerPrompt.includes("improve") || lowerPrompt.includes("make") || lowerPrompt.includes("add")) && wordCount >= 4;
2879
+ break;
2609
2880
  default:
2610
2881
  isMatch = false;
2611
2882
  }
@@ -5385,24 +5656,62 @@ ${errorMessage}
5385
5656
  process.exit(EXIT_CODES.PROVIDER_UNAVAILABLE);
5386
5657
  }
5387
5658
  }
5388
- async function analyzeWithProgress(provider, prompts3, date, context, rules, isJsonMode, noCache) {
5389
- const spinner = isJsonMode ? null : ora(`Analyzing ${String(prompts3.length)} prompts...`).start();
5659
+ async function analyzeWithProgress(provider, prompts3, date, context, rules, isJsonMode, noCache, extractedPrompts) {
5660
+ let cachedResults;
5661
+ let promptsToAnalyze = prompts3;
5662
+ if (extractedPrompts) {
5663
+ const cacheResult = await loadAndFilterCachedResults(
5664
+ extractedPrompts,
5665
+ provider,
5666
+ noCache
5667
+ );
5668
+ cachedResults = cacheResult.cachedResults;
5669
+ promptsToAnalyze = cacheResult.toAnalyze;
5670
+ }
5671
+ const total = prompts3.length;
5672
+ const cached = cachedResults?.size ?? 0;
5673
+ const cacheInfo = cached > 0 ? ` (${String(cached)} cached)` : "";
5674
+ const spinner = isJsonMode ? null : ora(`Analyzing ${String(total)} prompts${cacheInfo}...`).start();
5390
5675
  try {
5391
5676
  const result = await analyzePrompts({
5392
5677
  provider,
5393
- prompts: prompts3,
5678
+ prompts: promptsToAnalyze,
5394
5679
  date,
5395
5680
  context,
5396
5681
  rules,
5397
- onProgress: (current, total) => {
5398
- if (!isJsonMode && spinner && total > 1) {
5399
- spinner.text = `Analyzing ${String(prompts3.length)} prompts (batch ${String(current + 1)}/${String(total)})...`;
5682
+ onProgress: (current, batchTotal) => {
5683
+ if (!isJsonMode && spinner && batchTotal > 1) {
5684
+ spinner.text = `Analyzing ${String(total)} prompts${cacheInfo} (batch ${String(current + 1)}/${String(batchTotal)})...`;
5400
5685
  }
5401
5686
  },
5402
- noCache
5687
+ noCache,
5688
+ cachedResults
5403
5689
  });
5690
+ if (!noCache && extractedPrompts?.length === 1 && promptsToAnalyze.length === 1) {
5691
+ const prompt = extractedPrompts[0];
5692
+ if (prompt) {
5693
+ const model = extractModelFromProvider(provider.name);
5694
+ const schemaType = determineSchemaType(provider);
5695
+ try {
5696
+ await savePromptResult(prompt.content, result, {
5697
+ date: prompt.date,
5698
+ project: prompt.project,
5699
+ provider: provider.name,
5700
+ model,
5701
+ schemaType
5702
+ });
5703
+ } catch (error) {
5704
+ const errorMessage = error instanceof Error ? error.message : String(error);
5705
+ logger2.debug(
5706
+ `Failed to save prompt result: ${errorMessage}`,
5707
+ "results"
5708
+ );
5709
+ }
5710
+ }
5711
+ }
5404
5712
  if (!isJsonMode) {
5405
- spinner?.succeed(chalk6.green("Analysis complete"));
5713
+ const hitRate = total > 0 && cached > 0 ? ` - ${(cached / total * 100).toFixed(0)}% cached` : "";
5714
+ spinner?.succeed(chalk6.green(`Analysis complete${hitRate}`));
5406
5715
  }
5407
5716
  return result;
5408
5717
  } catch (error) {
@@ -5419,6 +5728,57 @@ async function analyzeWithProgress(provider, prompts3, date, context, rules, isJ
5419
5728
  process.exit(EXIT_CODES.ERROR);
5420
5729
  }
5421
5730
  }
5731
+ function determineSchemaType(provider) {
5732
+ const providerName = provider.name.toLowerCase();
5733
+ if (providerName.includes("anthropic")) {
5734
+ return "anthropic";
5735
+ }
5736
+ if (providerName.includes("ollama")) {
5737
+ return "ollama";
5738
+ }
5739
+ if (providerName.includes("google")) {
5740
+ return "google";
5741
+ }
5742
+ return "ollama";
5743
+ }
5744
+ async function loadAndFilterCachedResults(extractedPrompts, provider, noCache) {
5745
+ if (noCache) {
5746
+ logger2.debug("Cache disabled, analyzing all prompts", "results");
5747
+ return {
5748
+ cachedResults: /* @__PURE__ */ new Map(),
5749
+ toAnalyze: extractedPrompts.map((p) => p.content)
5750
+ };
5751
+ }
5752
+ try {
5753
+ const model = extractModelFromProvider(provider.name);
5754
+ const schemaType = determineSchemaType(provider);
5755
+ const { cached, toAnalyze } = await getPromptsWithCache(
5756
+ extractedPrompts,
5757
+ model,
5758
+ schemaType
5759
+ );
5760
+ const total = extractedPrompts.length;
5761
+ const hitRate = total > 0 ? (cached.size / total * 100).toFixed(1) : "0.0";
5762
+ logger2.debug(
5763
+ `Results cache: ${String(cached.size)}/${String(total)} hits (${hitRate}%)`,
5764
+ "results"
5765
+ );
5766
+ return {
5767
+ cachedResults: cached,
5768
+ toAnalyze: toAnalyze.map((p) => p.content)
5769
+ };
5770
+ } catch (error) {
5771
+ const errorMessage = error instanceof Error ? error.message : String(error);
5772
+ logger2.warn(
5773
+ `Failed to load cached results: ${errorMessage}. Analyzing all prompts.`,
5774
+ "results"
5775
+ );
5776
+ return {
5777
+ cachedResults: /* @__PURE__ */ new Map(),
5778
+ toAnalyze: extractedPrompts.map((p) => p.content)
5779
+ };
5780
+ }
5781
+ }
5422
5782
  function generatePromptKey(prompt) {
5423
5783
  return `${prompt.project}:${prompt.sessionId}:${prompt.timestamp}`;
5424
5784
  }
@@ -5463,13 +5823,55 @@ async function runWatchMode(provider, args, context, rules) {
5463
5823
  analyzedPrompts.set(promptKey, Date.now());
5464
5824
  void (async () => {
5465
5825
  try {
5466
- const result = await analyzePrompts({
5467
- provider,
5468
- prompts: [prompt.content],
5469
- date: prompt.date,
5470
- context,
5471
- rules
5472
- });
5826
+ let result;
5827
+ if (!args.noCache) {
5828
+ const model = extractModelFromProvider(provider.name);
5829
+ const schemaType = determineSchemaType(provider);
5830
+ const cachedResult = await getPromptResult(prompt.content, {
5831
+ date: prompt.date,
5832
+ project: prompt.project,
5833
+ model,
5834
+ schemaType
5835
+ });
5836
+ if (cachedResult) {
5837
+ logger2.debug(
5838
+ `Watch mode: using cached result for prompt on ${prompt.date}`,
5839
+ "results"
5840
+ );
5841
+ result = cachedResult;
5842
+ } else {
5843
+ result = await analyzePrompts({
5844
+ provider,
5845
+ prompts: [prompt.content],
5846
+ date: prompt.date,
5847
+ context,
5848
+ rules
5849
+ });
5850
+ try {
5851
+ await savePromptResult(prompt.content, result, {
5852
+ date: prompt.date,
5853
+ project: prompt.project,
5854
+ provider: provider.name,
5855
+ model,
5856
+ schemaType
5857
+ });
5858
+ } catch (error) {
5859
+ const errorMessage = error instanceof Error ? error.message : String(error);
5860
+ logger2.debug(
5861
+ `Failed to save prompt result in watch mode: ${errorMessage}`,
5862
+ "results"
5863
+ );
5864
+ }
5865
+ }
5866
+ } else {
5867
+ result = await analyzePrompts({
5868
+ provider,
5869
+ prompts: [prompt.content],
5870
+ date: prompt.date,
5871
+ context,
5872
+ rules
5873
+ });
5874
+ }
5473
5875
  const now = /* @__PURE__ */ new Date();
5474
5876
  const timeStr = now.toLocaleTimeString("en-US", {
5475
5877
  hour12: false,
@@ -5637,7 +6039,8 @@ async function cli() {
5637
6039
  config.context,
5638
6040
  config.rules,
5639
6041
  isJsonMode,
5640
- args.noCache
6042
+ args.noCache,
6043
+ group.prompts
5641
6044
  );
5642
6045
  results.push(result);
5643
6046
  }
@@ -5713,7 +6116,8 @@ async function cli() {
5713
6116
  config.context,
5714
6117
  config.rules,
5715
6118
  isJsonMode,
5716
- args.noCache
6119
+ args.noCache,
6120
+ logResult.prompts
5717
6121
  );
5718
6122
  if (args.output) {
5719
6123
  const ext = extname(args.output);
package/dist/index.js CHANGED
@@ -389,63 +389,178 @@ var ISSUE_TAXONOMY = {
389
389
  vague: {
390
390
  name: "Vague Request",
391
391
  severity: "high",
392
- suggestion: "Be more specific about what you need",
392
+ suggestion: "Be more specific about what you need - include function names, file paths, error messages, or specific behaviors",
393
393
  exampleBefore: "Help me with my code",
394
- exampleAfter: "Help me debug this TypeScript function that returns undefined"
394
+ exampleAfter: "Help me debug the calculateTotal() function in utils.ts that returns undefined when called with an empty array"
395
395
  },
396
396
  "no-context": {
397
397
  name: "Missing Context",
398
398
  severity: "high",
399
- suggestion: "Provide relevant background information",
399
+ suggestion: "Provide relevant background information - include file paths, function names, error messages, or code snippets",
400
400
  exampleBefore: "Fix the bug",
401
- exampleAfter: "Fix the bug in the authentication flow where users are logged out after 5 minutes"
401
+ exampleAfter: "Fix the bug in src/auth/login.ts where users are logged out after 5 minutes due to token expiration logic"
402
402
  },
403
403
  "too-broad": {
404
404
  name: "Too Broad",
405
405
  severity: "medium",
406
- suggestion: "Break down into smaller, focused requests",
407
- exampleBefore: "Build me an app",
408
- exampleAfter: "Create a React component for displaying user profiles with avatar and bio"
406
+ suggestion: "Break down into smaller, focused requests - focus on one task or clearly order multiple related tasks",
407
+ exampleBefore: "Build me an app with authentication, database, and API",
408
+ exampleAfter: "Create a React login component with email/password authentication using JWT tokens"
409
409
  },
410
410
  "no-goal": {
411
411
  name: "No Clear Goal",
412
412
  severity: "high",
413
- suggestion: "State what outcome you want to achieve",
413
+ suggestion: "State what outcome you want to achieve - specify success criteria and desired behavior",
414
414
  exampleBefore: "Look at this file",
415
- exampleAfter: "Review this file for security vulnerabilities in the authentication logic"
415
+ exampleAfter: "Review src/auth/login.ts for security vulnerabilities, focusing on input validation and SQL injection risks"
416
416
  },
417
417
  imperative: {
418
418
  name: "Command Without Context",
419
419
  severity: "low",
420
- suggestion: "Explain why you need this",
420
+ suggestion: "Explain why you need this - provide context about the use case and requirements",
421
421
  exampleBefore: "Add a button",
422
- exampleAfter: 'Add a "Submit" button to trigger form validation and API submission'
422
+ exampleAfter: 'Add a "Submit" button to the login form that triggers validation and calls the authentication API'
423
+ },
424
+ "missing-technical-details": {
425
+ name: "Missing Technical Details",
426
+ severity: "medium",
427
+ suggestion: "Include technical details - file paths, function signatures, error messages, stack traces, or code snippets",
428
+ exampleBefore: "The function crashes sometimes",
429
+ exampleAfter: `The validateUser() function in src/utils/auth.ts crashes with "Cannot read property 'email' of null" when called with undefined`
430
+ },
431
+ "unclear-priorities": {
432
+ name: "Unclear Priorities",
433
+ severity: "low",
434
+ suggestion: "Order multiple requests by priority or split into separate prompts for clarity",
435
+ exampleBefore: "Add error handling and logging and also optimize performance and add tests",
436
+ exampleAfter: "First, add comprehensive error handling with try-catch blocks. Then, add logging for debugging. Finally, optimize database queries."
437
+ },
438
+ "insufficient-constraints": {
439
+ name: "Insufficient Constraints",
440
+ severity: "low",
441
+ suggestion: "Specify requirements and constraints - edge cases, performance needs, compatibility requirements",
442
+ exampleBefore: "Make it faster",
443
+ exampleAfter: "Optimize the database query to reduce response time to under 100ms, maintaining backward compatibility with existing API clients"
423
444
  }
424
445
  };
425
446
  var SYSTEM_PROMPT_MINIMAL = `You analyze prompts for quality issues.
426
447
  Respond with JSON only: {"issues": ["issue-id", ...], "score": 0-100}
427
448
 
428
- Valid issue IDs: vague, no-context, too-broad, no-goal, imperative
449
+ Valid issue IDs: vague, no-context, too-broad, no-goal, imperative, missing-technical-details, unclear-priorities, insufficient-constraints
450
+
451
+ Issue definitions:
452
+ - vague: Generic requests without specifics ("help", "fix", "improve")
453
+ - no-context: Missing background info (uses "this", "it", "the bug" without context)
454
+ - too-broad: Requests covering multiple unrelated topics
455
+ - no-goal: Ambiguous success criteria or desired outcome
456
+ - imperative: Commands without explanation or reasoning
457
+ - missing-technical-details: No file paths, function names, or error messages
458
+ - unclear-priorities: Multiple requests without ordering
459
+ - insufficient-constraints: No requirements or edge cases mentioned
460
+
461
+ Scoring: 0-100 (100=perfect, 90+=excellent, 70-89=good, 50-69=fair, <50=poor)
429
462
 
430
463
  Examples:
431
464
  Input: "Help me with code"
432
- Output: {"issues": ["vague", "no-context"], "score": 40}
465
+ Output: {"issues": ["vague", "no-context"], "score": 35}
433
466
 
434
467
  Input: "Debug this TypeScript function that returns undefined"
435
- Output: {"issues": [], "score": 85}`;
436
- var SYSTEM_PROMPT_SIMPLE = `Analyze prompts for quality issues. Return ONLY JSON, no other text.
468
+ Output: {"issues": ["missing-technical-details"], "score": 70}
469
+
470
+ Input: "Debug calculateTotal() in utils.ts that returns undefined when called with empty array"
471
+ Output: {"issues": [], "score": 90}`;
472
+ var SYSTEM_PROMPT_FULL = `You are an expert prompt quality analyst specializing in code-related prompts for AI assistants like Claude. Your task is to analyze prompts and identify patterns that reduce their effectiveness, providing actionable improvements.
473
+
474
+ CRITICAL: Return ONLY valid JSON following the exact schema below. No markdown, no explanations, no code fences - just pure JSON.
437
475
 
438
476
  Schema:
439
- {"issues":[{"name":"issue name","example":"bad prompt","fix":"better prompt"}],"score":75,"tip":"main suggestion"}
477
+ {
478
+ "patterns": [
479
+ {
480
+ "id": "kebab-case-id",
481
+ "name": "Human-Readable Issue Name",
482
+ "frequency": 3,
483
+ "severity": "high|medium|low",
484
+ "examples": ["example prompt 1", "example prompt 2"],
485
+ "suggestion": "Actionable advice to fix this pattern",
486
+ "beforeAfter": {
487
+ "before": "Original problematic prompt",
488
+ "after": "Improved version addressing the issue"
489
+ }
490
+ }
491
+ ],
492
+ "stats": {
493
+ "totalPrompts": 10,
494
+ "promptsWithIssues": 7,
495
+ "overallScore": 65
496
+ },
497
+ "topSuggestion": "Single most impactful recommendation"
498
+ }
499
+
500
+ QUALITY DIMENSIONS TO EVALUATE:
501
+
502
+ 1. SPECIFICITY (High Priority)
503
+ - Vague: "help me", "fix this", "improve code" without specifics
504
+ - Good: Includes function names, file paths, error messages, specific behaviors
505
+ - Look for: Generic verbs without objects, pronouns without referents
440
506
 
441
- Rules:
442
- - issues: array of problems found (empty if none)
443
- - score: 0-100 quality score (100=perfect)
444
- - tip: single most important suggestion
445
- - name: short issue name (e.g. "vague request", "missing context")
446
- - example: actual prompt text showing the issue
447
- - fix: improved version of that prompt`;
448
- var SYSTEM_PROMPT_FULL = SYSTEM_PROMPT_SIMPLE;
507
+ 2. CONTEXT PROVISION (High Priority)
508
+ - Missing: References to "this code", "the bug", "it" without background
509
+ - Good: Provides file paths, function signatures, relevant code snippets, error stack traces
510
+ - Look for: Unclear referents, assumptions of shared knowledge
511
+
512
+ 3. GOAL CLARITY (High Priority)
513
+ - Unclear: "Look at this", "Review my code", "What's wrong?"
514
+ - Good: Explicitly states desired outcome: "Find security vulnerabilities", "Optimize for performance", "Fix the null pointer exception"
515
+ - Look for: Ambiguous success criteria, open-ended questions
516
+
517
+ 4. SCOPE APPROPRIATENESS (Medium Priority)
518
+ - Too broad: "Build me an app", "Refactor everything", multiple unrelated tasks
519
+ - Too narrow: Overly specific constraints that limit solution space unnecessarily
520
+ - Good: Focused single task or clearly ordered multiple tasks
521
+ - Look for: Multiple "and" clauses, unrelated requests, scope creep
522
+
523
+ 5. ACTIONABILITY (Medium Priority)
524
+ - Low: "What do you think?", "Is this good?", purely exploratory
525
+ - Good: Clear action requested: "Fix", "Implement", "Refactor", "Add"
526
+ - Look for: Vague intentions, exploration without purpose
527
+
528
+ 6. TECHNICAL RICHNESS (Medium Priority)
529
+ - Missing: No code examples, file paths, function names, error messages
530
+ - Good: Includes relevant code, stack traces, configuration, environment details
531
+ - Look for: Purely conceptual descriptions without technical details
532
+
533
+ 7. CONSTRAINT DEFINITION (Low Priority)
534
+ - Missing: No requirements, edge cases, or constraints mentioned
535
+ - Good: Specifies requirements, edge cases, performance needs, compatibility needs
536
+ - Look for: Requests that could have many valid interpretations
537
+
538
+ SEVERITY GUIDELINES:
539
+ - high: Significantly impairs prompt effectiveness (vague, missing context, no goal)
540
+ - medium: Moderate impact on effectiveness (too broad, lacks technical details)
541
+ - low: Minor improvement opportunity (missing constraints, could be more specific)
542
+
543
+ SCORING GUIDELINES (0-100):
544
+ - 90-100: Excellent prompts - specific, contextual, actionable, well-scoped
545
+ - 75-89: Good prompts - minor improvements possible
546
+ - 60-74: Fair prompts - needs more context, clarity, or specificity
547
+ - 40-59: Poor prompts - multiple significant issues, partially actionable
548
+ - 20-39: Very poor - barely actionable, missing critical information
549
+ - 0-19: Extremely poor - cannot be meaningfully acted upon
550
+
551
+ PATTERN IDENTIFICATION:
552
+ - Group similar issues together (same root cause)
553
+ - Count frequency: how many prompts exhibit this pattern
554
+ - Provide 1-3 real examples from the actual prompts analyzed
555
+ - Create meaningful before/after pairs that clearly show improvement
556
+ - Ensure beforeAfter.before matches one of the examples
557
+
558
+ IMPROVEMENT PRIORITIES:
559
+ 1. High severity patterns (vague, missing context, no goal) should appear first
560
+ 2. More frequent patterns should rank higher
561
+ 3. topSuggestion should address the most common high-severity issue
562
+
563
+ Remember: The goal is actionable feedback. Focus on patterns that, when fixed, would meaningfully improve prompt effectiveness for AI code assistants.`;
449
564
  var VALID_PATTERN_IDS = Object.keys(ISSUE_TAXONOMY);
450
565
  function applyRulesConfig(rules, baseTaxonomy = ISSUE_TAXONOMY) {
451
566
  if (!rules || Object.keys(rules).length === 0) {
@@ -1822,6 +1937,32 @@ function extractRealExamples(issueId, prompts, limit = 3) {
1822
1937
  case "imperative":
1823
1938
  isMatch = trimmed.length < 20 && wordCount <= 3 && /^(add|delete|remove|update|change|modify)\b/.exec(lowerPrompt) !== null && !lowerPrompt.includes("?");
1824
1939
  break;
1940
+ case "missing-technical-details": {
1941
+ const hasFileRef = /\w+\.(ts|js|tsx|jsx|py|go|java|rb|php|json|yaml|yml)\b/.exec(
1942
+ lowerPrompt
1943
+ ) !== null;
1944
+ const hasFunctionRef = /function|def |class |const |let |var |(\.\w+\()/.exec(
1945
+ lowerPrompt
1946
+ ) !== null;
1947
+ const hasErrorRef = /error|exception|failed|crash|undefined|null/.exec(lowerPrompt) !== null;
1948
+ isMatch = !hasFileRef && !hasFunctionRef && !hasErrorRef && wordCount >= 3;
1949
+ break;
1950
+ }
1951
+ case "unclear-priorities": {
1952
+ const andMatches = lowerPrompt.match(/\band\b/g);
1953
+ const orMatches = lowerPrompt.match(/\bor\b/g);
1954
+ const alsoMatches = lowerPrompt.match(/\balso\b/g);
1955
+ const conjunctionCount = (andMatches?.length ?? 0) + (orMatches?.length ?? 0) + (alsoMatches?.length ?? 0);
1956
+ isMatch = conjunctionCount >= 2 && !/\b(first|second|third|then|next|finally|after|before)\b/.exec(
1957
+ lowerPrompt
1958
+ ) && wordCount >= 10;
1959
+ break;
1960
+ }
1961
+ case "insufficient-constraints":
1962
+ isMatch = !/\b(constraint|requirement|must|should|edge case|boundary|limit|performance|compatib)\b/.exec(
1963
+ lowerPrompt
1964
+ ) && !/\b(<|>|<=|>=|\d+ms|\d+mb|\d+kb)\b/.exec(lowerPrompt) && (lowerPrompt.includes("optimize") || lowerPrompt.includes("improve") || lowerPrompt.includes("make") || lowerPrompt.includes("add")) && wordCount >= 4;
1965
+ break;
1825
1966
  default:
1826
1967
  isMatch = false;
1827
1968
  }
@@ -2730,6 +2871,52 @@ function getAllProviders(config) {
2730
2871
  }
2731
2872
  return config.services.map((type) => createProvider(type, config));
2732
2873
  }
2874
+ var START_MARKER = "# >>> hyntx config >>>";
2875
+ var END_MARKER = "# <<< hyntx config <<<";
2876
+ function findMarkerPositions(content) {
2877
+ const startIndex = content.indexOf(START_MARKER);
2878
+ const endIndex = content.indexOf(END_MARKER);
2879
+ if (startIndex === -1 && endIndex === -1) {
2880
+ return { startIndex: -1, endIndex: -1, isValid: true };
2881
+ }
2882
+ if (startIndex !== -1 && endIndex === -1) {
2883
+ return { startIndex, endIndex: -1, isValid: false, issue: "missing_end" };
2884
+ }
2885
+ if (startIndex === -1 && endIndex !== -1) {
2886
+ return { startIndex: -1, endIndex, isValid: false, issue: "missing_start" };
2887
+ }
2888
+ if (startIndex > endIndex) {
2889
+ return { startIndex, endIndex, isValid: false, issue: "wrong_order" };
2890
+ }
2891
+ return { startIndex, endIndex, isValid: true };
2892
+ }
2893
+ function detectShellConfigFile() {
2894
+ const home = homedir();
2895
+ const shell = process.env["SHELL"] ?? "";
2896
+ if (shell.includes("zsh")) {
2897
+ return {
2898
+ shellType: "zsh",
2899
+ configFile: join(home, ".zshrc")
2900
+ };
2901
+ }
2902
+ if (shell.includes("bash")) {
2903
+ return {
2904
+ shellType: "bash",
2905
+ configFile: join(home, ".bashrc")
2906
+ };
2907
+ }
2908
+ if (shell.includes("fish")) {
2909
+ return {
2910
+ shellType: "fish",
2911
+ configFile: join(home, ".config", "fish", "config.fish")
2912
+ };
2913
+ }
2914
+ const defaultShell = process.platform === "darwin" ? "zsh" : "bash";
2915
+ return {
2916
+ shellType: defaultShell,
2917
+ configFile: join(home, `.${defaultShell}rc`)
2918
+ };
2919
+ }
2733
2920
 
2734
2921
  // src/utils/env.ts
2735
2922
  var VALID_PROVIDERS = [
@@ -2738,7 +2925,21 @@ var VALID_PROVIDERS = [
2738
2925
  "google"
2739
2926
  ];
2740
2927
  function isFirstRun() {
2741
- return !process.env["HYNTX_SERVICES"];
2928
+ if (process.env["HYNTX_SERVICES"]) {
2929
+ return false;
2930
+ }
2931
+ try {
2932
+ const { configFile } = detectShellConfigFile();
2933
+ if (existsSync(configFile)) {
2934
+ const content = readFileSync(configFile, "utf-8");
2935
+ const positions = findMarkerPositions(content);
2936
+ if (positions.startIndex !== -1 && positions.endIndex !== -1 && positions.isValid) {
2937
+ return false;
2938
+ }
2939
+ }
2940
+ } catch {
2941
+ }
2942
+ return true;
2742
2943
  }
2743
2944
  function parseServices(services) {
2744
2945
  if (!services || services.trim() === "") {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hyntx",
3
- "version": "2.2.1",
3
+ "version": "2.4.0",
4
4
  "description": "CLI that analyzes Claude Code prompts and generates improvement suggestions",
5
5
  "type": "module",
6
6
  "engines": {
@@ -23,6 +23,7 @@
23
23
  "@jmlweb/tsconfig-base": "^1.0.0",
24
24
  "@jmlweb/vitest-config": "^1.0.0",
25
25
  "@semantic-release/changelog": "^6.0.3",
26
+ "@semantic-release/exec": "^6.0.3",
26
27
  "@semantic-release/git": "^10.0.1",
27
28
  "@types/figlet": "^1.7.0",
28
29
  "@types/node": "^25.0.3",