Efficient completion marker generation to prevent timeouts and improve task completion reliability. Use when marking tasks complete to ensure atomic completion marker output. Prevents timeout issues and reduces completion time by 10-15 seconds.
Efficient completion marker generation to prevent timeouts and improve task completion reliability. Use when marking tasks complete to ensure atomic completion marker output. Prevents timeout issues and reduces completion time by 10-15 seconds.
Completion Marker Optimization
Efficient completion marker generation to prevent timeouts and improve task completion reliability. Eliminates timeout issues and reduces completion time by 10-15 seconds.
⚠️ CRITICAL PROTOCOL - READ FIRST ⚠️
THE COMPLETION MARKER MUST BE OUTPUT AS A SINGLE, ATOMIC STRING. STREAMING CHARACTER-BY-CHARACTER VIOLATES THE PROTOCOL AND CAUSES DETECTION FAILURES.
Protocol Violation Rate: 100% of analyzed tasks show streaming violations despite explicit instructions.
Impact:
Orchestrator may fail to detect completion
Potential parsing issues
Token waste (23 tokens → 1 token for marker)
Timeout issues (15+ seconds)
CRITICAL RULES:
Buffer the entire marker before outputting
Never stream it character-by-character
Output the complete string in a single response
The orchestrator expects atomic output - streaming may cause detection failures
Output <ralph>COMPLETE</ralph> exactly once. Do not repeat it. Duplicate output is invalid.
Place the marker early in your final response (e.g. immediately after the verification summary) so that if the response is truncated, completion is still detected.
Common mistake: Do not output the marker twice. Invalid example: <ralph>COMPLETE</ralph><ralph>COMPLETE</ralph>.
Overview
Problem: Character-by-character streaming causes timeouts (15+ seconds) and protocol violations
Solution: Atomic completion marker output as single string
Impact: Eliminate timeout issues, reduce completion time by 10-15 seconds, ensure 100% protocol compliance
Output Format
Visual Examples: Correct vs Incorrect
✅ CORRECT: Atomic Output (Single Token)
The marker is output as one complete string in a single response:
## Task Complete
All functionality has been implemented and verified.
<ralph>COMPLETE</ralph>
Token Breakdown (Correct):
Single token: <ralph>COMPLETE</ralph>
Output in one response
Orchestrator detects immediately
❌ INCORRECT: Streaming (Multiple Tokens)
The marker is streamed character-by-character across multiple tokens:
<
ral
ph
>COMPLETE</ralph>
Token Breakdown (Incorrect):
Token 1: <
Token 2: ral
Token 3: ph
Token 4: >COMPLETE</ralph>
Result: Orchestrator may not detect completion, parsing issues occur
Why This Fails:
Orchestrator expects complete marker in single token
# ✅ CORRECT: Completion before cleanup<ralph>COMPLETE</ralph># Cleanup operations (if needed)
❌ WRONG: Cleanup before completion
# WRONG: Cleanup before completion marker# Cleanup operations<ralph>COMPLETE</ralph>
Validation Before Completion
Pre-Completion Validation Checklist
CRITICAL: Complete ALL items before outputting marker. This checklist prevents protocol violations.
Task Completion Verification:
All success criteria met
Functional testing completed
TypeScript compilation passed (if applicable)
Browser testing completed (if applicable)
No console errors
Progress.txt updated (if applicable)
Marker Output Validation:
All operations are complete (no pending tool calls)
Marker string is ready: <ralph>COMPLETE</ralph>
Marker will be output as single atomic string (not streamed)
Marker will be included in assistant response text (not shell command)
No intermediate text will appear between marker components
Complete marker is buffered and ready for atomic output
Orchestrator Compatibility Check:
Marker is complete string (not partial)
No streaming will occur (verified in validation step)
Marker format is correct: <ralph>COMPLETE</ralph>
Marker will be at end of response after all verification
Only after ALL items above are checked, proceed to output the marker.
Verification Pattern
## Final Verification1.**TypeScript Compilation**: ✅ Passes
```bash
npx tsc --noEmit
# No errors
Browser Testing: ✅ Completed
All test cases pass
No console errors
Success Criteria: ✅ All met
Criterion 1: ✅
Criterion 2: ✅
Criterion 3: ✅
Progress Tracking: ✅ Updated
progress.txt reflects completion
COMPLETE
## Orchestrator Detection Patterns
### How Orchestrator Detects Completion
The orchestrator scans assistant responses for the completion marker pattern. It expects:
1. **Complete marker in single token**: `<ralph>COMPLETE</ralph>` as one token
2. **In assistant response text**: Not in shell output or tool responses
3. **At end of response**: After all verification and documentation
4. **Atomic output**: No streaming, no partial tokens
### Detection Failure Modes
**Why streaming causes detection failures**:
1. **Token-by-token scanning**: Orchestrator may miss partial tokens
2. **Timing issues**: Incomplete marker may be processed before completion
3. **Parsing errors**: Partial tokens may not match detection pattern
4. **State confusion**: Multiple tokens may confuse detection logic
**Example of detection failure**:
Token 1: "<" → Not recognized as marker
Token 2: "ral" → Not recognized as marker
Token 3: "ph" → Not recognized as marker
Token 4: ">COMPLETE" → Pattern incomplete, detection fails
Before outputting marker:
1. Verify no pending tool calls
2. All tool calls have completed
3. No async operations in progress
4. All verification steps finished
5. Then output marker atomically
# ❌ WRONG: Streaming<ralph>COMPLETE</ralph># Each character streamed separately# ✅ CORRECT: Atomic<ralph>COMPLETE</ralph># Single string output
CRITICAL ENFORCEMENT: The completion marker <ralph>COMPLETE</ralph> MUST be output as a SINGLE, ATOMIC STRING in ONE response. Do NOT stream it character-by-character. The orchestrator expects the complete marker in a single token output.
Pitfall 2: Echo Commands
Problem: Using shell echo commands for completion marker
Solution: Include in assistant response text
# ❌ WRONG: Shell commandecho"<ralph>COMPLETE</ralph>"# ✅ CORRECT: In response
<ralph>COMPLETE</ralph>
Pitfall 3: Delayed Completion
Problem: Delaying completion for cleanup operations
Solution: Output completion before cleanup
# ❌ WRONG: Cleanup before completion# Cleanup operations<ralph>COMPLETE</ralph># ✅ CORRECT: Completion before cleanup<ralph>COMPLETE</ralph># Cleanup operations (if needed)
Troubleshooting: When Streaming Cannot Be Prevented
System-Level Workarounds
If streaming occurs despite following all guidelines:
