# Escalate Issues

> Triage maintenance problems by severity, document findings with context, route to appropriate specialist agent or human, and create actionable issue reports. Use when a maintenance task encounters problems beyond automated cleanup: code that is unsafe to delete, configuration changes requiring domain expertise, breaking changes detected during cleanup, complex refactoring needed, or security-sensitive findings such as hardcoded secrets or vulnerabilities.

- Skill: `pjt222/escalate-issues-6` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pjt222/escalate-issues-6`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/escalate-issues-6/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/escalate-issues-6

---


# escalate-issues

## When Use

Use this skill when maintenance hits problems past auto cleanup:

- Not sure if code safe to delete
- Config changes need domain know-how (security, speed, arch)
- Breaking changes spotted in cleanup
- Complex refactor needed (not just cleanup)
- Security-touchy finds (hardcoded secrets, vulns)

**Do NOT use** for simple issues with clear fixes. Escalate only when auto cleanup risky or not enough.

## Inputs

| Parameter | Type | Required | Description |
|---|---|---|---|
| `issue_description` | string | Yes | Clear description of the problem |
| `severity` | enum | Yes | `critical`, `high`, `medium`, `low` |
| `context_files` | array | No | Paths to relevant files |
| `specialist` | string | No | Target agent (auto-route if not specified) |
| `blocking` | boolean | No | Whether issue blocks further cleanup (default: false) |

## Steps

### Step 1: Assess Severity

Sort issue with standard severity levels.

**CRITICAL** — Block prod work:
- Broken imports in active code
- Security vulns (exposed secrets, SQL injection)
- Data loss risk from cleanup
- Prod service outage

**HIGH** — Hit maintainability or dev speed:
- Big dead code bloat (>1000 lines)
- Broken CI/CD pipelines
- Big config drift between envs
- Unrefd modules that maybe load dynamic

**MEDIUM** — Small hygiene issues:
- Unused helper fns (<100 lines)
- Stale docs need update
- Deprecated config files (no longer used but present)
- Lint warns in non-critical paths

**LOW** — Style inconsistencies:
- Mixed indent (works but inconsistent)
- Trailing whitespace
- Inconsistent naming (camelCase vs snake_case)
- Small format differences

**Severity Decision Tree**:
```text
Does it break production? → CRITICAL
Does it block development? → HIGH
Does it impact code quality? → MEDIUM
Is it purely cosmetic? → LOW
```

**Got:** Issue sorted with clear severity label

**If fail:** Not sure? Default HIGH and escalate to human for re-triage

### Step 2: Document Finding

Grab all context for specialist review.

**Issue Report Template**:
````markdown
# Issue: [Brief Title]

**Severity**: CRITICAL | HIGH | MEDIUM | LOW
**Discovered During**: [Skill name, e.g., clean-codebase]
**Date**: YYYY-MM-DD
**Blocking**: Yes | No

## Description

Clear description of the problem in 2-3 sentences.

## Context

- **File(s)**: [List of affected files with line numbers]
- **Related**: [Related issues, commits, or previous attempts to fix]
- **Impact**: [What breaks if this isn't fixed, or what's wasted if not cleaned]

## Evidence

```language
# Code snippet or log excerpt showing the problem
```

## Attempted Fixes

- Tried X but failed because Y
- Considered Z but uncertain due to W

## Recommendation

- **Option 1**: [Safe conservative approach]
- **Option 2**: [More aggressive fix with risks]
- **Preferred**: [Which option to pursue and why]

## Specialist Routing

**Suggested Agent**: [agent-name]
**Reason**: [Why this specialist is appropriate]

## References

- [Link to related documentation]
- [Link to similar past issues]
````

**Got:** Issue logged with full context in `ESCALATION_REPORTS/issue_YYYYMMDD_HHMM.md`

**If fail:** (N/A — always log, even if incomplete)

### Step 3: Determine Routing

Match issue type to right specialist agent or human reviewer.

**Routing Table**:

| Issue Type | Specialist | Reason |
|------------|-----------|---------|
| Security vulnerability | security-analyst | Security expertise required |
| GxP compliance concern | gxp-validator | Regulatory knowledge needed |
| Architecture decision | senior-software-developer | Design pattern expertise |
| Config management | devops-engineer | Infrastructure knowledge |
| Dependency conflicts | devops-engineer | Package management expertise |
| Performance bottleneck | senior-data-scientist | Optimization knowledge |
| Code style dispute | code-reviewer | Style guide authority |
| Dead code uncertainty | r-developer (or lang-specific) | Language-specific knowledge |
| Broken test unclear | code-reviewer | Test design expertise |
| Documentation accuracy | senior-researcher | Domain knowledge required |
| License compatibility | auditor | Legal/compliance expertise |

**Automatic Routing Logic**:
```python
def route_issue(severity, issue_type):
    if severity == "CRITICAL":
        # Always escalate to human for critical issues
        return "human"

    if "security" in issue_type or "secret" in issue_type:
        return "security-analyst"

    if "gxp" in issue_type or "compliance" in issue_type:
        return "gxp-validator"

    if "architecture" in issue_type or "design" in issue_type:
        return "senior-software-developer"

    if "config" in issue_type or "deployment" in issue_type:
        return "devops-engineer"

    # Default: code-reviewer for general code issues
    return "code-reviewer"
```

**Got:** Issue routed to right specialist with reason

**If fail:** No clear specialist? Escalate to human for manual route

### Step 4: Create Actionable Issue Report

Make report matched to target (agent or human).

**For Specialist Agents** (structured format for MCP tools):
Emit one document: the routing header delimited by `---` fences, then the report
body beneath it. The receiving tool parses the header keys, so those and the
agent ids stay in English.

```yaml
type: escalation
severity: high
from_agent: janitor
to_agent: security-analyst
blocking: false
```


```text
# Security Concern: Hardcoded API Key in Config

**File**: config/production.yml:45
**Pattern**: API_KEY="sk_live_abc123..."

**Request**: Please review if this is a valid secret or a placeholder.
If valid, recommend secure credential management strategy.

**Context**: Discovered during config cleanup sweep.
```

**For Human Reviewers** (detailed markdown):
```markdown
# Escalation Report: Uncertain Dead Code Removal

**From**: Janitor Agent
**Date**: 2026-02-16
**Severity**: HIGH

## Problem

File `src/legacy_payments.js` (450 lines) appears unused but contains
complex payment processing logic. Static analysis shows zero references,
but name suggests business-critical functionality.

## Why Escalated

- Uncertain if payment code is dynamically loaded at runtime
- Potential data loss risk if deleted incorrectly
- Requires domain knowledge to assess business impact

## Evidence

- No direct imports found
- Last modified 8 months ago
- Git history shows it was part of payment refactor

## Recommendation

Request human review before deletion. If confirmed dead:
1. Archive to archive/legacy/ directory
2. Document in ARCHIVE_LOG.md
3. Create ticket to verify payment flows still work

## Next Steps

Awaiting human confirmation before proceeding with cleanup.
```

**Got:** Report formatted right for target

**If fail:** (N/A — make report in plain markdown if unsure)

### Step 5: Track Escalation Status

Keep log of all escalations to block dup reports.

```markdown
# Escalation Log

| ID | Date | Severity | Issue | Specialist | Status |
|----|------|----------|-------|-----------|--------|
| ESC-001 | 2026-02-16 | CRITICAL | Broken prod import | human | Resolved |
| ESC-002 | 2026-02-16 | HIGH | Dead payment code | human | Pending |
| ESC-003 | 2026-02-16 | MEDIUM | Config drift | devops-engineer | In Progress |
```

**Got:** `ESCALATION_LOG.md` updated with new entry

**If fail:** Log not exist? Make it

### Step 6: Notify and Block (If Required)

Issue blocks more work? Notify and pause cleanup.

**Blocking Logic**:
- CRITICAL issues always block
- HIGH issues block if on critical path
- MEDIUM/LOW issues do not block

**Notification**:
```markdown
⚠️ MAINTENANCE BLOCKED ⚠️

Issue ESC-002 (HIGH severity) requires human review before proceeding.

**Affected Operation**: clean-codebase (Step 5: Remove Dead Code)
**Reason**: Uncertain if src/legacy_payments.js is truly dead

**Action Required**: Review ESCALATION_REPORTS/ESC-002_2026-02-16.md

Once resolved, re-run maintenance from Step 5.
```

**Got:** Maintenance paused; clear notice made

**If fail:** No notice mech? Log in report

## Validation Checklist

After escalation:

- [ ] Issue severity assessed right
- [ ] Full context logged (files, evidence, tries)
- [ ] Right specialist picked
- [ ] Escalation report made in ESCALATION_REPORTS/
- [ ] ESCALATION_LOG.md updated
- [ ] Block status told if apply
- [ ] No secret info exposed in report

## Pitfalls

1. **Over-Escalating**: Escalating simple issues waste specialist time. Only escalate when truly unsure or risky.

2. **Under-Escalating**: Deleting code "just to see if tests pass" with no escalation can cause prod outage.

3. **Thin Context**: Escalating with no evidence force specialists to re-dig. Add file paths, line numbers, err msgs.

4. **Vague Descriptions**: "Something's wrong with config" not actionable. Be specific: "Config drift: dev uses API v1, prod uses v2".

5. **Not Tracking Status**: Re-escalate issue already reviewed. Check ESCALATION_LOG.md first.

6. **Exposing Secrets**: Adding real API keys or passwords in escalation reports. Redact touchy values.

## See Also

- [clean-codebase](../clean-codebase/SKILL.md) — Often fires escalations on unsure
- [tidy-project-structure](../tidy-project-structure/SKILL.md) — May find complex org issues
- [repair-broken-references](../repair-broken-references/SKILL.md) — Escalate when unclear if ref should fix or remove
- [compliance/security-scan](../../compliance/security-scan/SKILL.md) — Escalate security finds
- [general/issue-triage](../../general/issue-triage/SKILL.md) — General issue sort patterns