Skip to content

notque/vexjoy-agent / skills/meta/do

Classify user requests and route to the correct skill, pipeline, and stack. Primary entry point for all delegated work.

references/progressive-depth.md

View on GitHub
# Progressive Depth Routing

Start every task at the shallowest viable depth. Escalate only when evidence demands it. A 2-line fix stays a 2-line fix. A task that reveals hidden complexity gets escalated to full skill methodology.

The router's initial complexity classification is a *starting point*, not a commitment. Uncertainty about depth is normal — the correct response is to start shallow and let the work surface the real complexity, not to guess high "just to be safe."

---

## Depth Levels

### Level 0: Inline

Router handles directly. No agent dispatched.

**When**: The user named an exact file path to read, or asked a question answerable from conversation context.

**Examples**: "Read `scripts/pre-route.py`", "What branch am I on?", "Show me the last commit."

### Level 1: Quick Trivial

Use `quick --trivial` for tasks that appear to be 1-3 file edits.

**When**: The change looks self-contained — a bug fix, a config tweak, adding a small block of code. The agent attempts the fix and watches for escalation signals.

**Examples**: "Fix the typo in docs/router-ab-runbook.md", "Add a --verbose flag to pre-route.py", "Update the version number in SKILL.md."

**Escalation signals** (any one triggers escalation):
- More than 3 files need changes
- Test failures reveal deeper issues than the original fix
- Architectural questions arise (e.g., "should this be a new module?")
- The fix has side effects in other modules
- The agent is uncertain about the correct approach

### Level 2: Methodical

Dispatch agent with domain-appropriate skill (full phase-gated workflow).

**When**: Level 1 escalated, or the router classifies the task as Medium complexity. The task requires understanding multiple files, running tests, or following a multi-step methodology.

**Examples**: "Refactor the routing system to support plugin skills", "Add webhook support to the notification service", "Debug why CI fails on the go-patterns tests."

### Level 3: Pipeline

Multi-agent pipeline with planning, execution, and review.

**When**: Level 2 escalated due to cross-cutting concerns, or the router classifies as Complex. The task spans multiple domains, requires coordination between agents, or involves architectural decisions.

**Examples**: "Implement a new feature lifecycle for the toolkit", "Migrate the entire test suite from Jest to Vitest", "Add multi-repo support to the routing system."

---

## Escalation Signal Format

When an agent at any level determines it needs escalation, it must emit a structured signal — not silently produce degraded output:

```
[ESCALATION-NEEDED]
Current level: 1 (Fast)
Reason: Found 7 files need changes, original estimate was 2
Recommended level: 2 (Methodical)
Work completed so far: Fixed the primary file (docs/router-ab-runbook.md), discovered 6 other references that need matching updates
```

The router receives this signal and re-dispatches at the recommended level. The block becomes the `prior_results` field of the new Task Spec. The router copies these fields into it: current level, reason, work completed so far, and files touched.

---

## User Escape Hatch

Users can override depth at any time during routing or execution:

| User says | Effect |
|-----------|--------|
| "go deeper" / "use full workflow" | Escalate to Level 2 (Methodical) |
| "keep it simple" / "just fix it" | Stay at current level, skip enhancements |
| "full pipeline" | Escalate to Level 3 (Pipeline) |
| "start over deeper" | Abandon current work, restart at specified level |

The escape hatch exists because the user has context the router lacks. An override is a routing signal: the routing hooks record the dispatch and score its outcome on the next turn, so the corrected depth shows up in `learning-db.py route-health` without any extra step.

---

## Mapping to Router Classification

Progressive depth modifies how classification maps to execution, not the classification itself:

| Router classification | Default depth | Progressive depth |
|-----------------------|---------------|-------------------|
| Trivial | Inline | Level 0: Inline (same) |
| Simple | Agent + skill | Level 1: Quick Trivial (start shallow, escalate if needed) |
| Medium | Agent + skill | Level 2: Methodical (or Level 1 if task looks simpler than Medium) |
| Complex | Pipeline | Level 3: Pipeline (or Level 2 if task looks simpler than Complex) |

The key change: **Simple and Medium tasks start at Level 1 when the scope is ambiguous.** If the agent can finish at Level 1, it does — saving the overhead of full skill methodology. If it cannot, the escalation signal triggers Level 2 with no work lost.

---

## Patterns to Detect and Fix

| Failure Mode | Why it fails | Correct behavior |
|--------------|-------------|------------------|
| Starting at Level 2 "just to be safe" | Defeats the purpose; burns tokens on methodology the task doesn't need | Start at Level 1, let evidence drive escalation |
| Escalating without evidence | Phantom complexity; the agent imagines problems that don't exist | Must cite a concrete escalation signal |
| Silent degradation | Shallow agent produces wrong output instead of escalating | Agent must emit `[ESCALATION-NEEDED]` when hitting limits |
| Ignoring user override | User said "go deeper" but agent continues at current level | User overrides are immediate and unconditional |
| Re-doing completed work after escalation | Level 2 agent restarts from scratch instead of building on Level 1 output | Escalation signal includes "work completed so far" — Level 2 continues from there |
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall