recursive-communicator

Purpose

The recursive-communicator skill provides structured protocols for managing recursive communication loops between the validation orchestrator, validation specialists, and the main feature implementer agent. It handles failure notifications, fix requests, re-validation triggers, and loop termination to ensure validation issues are resolved systematically.

When to Use

This skill auto-activates when you:

Communicate validation failures to the main agent
Request fixes from the main agent for validation issues
Trigger re-validation after main agent fixes
Manage recursive fix loops (failure → fix → re-check → repeat)
Track iteration counts in recursive communication
Prevent deadlocks in recursive loops
Escalate unresolvable validation issues
Log communication history for traceability

Provided Capabilities

Failure Communication

Structured Failure Reports: Format validation failures for main agent
Detailed Error Information: Include file locations, line numbers, error messages
Suggested Fixes: Provide specialist recommendations for resolving issues
Priority Tagging: Mark critical vs. non-critical failures
Context Preservation: Include all relevant context for debugging

Fix Request Management

Clear Fix Requests: Explicitly request main agent to fix specific issues
Action Items: Provide actionable list of fixes needed
Deadline Awareness: Track iteration limits (max 5)
Fix Verification: Confirm when main agent completes fixes
Re-validation Triggering: Signal specialists to re-check after fixes

Re-validation Coordination

Re-check Signals: Trigger specialist re-validation after fixes
Iteration Tracking: Increment and track iteration counts
Status Updates: Communicate re-validation status to all parties
Loop Continuation: Determine if another iteration needed
Loop Termination: Identify when to exit recursive loop

Deadlock Prevention

Max Iteration Limits: Enforce maximum 5 iterations per specialist
Timeout Detection: Identify stalled communication
Escalation Triggers: Escalate after max iterations or timeout
User Intervention Requests: Flag when human input needed
Graceful Degradation: Handle unresolvable issues without blocking workflow

Communication Logging

Message History: Log all communication between agents
Iteration History: Track all iterations with timestamps
Fix History: Document all fixes attempted
Status Transitions: Log status changes (failed → fixing → re-checking → passed)
Audit Trail: Maintain complete communication audit trail

Usage Guide

Step 1: Detect Validation Failure

When a validation specialist reports failure:

Validation Failure Detected

Specialist: test-runner-specialist Phase: Test Execution Issue: 3 unit tests failing

Failure Details:

test_validation_coordinator.py::test_sequential_invocation - AssertionError
test_validation_coordinator.py::test_failure_tracking - KeyError
test_validation_coordinator.py::test_workflow_completion - AttributeError

Coverage: 73.2% (target: ≥80%)

Action Required: Activate recursive-communicator skill

Step 2: Format Failure Report

Use communication-protocol.md and message-templates.md to format structured report:

Failure Report Structure:

Validation Failure Report

Report ID: VFR-{issue-number}-{specialist-name}-{iteration} Generated: [YYYY-MM-DD HH:MM:SS] Issue: #{issue-number} - [Feature Name] Specialist: [Specialist Name] Phase: [Validation Phase] Iteration: [Current] / [Max (5)]

Failure Summary

Status: ❌ FAILED Failure Type: [Test Failures / Quality Issues / Security Vulnerabilities / E2E Failures] Severity: [Critical / High / Medium / Low] Impact: Blocks progression to [Next Phase]

Detailed Failures

Failure 1: [Test/Issue Name]

File: [File path]
Line: [Line number]
Error Type: [AssertionError / TypeError / SecurityError / etc.]
Error Message:

[Full error message from specialist]

Context: [Additional context about the failure]

Failure 2: [Test/Issue Name]

File: [File path]
Line: [Line number]
Error Type: [Error type]
Error Message:

[Full error message]

Context: [Additional context]

[... Additional failures ...]

Suggested Fixes

Fix for Failure 1

Recommendation: [Specialist's suggestion for fixing the issue] Approach: [Specific steps or code changes needed] Priority: [Critical / High / Medium / Low]

Fix for Failure 2

Recommendation: [Specialist's suggestion] Approach: [Specific steps] Priority: [Priority level]

[... Additional fix suggestions ...]

Required Actions

Main Agent (@feature-implementer-main):

Review failure details above
Implement suggested fixes (or alternative approach)
Verify fixes locally (if possible)
Signal completion to validation orchestrator
Await re-validation

Expected Timeline: [Estimated time to fix] Escalation: If fixes cannot be completed, escalate to user

Re-validation Plan

After Fix Completion:

Validation orchestrator will re-invoke [Specialist Name]
Specialist will re-run [Tests/Checks]
IF pass: Proceed to [Next Phase]
IF fail: Iteration [Current+1] / [Max (5)]
IF max iterations exceeded: Escalate to user intervention

Sent by: Validation Orchestrator (recursive-communicator skill) Awaiting: Main Agent Fix Completion

Step 3: Send Failure Report to Main Agent

Communicate failure report to @feature-implementer-main:

Communication Protocol:

Sending Failure Report

To: @feature-implementer-main From: @validation-orchestrator (via recursive-communicator) Type: Validation Failure Report Priority: [High/Medium/Low based on severity]

Message:

@feature-implementer-main: Validation failure detected during [Phase] validation.

[Full Failure Report from Step 2]

Please review and fix the above issues. Signal completion when ready for re-validation.

Status: Sent Timestamp: [YYYY-MM-DD HH:MM:SS] Awaiting Response: Yes

Step 4: Wait for Main Agent Fix

Monitor main agent activity:

Waiting State:

Awaiting Main Agent Fix

Current Status: Waiting for Fix Specialist: [Specialist Name] (paused) Iteration: [Current] / [Max (5)] Time Elapsed: [MM:SS since failure report sent] Timeout: 30 minutes (escalate if exceeded)

Main Agent Actions Expected:

Monitoring:

Check main agent status every 2 minutes
Log any main agent communications
Detect timeout if >30 minutes without response

Timeout Handling:

IF time_elapsed > 30 minutes WITHOUT main agent response:

Log timeout event
Send reminder to main agent
IF still no response after reminder (5 minutes): a. Escalate to user intervention b. Flag as "unresponsive" c. Await user decision (abort / manual fix / extend timeout)

Step 5: Receive Fix Completion Signal

When main agent signals fix completion:

Fix Completion Confirmation:

Main Agent Fix Completed

Received From: @feature-implementer-main Timestamp: [YYYY-MM-DD HH:MM:SS] Fix Duration: [MM:SS from failure report to completion]

Main Agent Report: [Summary of fixes implemented by main agent]

Fixes Applied:

Fix 1: [Description of fix]
Fix 2: [Description of fix]
[... Additional fixes ...]

Verification:

Main agent confirmed fixes applied
Files modified: [List of changed files]
Ready for re-validation

Next Action: Trigger re-validation (Step 6)

Step 6: Trigger Re-validation

Re-invoke specialist for re-check:

Re-validation Trigger:

Triggering Re-validation

Specialist: [Specialist Name] Iteration: [Current+1] / [Max (5)] Previous Status: Failed Current Status: Re-checking

Re-invocation: @[specialist-name] re-check [validation type] for feature #{issue-number} Iteration: [Current+1] / [Max (5)] Previous failures: [List of failures from previous iteration] Fixes applied: [List of fixes from main agent]

Expected Outcomes:

PASS: All previous failures resolved
- Exit recursive loop
- Proceed to next validation phase
- Log success with iteration count
FAIL (some/all failures persist):
- Increment iteration count
- Return to Step 1 (detect failure)
- IF iteration <= 5: Repeat recursive loop
- IF iteration > 5: Escalate (Step 7)

Status: Re-validation in Progress Timestamp: [YYYY-MM-DD HH:MM:SS]

Step 7: Handle Re-validation Result

Process specialist re-check output:

Result: PASS ✅

Re-validation Success

Specialist: [Specialist Name] Iteration: [Final] / [Max (5)] Status: ✅ PASSED

Previous Failures: [Count] failures Current Failures: 0 failures Resolution: All issues fixed by main agent

Iteration History:

Iteration 1: [X] failures
Iteration 2: [Y] failures
...
Iteration [Final]: 0 failures (PASS)

Total Fix Time: [HH:MM:SS across all iterations]

Action: Exit recursive loop, proceed to [Next Phase] Communication: Notify main agent of success Logging: Log successful resolution and iteration count

Result: FAIL ❌

Re-validation Failure (Iteration [Current] / 5)

Specialist: [Specialist Name] Iteration: [Current] / [Max (5)] Status: ❌ STILL FAILING

Previous Failures: [Count from previous iteration] Current Failures: [Count from current iteration] New Failures: [Count of new failures introduced] Persistent Failures: [Count still failing]

Analysis:

Failures resolved: [List]
Failures persisting: [List]
New failures introduced: [List]

Decision: IF iteration < 5: ✅ Continue recursive loop ✅ Return to Step 2 (format new failure report) ✅ Increment iteration: [Current+1] / 5 ELSE (iteration >= 5): ⛔ Max iterations exceeded ⛔ Proceed to Step 8 (escalation)

Step 8: Escalate Unresolvable Issues

When max iterations (5) exceeded or timeout occurs:

Escalation Report:

Escalation: Unresolvable Validation Issue

Escalation ID: ESC-{issue-number}-{specialist-name}-{timestamp} Generated: [YYYY-MM-DD HH:MM:SS] Issue: #{issue-number} - [Feature Name] Specialist: [Specialist Name] Phase: [Validation Phase] Escalation Reason: [Max Iterations Exceeded / Timeout / Deadlock / Other]

Escalation Summary

Status: ⛔ UNRESOLVABLE (Requires User Intervention) Total Iterations: [Max (5)] Total Time: [HH:MM:SS across all iterations] Persistent Failures: [Count]

Iteration History

Iteration	Failures	Fixes Applied	Result
1	[Count]	[Summary]	FAIL
2	[Count]	[Summary]	FAIL
3	[Count]	[Summary]	FAIL
4	[Count]	[Summary]	FAIL
5	[Count]	[Summary]	FAIL

Pattern Analysis: [Analysis of why failures persist across iterations]

Persistent Failures

[List of failures that remain unresolved after 5 iterations]

Failure 1: [Test/Issue Name]

File: [File path]
Line: [Line number]
Error: [Error message]
Iterations Failed: [1, 2, 3, 4, 5]
Fixes Attempted:
- Iteration 1: [Fix attempted]
- Iteration 2: [Fix attempted]
- ...
Why Unresolved: [Analysis of why this failure persists]

[... Additional persistent failures ...]

Recommended Actions

Option 1: User Manual Fix

User reviews failures and provides manual fix
Validation orchestrator re-runs after user fix
Risk: Requires user expertise

Option 2: Skip Validation

Mark validation as "failed but proceeding"
Document known issues
Risk: Deploy with known failures

Option 3: Abort Feature

Stop implementation
Return feature to design phase
Risk: Wasted effort on implementation

Option 4: Extend Max Iterations

Allow additional iterations (e.g., 3 more)
Continue recursive loop
Risk: Potentially infinite loop

Escalated To: User / Main Orchestrator Awaiting Decision: [Option 1 / Option 2 / Option 3 / Option 4] Validation Workflow: PAUSED

Sent by: Validation Orchestrator (recursive-communicator skill)

Step 9: Log Communication History

Maintain complete audit trail:

Communication Log Entry:

Communication Log

Entry ID: LOG-{issue-number}-{specialist-name}-{iteration}-{timestamp}

Participants:

Validation Orchestrator (@validation-orchestrator)
Specialist (@[specialist-name])
Main Agent (@feature-implementer-main)

Communication Flow:

[Timestamp 1] Specialist → Orchestrator: Validation failure detected

Failures: [Count]
Details: [Summary]

[Timestamp 2] Orchestrator → Main Agent: Failure report sent (Iteration 1/5)

Report ID: VFR-{issue-number}-{specialist-name}-1
Status: Awaiting Fix

[Timestamp 3] Main Agent → Orchestrator: Fix completion signal

Duration: [MM:SS]
Fixes: [Summary]

[Timestamp 4] Orchestrator → Specialist: Re-validation triggered (Iteration 2/5)

Status: Re-checking

[Timestamp 5] Specialist → Orchestrator: Re-validation result (PASS)

Status: ✅ All failures resolved
Final iteration: 2/5

[Timestamp 6] Orchestrator → Main Agent: Success notification

Status: Validation passed
Proceed to: [Next Phase]

Total Messages: 6 Total Iterations: 2 Total Duration: [HH:MM:SS] Outcome: Success

Best Practices

Clear Communication

Use structured message templates (from message-templates.md)
Include all relevant context (files, lines, errors)
Provide actionable fix suggestions
Specify expected outcomes clearly

Iteration Tracking

Always track current/max iterations
Log every iteration with timestamp
Document fixes attempted in each iteration
Analyze patterns across iterations

Timeout Management

Set reasonable timeouts (default: 30 minutes)
Send reminders before escalation
Log timeout events
Escalate gracefully when timeout exceeded

Deadlock Prevention

Enforce strict max iterations (5)
Detect circular failures (same failure across iterations)
Escalate when progress stalls
Provide escape routes (skip validation, user intervention)

Comprehensive Logging

Log all messages between agents
Track status transitions
Document fix attempts
Maintain audit trail for troubleshooting

Graceful Escalation

Provide context when escalating
Offer multiple resolution options
Include iteration history and analysis
Make escalation actionable for user

Resources

communication-protocol.md

Comprehensive protocol for agent-to-agent communication including:

Message formatting standards
Communication flow patterns
Status signaling conventions
Timeout and escalation procedures
Error handling protocols

message-templates.md

Pre-defined message templates for common scenarios:

Failure report template
Fix request template
Re-validation trigger template
Success notification template
Escalation report template
Communication log template

Example Usage

Input (Validation Failure)

Specialist: test-runner-specialist Status: FAILED Failures:

3 unit tests failing
Coverage: 73.2% (target: 80%)

Error Details: test_validation_coordinator.py::test_sequential_invocation - AssertionError test_validation_coordinator.py::test_failure_tracking - KeyError test_validation_coordinator.py::test_workflow_completion - AttributeError

Output (Recursive Communication Flow)

Recursive Communication: Feature #47 (Iteration 1/5)

Step 1: Failure Detection

Status: ❌ Test failures detected by test-runner-specialist Failures: 3 tests, coverage below target

Step 2: Failure Report Formatted

Report ID: VFR-47-test-runner-1 Sent To: @feature-implementer-main Content: Detailed failure report with error messages and fix suggestions

Step 3: Awaiting Fix

Status: Waiting for main agent fix Elapsed: 00:08:32 Timeout: 30 minutes

Step 4: Fix Completed

Status: Main agent fixed issues Duration: 00:08:32 Fixes: Implementation logic errors in validation_coordinator.py

Step 5: Re-validation Triggered

Status: Re-invoking test-runner-specialist (Iteration 2/5) Action: Re-run tests with fixed implementation

Step 6: Re-validation Result

Status: ❌ 1 test still failing (improvement from 3) Action: Continue to Iteration 2

[Iteration 2 begins... follows same flow]

Final Result (Iteration 3)

Status: ✅ ALL TESTS PASS, Coverage 87.3% Total Iterations: 3/5 Total Time: 00:24:15 Outcome: Exit recursive loop, proceed to Code Quality phase

Integration

This skill is used by:

validation-orchestrator agent during Phase 5: Validation
Activates automatically when validation failures occur
Works in conjunction with validation-coordinator skill for workflow management
Enables recursive communication pattern between validation specialists and main agent
Critical for resolving validation issues before deployment

Version: 2.0.0 Auto-Activation: Yes (when validation failures occur) Phase: 5 (Validation) Created: 2025-10-29