3.9 KiB

Raw Blame History

Escalation Triggers

Purpose: Conditions that require human decision and cannot be resolved autonomously.

Escalation Categories

CRITICAL Escalations

Definition: Automation CANNOT proceed - requires human decision.

Behavior:

Delete marker file: rm "{marker_file}"
Update state: set status to PAUSED in state document
Present options (stop hook won't interfere)
Wait for user input
On resume: recreate marker, set IN_PROGRESS, continue

Triggers in this category:

Code Review Loop Exceeded (#1)
Session Spawn Failure (#3)
Git Commit Failure (#4)
Unexpected Error (#5)
Dev-Story Implementation Failure (#7) when blocking + retries exhausted
Session Incomplete (#8) - session finished but workflow not verified complete (v2.2)

PREFERENCE Escalations

Definition: Automation COULD proceed either way - user chooses direction.

Behavior:

Keep marker file (automation still "active")
Present options
Act on selection immediately

Triggers in this category:

Cannot Parse Session Output (#2)
Dependency Conflict (#6)
Dev-Story Implementation Failure (#7) when NOT blocking

Escalation Protocol

When an escalation trigger is hit:

Categorize: CRITICAL or PREFERENCE
If CRITICAL: delete marker, set status to PAUSED
Notify: sound/notification
Present: situation + numbered options
Wait: halt until user responds
Log: record decision in action log
Resume: if CRITICAL, recreate marker, set IN_PROGRESS, continue

Trigger Index

Each trigger includes its escalation message template in:

data/escalation-messages-core.md (Triggers 1-4)
data/escalation-messages-extended.md (Triggers 5-7)

1. Code Review Loop Exceeded (CRITICAL)

Trigger: Code review has run 5 cycles without clean status. See: escalation-messages-core.md#1-code-review-loop-exceeded

2. Cannot Parse Session Output (PREFERENCE)

Trigger: Output doesn't match success/failure patterns. See: escalation-messages-core.md#2-cannot-parse-session-output

3. Session Spawn Failure (CRITICAL)

Trigger: T-Mux session failed to spawn after retries. See: escalation-messages-core.md#3-session-spawn-failure

4. Git Commit Failure (CRITICAL)

Trigger: Git commit failed (conflict, hook error, etc.). See: escalation-messages-core.md#4-git-commit-failure

5. Unexpected Error (CRITICAL)

Trigger: Unhandled exception or unexpected condition. See: escalation-messages-extended.md#5-unexpected-error

6. Dependency Conflict (PREFERENCE)

Trigger: Parallelism detects potential conflict. See: escalation-messages-extended.md#6-dependency-conflict

7. Dev-Story Implementation Failure (CRITICAL or PREFERENCE)

Trigger: dev-story completes with errors after retries. See: escalation-messages-extended.md#7-dev-story-implementation-failure

8. Session Incomplete (CRITICAL) [v2.2]

Trigger: story-automator monitor-session returns final_state: "incomplete" after maxCycles exhausted Condition: Session finished (idle/exited) but workflow verification failed across all retry attempts. Typical cause: Codex code-review session ended without updating sprint-status.

Why CRITICAL (not PREFERENCE):

Automated retries already exhausted
Human must decide: manual fix, use Claude, or skip story

Options:

[1] Manual Fix - Update sprint-status.yaml yourself
[2] Run with Claude - Re-run code-review with Claude agent
[3] Skip Story - Mark story as skipped and continue
Pause - Stop orchestration for investigation

Verification command:

"$scripts" orchestrator-helper verify-code-review {story_id}

Non-Escalation Conditions

Handled automatically (no escalation):

Optional step (automate) skipped by override → log and continue
Session completes with clear success → continue
Session completes with clear failure → retry once, then escalate if still fails

3.9 KiB Raw Blame History