From cappy-toolkit
Escalation advisor for CAPPY investigations — defines escalation paths when investigation hits constraints, blocked gates, or requires Engineering involvement.
npx claudepluginhub thelightarchitect/cappy-toolkit --plugin cappy-toolkitThis skill uses the workspace's default tool permissions.
<!-- Copyright (C) 2025-2026 Kevin Francis Tan (github.com/theLightArchitect) | SPDX-License-Identifier: AGPL-3.0-or-later -->
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Version: 1.0.0 Purpose: Define escalation paths when investigation hits constraints Agent: CAPPY (singleton agent) (escalation responsibility) Created: 2026-02-05 P-006 Component: Praetorian Deterministic Architecture
When to Trigger: After every MCP tool execution to monitor token budget
Hook Specification:
ContextGatingHook::trigger(
tokens_used: usize, // Tokens consumed by current tool execution
tokens_remaining: usize, // Tokens left (8000 - used)
tokens_budget: usize, // Hard budget (6000 tokens, 75% of 8000)
token_budget_exhausted: bool, // Has usage >= 85% of total (6800)?
current_phase: usize, // Phase number (0-7)
investigation_id: String, // Case ID for logging
escalation_level: u8 // 0=normal, 1=warning, 2=critical
)
Hook Behavior:
Escalation Trigger Logic:
If tokens_remaining < budget_remaining_for_remaining_phases:
→ Cannot complete all phases with current context
→ Trigger escalation workflow
→ CAPPY (singleton agent) invokes /escalation skill
→ Present 3 recovery options to Claude
Agent Implementation (in CAPPY (singleton agent)):
Why This Hook: P-006 hard constraint. Prevents running out of context mid-investigation. Forces conscious decision (continue vs deliver now) when budget gets tight.
The /escalation skill defines recovery strategies when investigation:
This skill serves as the decision tree for CAPPY (singleton agent) when escalation is needed.
Trigger: ContextGatingHook budget >= 85%
Problem:
Recovery Options (in priority order):
Trigger: Phase gate blocks phase advancement 2+ times
Problem:
Recovery Options:
Trigger: Same phase attempted 3+ times without progression
Problem:
Recovery Options:
def get_escalation_options(trigger_type: str, context: Dict) -> List[Dict]:
"""
Returns prioritized recovery options for escalation type.
Args:
trigger_type: "CONTEXT_BUDGET", "GATE_BLOCKED", "DEADLOCK"
context: {
tokens_used: int,
tokens_budget: int,
tokens_remaining: int,
can_continue: bool,
phases_completed: List[str],
confidence: float (0-100),
attempts: int
}
Returns:
[{
priority: int (1-5, lower = higher priority),
option: str (name of recovery option),
impact: str (what happens if chosen),
effort: str (time/effort required),
success_rate: str ("High", "Medium", "Low"),
when_to_choose: str (decision criteria)
}]
"""
pass
def get_escalation_contact() -> Dict:
"""
Returns who to contact for escalation.
Returns:
{
name: "Kevin Tan",
slack_handle: "kevtan",
email: "contact via github.com/theLightArchitect",
timezone: "PST",
typical_availability: "Pacific business hours"
}
"""
pass
def should_auto_recover(trigger_type: str) -> bool:
"""
Returns if escalation type can auto-recover without human decision.
Args:
trigger_type: "CONTEXT_BUDGET", "GATE_BLOCKED", "DEADLOCK"
Returns:
True if auto-recovery possible, False if human decision required
"""
pass
def log_escalation_attempt(
investigation_id: str,
trigger_type: str,
severity: str,
recommendation: str,
status: str = "AWAITING_DECISION"
) -> None:
"""
Logs escalation attempt to inv_context.json escalation_attempts section.
Args:
investigation_id: e.g., "SF-03896040"
trigger_type: "CONTEXT_BUDGET", "GATE_BLOCKED", "DEADLOCK"
severity: "WARNING", "CRITICAL", "BLOCKED", "EMERGENCY"
recommendation: The recommended recovery option
status: One of "AWAITING_DECISION", "APPROVED", "DENIED", "AUTO_RECOVERED"
"""
pass
Receive Escalation Trigger
{severity: CRITICAL, budget_percentage: 87%}{blocked: true, reason: "confidence < 70%"}Load Escalation Skill
escalation_skill = load_skill("/escalation")Analyze Situation
Get Recovery Options
options = escalation_skill.get_escalation_options(trigger, context)Recommend to Claude
{
"status": "ESCALATION_NEEDED",
"trigger": "CONTEXT_BUDGET_EXCEEDED",
"severity": "CRITICAL",
"analysis": {
"phases_complete": ["Phase 2", "Phase 3", "Phase 4"],
"phases_remaining": ["Phase 5", "Phase 6", "Phase 7"],
"tokens_used": 75500,
"tokens_remaining": 9500,
"estimated_tokens_needed": 15000,
"can_finish": false
},
"options": [
{
"priority": 1,
"option": "Get Kevin approval to extend context",
"impact": "Investigation continues with fresh budget",
"time_needed": "5-10 min",
"success_rate": "High"
},
{
"priority": 2,
"option": "Summarize findings and deliver now",
"impact": "Faster delivery, may miss deeper root cause",
"time_needed": "30 min",
"success_rate": "Always succeeds"
}
],
"recommendation": "ESCALATE to Kevin - 5 min vs 30 min delivery",
"message": "Context budget 87% of limit. Recommend Kevin approval to continue Phase 5 validation."
}
Wait for Claude/Kevin Decision
Execute Recovery
Each escalation attempt is logged:
{
"investigation_id": "SF-03896040",
"escalation_attempts": [
{
"timestamp": "2026-02-05T14:32:15Z",
"phase": 5,
"trigger": "CONTEXT_BUDGET_EXCEEDED",
"severity": "CRITICAL",
"tokens_used": 75500,
"tokens_budget": 85000,
"budget_percentage": 88.8,
"recommendation": "Get Kevin approval to extend context",
"status": "AWAITING_DECISION"
},
{
"timestamp": "2026-02-05T14:45:20Z",
"phase": 5,
"trigger": "CONTEXT_BUDGET_EXCEEDED",
"severity": "CRITICAL",
"tokens_used": 75500,
"tokens_budget": 85000,
"budget_percentage": 88.8,
"recommendation": "Get Kevin approval to extend context",
"status": "APPROVED"
}
]
}
Escalation handling is working when:
/investigate - Main investigation skill (Phases 1-7)/gate - Phase gate enforcement"Escalation is not failure - it's the mark of wise engineering that recognizes human judgment matters."
Created: 2026-02-05
Last Updated: 2026-02-05
Version: 1.0.0