Add implementation plan for PromptGetException in Prompts

Author: josbeir

IMPLEMENTATION_PLAN_PROMPT_EXCEPTIONS.md

@@ -0,0 +1,200 @@
+# Implementation Plan: PromptGetException in Prompts
+
+## Objective
+Add proper error handling to all prompt classes by implementing validation and throwing `PromptGetException` from `Mcp\Exception\PromptGetException` when invalid parameters are provided.
+
+## Overview
+
+Each prompt accepts parameters that define behavior. These should be validated before processing, and `PromptGetException` should be thrown for invalid inputs.
+
+- **PromptNotFoundException**: For prompts that don't exist (handled by framework)
+- **PromptGetException**: For runtime errors during prompt execution (our responsibility)
+
+## Current State Analysis
+
+| Prompt | Parameters | Current Validation | Status |
+|--------|-----------|-------------------|--------|
+| DocumentationExpertPrompt | `$depth` | Falls back to default | ❌ Needs validation |
+| DebugHelperPrompt | `$context` | Checks empty only | ❌ Needs validation |
+| FeatureBuilderPrompt | `$component` | Likely no validation | ❌ Needs validation |
+| DatabaseExplorerPrompt | `$table`, `$show` | No validation | ❌ Needs validation |
+| CodeReviewerPrompt | `$focus` | Unknown | ❌ Needs validation |
+| MigrationGuidePrompt | `$fromVersion`, `$toVersion`, `$area` | No validation | ❌ Needs validation |
+| TestingAssistantPrompt | `$testType` | Unknown | ❌ Needs validation |
+| PerformanceAnalyzerPrompt | `$context` | Unknown | ❌ Needs validation |
+| OrmQueryHelperPrompt | `$queryGoal`, `$tables` | Unknown | ❌ Needs validation |
+| TinkerWorkshopPrompt | `$goal` | Unknown | ❌ Needs validation |
+| QualityAssurancePrompt | `$context`, `$tools` | Unknown | ❌ Needs validation |
+
+## Implementation Strategy
+
+### Phase 1: Add Validation Infrastructure to AbstractPrompt
+
+**File**: `src/Prompts/AbstractPrompt.php`
+
+Add utility methods for parameter validation:
+
+```php
+/**
+ * Validate that a parameter value is one of allowed values
+ * 
+ * @param string $value The parameter value
+ * @param array<string> $allowed Allowed values
+ * @param string $paramName The parameter name (for error message)
+ * @return void
+ * @throws \Mcp\Exception\PromptGetException
+ */
+protected function validateEnumParameter(
+    string $value, 
+    array $allowed, 
+    string $paramName
+): void;
+
+/**
+ * Validate that a parameter is not empty
+ * 
+ * @param string $value The parameter value
+ * @param string $paramName The parameter name (for error message)
+ * @return void
+ * @throws \Mcp\Exception\PromptGetException
+ */
+protected function validateNonEmptyParameter(string $value, string $paramName): void;
+
+/**
+ * Validate comma-separated values against allowed list
+ * 
+ * @param string $value Comma-separated values
+ * @param array<string> $allowed Allowed values
+ * @param string $paramName The parameter name (for error message)
+ * @return void
+ * @throws \Mcp\Exception\PromptGetException
+ */
+protected function validateCommaSeparatedParameter(
+    string $value,
+    array $allowed,
+    string $paramName
+): void;
+```
+
+### Phase 2: Update Prompts (Priority Order)
+
+#### High Priority
+
+**1. DocumentationExpertPrompt**
+- Validate: `$depth` ∈ ['basic', 'intermediate', 'advanced']
+- Action: Replace `match()` default with exception
+
+**2. DebugHelperPrompt**
+- Validate: `$context` ∈ ['', 'controller', 'model', 'database', 'view']
+- Action: Add enum validation
+
+**3. FeatureBuilderPrompt**
+- Validate: `$component` ∈ ['controller', 'model', 'behavior', 'helper', 'middleware', 'command', 'full-stack']
+- Action: Add enum validation
+
+#### Medium Priority
+
+**4. DatabaseExplorerPrompt**
+- Validate: `$show` ∈ ['schema', 'data', 'relationships', 'all']
+- Validate: `$table` is not empty
+- Action: Add enum and non-empty validation
+
+**5. CodeReviewerPrompt**
+- Validate: `$focus` ∈ ['conventions', 'security', 'performance', 'testing', 'all']
+- Action: Add enum validation
+
+**6. QualityAssurancePrompt**
+- Validate: `$context` ∈ ['guidelines', 'integration', 'troubleshooting', 'all']
+- Validate: `$tools` contains valid tool names
+- Action: Add enum and comma-separated validation
+
+#### Low Priority
+
+**7. TestingAssistantPrompt**
+- Validate: `$testType` ∈ ['unit', 'integration', 'fixture', 'all']
+- Action: Add enum validation
+
+**8. OrmQueryHelperPrompt**
+- Validate: `$queryGoal` is not empty
+- Validate: `$tables` (optional) contains valid table names or is empty
+- Action: Add non-empty validation for required params
+
+**9. TinkerWorkshopPrompt**
+- Validate: `$goal` ∈ ['explore', 'test', 'debug']
+- Action: Add enum validation
+
+**10. PerformanceAnalyzerPrompt**
+- Validate: `$concern` is not empty
+- Action: Add non-empty validation
+
+**11. MigrationGuidePrompt**
+- Validate: `$fromVersion` and `$toVersion` match semantic version format
+- Validate: `$area` (optional) is reasonable
+- Action: Add version format validation
+
+### Phase 3: Testing
+
+**New Test File**: `tests/TestCase/Prompts/PromptValidationTest.php`
+
+For each prompt, add tests:
+```php
+public function testValidParametersDoNotThrow(): void
+public function testInvalidParameterThrowsPromptGetException(): void
+public function testErrorMessageContainsParameterInfo(): void
+```
+
+## Error Message Format
+
+Consistent error messages:
+
+```
+Invalid value for parameter '{paramName}': '{value}'. 
+Expected one of: {allowed values}. 
+Prompt: {prompt name}
+```
+
+Example:
+```
+Invalid value for parameter 'depth': 'expert'. 
+Expected one of: basic, intermediate, advanced. 
+Prompt: documentation-expert
+```
+
+## Files to Modify
+
+1. **src/Prompts/AbstractPrompt.php** - Add validation methods
+2. **src/Prompts/DocumentationExpertPrompt.php** - Add depth validation
+3. **src/Prompts/DebugHelperPrompt.php** - Add context validation
+4. **src/Prompts/FeatureBuilderPrompt.php** - Add component validation
+5. **src/Prompts/DatabaseExplorerPrompt.php** - Add show/table validation
+6. **src/Prompts/CodeReviewerPrompt.php** - Add focus validation
+7. **src/Prompts/QualityAssurancePrompt.php** - Add context/tools validation
+8. **src/Prompts/TestingAssistantPrompt.php** - Add testType validation
+9. **src/Prompts/OrmQueryHelperPrompt.php** - Add queryGoal validation
+10. **src/Prompts/TinkerWorkshopPrompt.php** - Add goal validation
+11. **src/Prompts/PerformanceAnalyzerPrompt.php** - Add concern validation
+12. **src/Prompts/MigrationGuidePrompt.php** - Add version validation
+
+## Testing
+
+Create/update: `tests/TestCase/Prompts/PromptValidationTest.php`
+- Test each prompt's parameter validation
+- Verify correct exception is thrown
+- Verify error message format
+
+## Acceptance Criteria
+
+- [ ] All prompts validate their parameters
+- [ ] Invalid parameters throw `PromptGetException`
+- [ ] Error messages are clear and helpful
+- [ ] All tests pass
+- [ ] PHPStan level 8 compliance maintained
+- [ ] Code follows CakePHP 5.2+ standards
+- [ ] PHPUnit tests added for all validations
+
+## Timeline Estimate
+
+- Phase 1 (Infrastructure): 30 minutes
+- Phase 2 (Updates): 1-2 hours
+- Phase 3 (Testing): 1 hour
+- Total: 2.5-3.5 hours