# annotation

> When you run `/test annotation`, you are REQUIRED to:

- Author: Nash Gao
- Repository: nashgao/mqtt-client
- Version: 20260210001543
- Stars: 3
- Forks: 1
- Last Updated: 2026-02-09
- Source: https://github.com/nashgao/mqtt-client
- Web: https://mule.run/skillshub/@@nashgao/mqtt-client~annotation:20260210001543

---

---
allowed-tools: all
description: **ANALYZE PHP annotation coverage** with comprehensive bidirectional linkage validation using parallel agents (analysis only - no test execution)
intensity: ⚡⚡⚡
pattern: 📝📝📝
---

# 📝📝📝 CRITICAL ANNOTATION ANALYSIS: COMPREHENSIVE BIDIRECTIONAL LINKAGE VALIDATION! 📝📝📝

**THIS IS NOT TEST EXECUTION - THIS IS COMPREHENSIVE ANNOTATION COVERAGE ANALYSIS!**

**🚨 NOTE: This command analyzes existing annotations - it does NOT execute tests! 🚨**

## 🚨 ZERO TOLERANCE ENFORCEMENT

**MANDATORY - ALL annotation validation must achieve PERFECT analysis:**

### Success Criteria (ALL must be met)
- ✅ **0 Failed Validations** - All annotation checks must pass
- ✅ **0 Errors** - No parsing or analysis errors allowed
- ✅ **0 Warnings** - Annotation warnings are treated as failures
- ✅ **0 Broken Links** - All annotation references must be valid
- ✅ **0 Orphaned Methods** - All methods need corresponding annotations
- ✅ **100% Bidirectional** - All @Verified must have matching @TestedBy
- ✅ **0 Syntax Errors** - Annotation syntax must be perfect

### Failure Response Protocol
When ANY issue is detected:
1. **STOP** - Do not proceed to next analysis steps
2. **REPORT** - List all annotation issues with file:line references
3. **FIX** - Resolve ALL annotation issues before continuing
4. **VERIFY** - Re-run validation to confirm 100% clean analysis

### Exit Codes
- `0` = Perfect annotation analysis (no broken links, no orphans)
- `1` = Any validation failure, broken link, or missing annotation
- `2` = Configuration or annotation system error

---

When you run `/test annotation`, you are REQUIRED to:

1. **SCAN** all source methods and test methods for @Verified and @TestedBy annotations
2. **VALIDATE** bidirectional method-to-test-case linkage at the method level
3. **VERIFY** that source methods have @Verified annotations pointing to specific test methods
4. **ENSURE** that test methods have @TestedBy annotations pointing to specific source methods
5. **FIX** annotation issues automatically with safe mode validation
6. **REPORT** comprehensive validation results with actionable recommendations
7. **USE MULTIPLE AGENTS** for parallel annotation processing with Task tool

**FORBIDDEN BEHAVIORS:**
- ❌ "Basic annotation check" → NO! Use comprehensive method-level bidirectional validation!
- ❌ "Class-level annotation validation" → NO! Must validate at method level!
- ❌ "Skip method-to-test-case mapping" → NO! Method-level linkage analysis required!
- ❌ "Ignore orphaned methods" → NO! All methods must have corresponding test annotations!
- ❌ "Single-threaded validation" → NO! Use parallel agent coordination!
- ❌ "Generic annotation output" → NO! Method-specific parsing and reporting!
- ❌ "Bash functions instead of Task tool" → NO! Use proper Task tool agents!

**MANDATORY WORKFLOW:**
```
1. PHP annotation system detection → Identify annotation-automation.php
2. IMMEDIATELY spawn 5 agents for parallel method-level validation using Task tool
3. Method discovery → Find all public methods in source classes
4. Annotation discovery → Find all @Verified and @TestedBy annotations at method level
5. Parallel validation → Run method-to-test-case linkage validation across multiple agents
6. Bidirectional linkage analysis → Validate method-level consistency
7. VERIFY results → Ensure all methods have valid test linkages and coverage complete
```

## TASK TOOL AGENT SPAWNING (MANDATORY)

I'll spawn 5 specialized agents using Task tool for comprehensive annotation analysis:

### Test Scanner Agent:
```markdown
<function_calls>
<invoke name="Task">
<parameter name="subagent_type">test-annotation-scanner</parameter>
<parameter name="description">Scan test files for @TestedBy annotations</parameter>
<parameter name="prompt">You are the Test Scanner Agent for PHP annotation analysis.

Your responsibilities:
1. Discover all PHP test files in the project (typically in test/, tests/, or Cases/ directories)
2. Scan each test file for @TestedBy annotations on test methods
3. Extract test method names and their corresponding @TestedBy target methods
4. Identify test files with missing @TestedBy annotations
5. Generate comprehensive test file inventory with annotation status

MANDATORY ANNOTATION SCANNING:
You MUST actually scan test files for annotation patterns:
- Use Glob to find all PHP test files: **/*Test.php, **/test/**/*.php, **/tests/**/*.php
- Use Grep to search for @TestedBy annotations and test methods
- Parse annotation syntax: @TestedBy(method="ClassName::methodName")
- Map test methods to their target source methods
- Report orphaned test methods (tests without @TestedBy annotations)

MANDATORY RESULT TRACKING:
- You MUST save analysis results to /tmp/test-annotation-scanner-results.json
- Include success: true/false, test_files_found, annotations_discovered, orphaned_tests
- Document all discovered test methods and their annotation status
- Report any file access failures or annotation parsing errors

CRITICAL: Comprehensive test annotation scanning is required for bidirectional validation.</parameter>
</invoke>
</function_calls>
```

### Source Annotation Analyzer:
```markdown
<function_calls>
<invoke name="Task">
<parameter name="subagent_type">source-annotation-analyzer</parameter>
<parameter name="description">Analyze source files for @Verified annotations</parameter>
<parameter name="prompt">You are the Source Annotation Analyzer for PHP source file analysis.

Your responsibilities:
1. Discover all PHP source files in the project (typically in src/, app/, or lib/ directories)
2. Scan each source file for @Verified annotations on public methods
3. Extract method signatures and their corresponding @Verified target test methods
4. Identify source methods with missing @Verified annotations
5. Validate annotation syntax and format correctness

MANDATORY SOURCE ANALYSIS:
You MUST actually analyze source files for annotation patterns:
- Use Glob to find all PHP source files: **/src/**/*.php, **/app/**/*.php, **/lib/**/*.php
- Use Grep to search for @Verified annotations and public methods
- Parse annotation syntax: @Verified(by="TestClass::testMethodName")
- Map source methods to their corresponding test methods
- Report orphaned source methods (methods without @Verified annotations)
- Validate bidirectional linkage consistency

MANDATORY RESULT TRACKING:
- You MUST save analysis results to /tmp/source-annotation-analyzer-results.json
- Include success: true/false, source_files_found, verified_methods, unverified_methods
- Document method signatures and their annotation status
- Only execute after verifying source file accessibility

CRITICAL: Complete source method annotation analysis is required for coverage metrics.</parameter>
</invoke>
</function_calls>
```

### Annotation Generator:
```markdown
<function_calls>
<invoke name="Task">
<parameter name="subagent_type">annotation-generator</parameter>
<parameter name="description">Generate missing annotations automatically</parameter>
<parameter name="prompt">You are the Annotation Generator for PHP annotation completion.

Your responsibilities:
1. Read results from Test Scanner Agent and Source Annotation Analyzer
2. Identify missing @Verified annotations on source methods
3. Identify missing @TestedBy annotations on test methods
4. Generate properly formatted annotation suggestions
5. Create annotation patches for automatic application

MANDATORY ANNOTATION GENERATION:
You MUST actually generate missing annotations:
- Load /tmp/test-annotation-scanner-results.json and /tmp/source-annotation-analyzer-results.json
- Cross-reference source methods with test methods
- Generate @Verified annotations for source methods pointing to existing test methods
- Generate @TestedBy annotations for test methods pointing to source methods
- Create diff patches for annotation additions
- Validate annotation syntax and formatting

MANDATORY RESULT TRACKING:
- You MUST save generation results to /tmp/annotation-generator-results.json
- Include success: true/false, annotations_generated, patch_files_created, syntax_validated
- Document specific annotation additions and their target methods
- Only execute after both scanner agents confirm completion

CRITICAL: Automatic annotation generation requires cross-referencing both source and test analysis.</parameter>
</invoke>
</function_calls>
```

### Bidirectional Validator:
```markdown
<function_calls>
<invoke name="Task">
<parameter name="subagent_type">bidirectional-validator</parameter>
<parameter name="description">Validate annotation consistency and linkages</parameter>
<parameter name="prompt">You are the Bidirectional Validator for PHP annotation consistency checking.

Your responsibilities:
1. Read results from all other annotation agents
2. Validate bidirectional linkage between @Verified and @TestedBy annotations
3. Check for broken links (annotations pointing to non-existent methods)
4. Identify inconsistencies between source and test annotations
5. Generate comprehensive validation report with issues and recommendations

MANDATORY BIDIRECTIONAL VALIDATION:
You MUST actually validate annotation consistency:
- Load all agent result files from /tmp/
- Cross-validate method linkages in both directions
- Check that every @Verified(by="TestClass::testMethod") has corresponding @TestedBy(method="SourceClass::sourceMethod")
- Identify orphaned annotations (pointing to non-existent methods)
- Calculate coverage metrics (percentage of methods with annotations)
- Generate actionable fix recommendations

MANDATORY RESULT TRACKING:
- You MUST save validation results to /tmp/bidirectional-validator-results.json
- Include success: true/false, linkage_validated, broken_links_found, coverage_percentage
- Document specific inconsistencies and orphaned annotations
- Only execute after all generator agents complete their work

CRITICAL: Comprehensive consistency validation ensures annotation reliability.</parameter>
</invoke>
</function_calls>
```

### Annotation Reporter:
```markdown
<function_calls>
<invoke name="Task">
<parameter name="subagent_type">annotation-reporter</parameter>
<parameter name="description">Generate comprehensive annotation coverage report</parameter>
<parameter name="prompt">You are the Annotation Reporter for PHP annotation documentation.

Your responsibilities:
1. Read results from all other annotation agents
2. Generate comprehensive annotation coverage report
3. Create method-level annotation statistics and metrics
4. Document annotation best practices and patterns found
5. Generate actionable improvement recommendations

MANDATORY ANNOTATION REPORTING:
You MUST actually generate comprehensive reports:
- Load all agent result files from /tmp/
- Compile comprehensive annotation coverage statistics
- Generate method-level coverage report with gaps identified
- Create visual representation of annotation linkages
- Document common annotation patterns and anti-patterns found
- Generate prioritized list of annotation improvements
- Create summary report with before/after metrics

MANDATORY RESULT TRACKING:
- You MUST save reporting results to /tmp/annotation-reporter-results.json
- Include success: true/false, report_generated, metrics_calculated, recommendations_provided
- Generate final comprehensive annotation coverage report
- Only execute after bidirectional validator completes validation

CRITICAL: Clear, actionable reporting provides guidance for annotation improvements.</parameter>
</invoke>
</function_calls>
```

## AGENT RESULT VERIFICATION (MANDATORY)

After spawning all 5 annotation agents, you MUST verify their results:

```bash
# MANDATORY: Verify all agents completed successfully
AGENT_RESULTS_DIR="/tmp"
AGENT_FILES=("test-annotation-scanner-results.json" "source-annotation-analyzer-results.json" "annotation-generator-results.json" "bidirectional-validator-results.json" "annotation-reporter-results.json")

for result_file in "${AGENT_FILES[@]}"; do
    FULL_PATH="$AGENT_RESULTS_DIR/$result_file"
    if [ -f "$FULL_PATH" ]; then
        # Use jq to parse agent results
        AGENT_SUCCESS=$(jq -r '.success // false' "$FULL_PATH" 2>/dev/null || echo 'false')
        if [ "$AGENT_SUCCESS" != "true" ]; then
            echo "❌ CRITICAL: Annotation analysis agent failed to complete successfully"
            echo "   Failed agent result: $result_file"
            echo "   Check agent logs for failure details"
            exit 1
        fi
    else
        echo "❌ CRITICAL: Missing annotation analysis agent result file: $result_file"
        echo "   Agent may have failed to complete or save results"
        exit 1
    fi
done

echo "✅ All annotation analysis agents completed successfully"
```

## COMPREHENSIVE ANNOTATION ANALYSIS EXECUTION (MANDATORY)

After agent coordination, you MUST execute annotation analysis validation:

```bash
# Load final annotation analysis results
if [ -f "/tmp/annotation-reporter-results.json" ]; then
    echo "📝 Generating comprehensive annotation coverage report..."

    # Extract coverage metrics from final report
    COVERAGE_PERCENTAGE=$(jq -r '.coverage_percentage // 0' "/tmp/annotation-reporter-results.json" 2>/dev/null || echo '0')
    VERIFIED_METHODS=$(jq -r '.verified_methods // 0' "/tmp/annotation-reporter-results.json" 2>/dev/null || echo '0')
    UNVERIFIED_METHODS=$(jq -r '.unverified_methods // 0' "/tmp/annotation-reporter-results.json" 2>/dev/null || echo '0')
    BROKEN_LINKS=$(jq -r '.broken_links_found // 0' "/tmp/annotation-reporter-results.json" 2>/dev/null || echo '0')

    echo "📊 Annotation Coverage Analysis Results:"
    echo "   Coverage Percentage: $COVERAGE_PERCENTAGE%"
    echo "   Methods with @Verified annotations: $VERIFIED_METHODS"
    echo "   Methods missing @Verified annotations: $UNVERIFIED_METHODS"
    echo "   Broken annotation links: $BROKEN_LINKS"

    # Validate minimum coverage requirements
    if [ "$COVERAGE_PERCENTAGE" -lt 80 ]; then
        echo "⚠️  WARNING: Annotation coverage below recommended 80% threshold"
        echo "   Consider adding @Verified/@TestedBy annotations to improve coverage"
    fi

    if [ "$BROKEN_LINKS" -gt 0 ]; then
        echo "⚠️  WARNING: Found $BROKEN_LINKS broken annotation links"
        echo "   Review and fix annotations pointing to non-existent methods"
    fi

    echo "✅ Annotation analysis completed successfully"
else
    echo "❌ CRITICAL: Final annotation report not found"
    echo "   Annotation analysis may have failed to complete"
    exit 1
fi
```

🛑 **MANDATORY ANNOTATION VALIDATION PROTOCOL** 🛑
1. **SPAWN ALL 5 AGENTS IMMEDIATELY** using Task tool for parallel processing
2. **VERIFY AGENT RESULTS** using the mandatory verification script
3. **EXECUTE ANNOTATION ANALYSIS** to generate coverage metrics and reports
4. **VALIDATE COVERAGE** against minimum thresholds and quality standards

Execute comprehensive annotation validation with ZERO tolerance for incomplete linkage analysis.

**FORBIDDEN SHORTCUT PATTERNS:**
- "Basic annotation scan is sufficient" → NO, comprehensive validation required
- "Skip slow validation for speed" → NO, all annotations must be validated
- "Linkage reports are optional" → NO, mandatory linkage analysis
- "Manual annotation analysis is fine" → NO, automated analysis required
- "Single agent validation is faster" → NO, parallel validation mandatory
- "Bash functions instead of Task tool" → NO, use proper Task tool agents

You are validating annotations for: $ARGUMENTS

Let me ultrathink about comprehensive annotation validation with parallel agent coordination.

🚨 **REMEMBER: Annotations are the foundation of test-source linkage reliability!** 🚨

**YOU ARE NOT DONE UNTIL:**
- ✅ All 5 agents have been spawned using Task tool and completed their analysis
- ✅ All public methods discovered and scanned for annotations
- ✅ Method-level bidirectional linkage analyzed with gap identification
- ✅ All source methods have @Verified annotations pointing to specific test methods
- ✅ All test methods have @TestedBy annotations pointing to specific source methods
- ✅ Orphaned methods identified and reported
- ✅ Invalid method-to-test-case mappings analyzed with root cause identification
- ✅ Method-level coverage metrics collected and reported
- ✅ Actionable recommendations provided for method annotation improvements

**Method-Level Annotation Patterns:**

**Source Method Annotation Example:**
```php
class UserService {
    /**
     * @Verified(by="UserServiceTest::testCreateUser")
     * @param array $userData
     * @return User
     */
    public function createUser(array $userData): User {
        // Implementation
    }
}
```

**Test Method Annotation Example:**
```php
class UserServiceTest extends TestCase {
    /**
     * @TestedBy(method="UserService::createUser")
     * @covers UserService::createUser
     */
    public function testCreateUser(): void {
        // Test implementation
    }
}
```

**Anti-Patterns to Avoid:**
- ❌ Running validation without method-level bidirectional linkage analysis (incomplete validation)
- ❌ Validating at class level instead of method level (insufficient granularity)
- ❌ Ignoring orphaned methods without corresponding test annotations (quality compromise)
- ❌ Single-threaded validation without parallelization (performance issue)
- ❌ Generic validation without method-specific PHP optimization (suboptimal)
- ❌ Skipping method-level coverage analysis or quality metrics (missed insights)
- ❌ No automated method annotation fixing or actionable recommendations (missed improvements)
- ❌ Using bash functions instead of Task tool agents (not real parallelism)

**Final Verification:**
Before completing method-level annotation validation:
- Have I spawned all 5 agents using Task tool for true parallel processing?
- Have I discovered and scanned all public source methods for @Verified annotations?
- Have I discovered and scanned all test methods for @TestedBy annotations?
- Are method-to-test-case linkage reports generated with gap analysis?
- Have I identified and reported all orphaned methods without corresponding annotations?
- Are method-level fix recommendations provided with safe mode options?
- Do I have comprehensive monitoring setup for continuous method-level validation?

**Final Commitment:**
- **I will**: Use Task tool for all 5 agent spawning operations with proper parallel execution
- **I will**: Validate all method-level annotations with comprehensive bidirectional linkage analysis
- **I will**: Discover and scan all public source methods for @Verified annotations
- **I will**: Discover and scan all test methods for @TestedBy annotations
- **I will**: Use parallel agents for optimal method-level validation performance
- **I will**: Provide detailed method-to-test-case gap analysis and actionable recommendations
- **I will**: Validate method annotation quality and suggest improvements
- **I will**: Generate comprehensive method-level reports with monitoring capabilities
- **I will NOT**: Skip method-level linkage analysis or quality validation
- **I will NOT**: Ignore orphaned methods or broken method-to-test-case linkages
- **I will NOT**: Use single-threaded validation without parallelization
- **I will NOT**: Use bash functions instead of proper Task tool agents
- **I will NOT**: Provide generic reports without method-specific actionable insights

**REMEMBER:**
This is METHOD-LEVEL ANNOTATION VALIDATION mode - comprehensive method-level annotation analysis with bidirectional linkage validation, quality metrics, and automated fixing using 5 parallel Task tool agents. The goal is to ensure every source method has a corresponding @Verified annotation pointing to a specific test method, and every test method has a corresponding @TestedBy annotation pointing to a specific source method.

Executing comprehensive annotation validation protocol with parallel agent coordination...