Task Path Optimization

Task Path Optimization

Concept of the skill

Task path optimization is route planning before execution: classify the task shape, choose the lightest sufficient approach, sequence dependencies, isolate exploration when context would get polluted, and switch strategy after repeated failure instead of pushing harder on a bad path.

Concept Card

What it is: Task path optimization is the pre-execution discipline of choosing how to work before starting the work. It classifies task shape, risk, uncertainty, dependency structure, context cost, and review needs so the agent picks a direct edit, lightweight plan, exploration pass, parallel split, orchestrator-worker flow, evaluator-optimizer loop, or fresh-context recovery.

Mental model: Treat the task as a route-planning problem. The primitives are scope clarity, file certainty, dependency graph, risk/reversibility, context budget, parallelism, and failure history. The route is only optimal if its overhead is proportional to the work.

Why it exists: Agents waste time in two opposite ways: coding immediately when they do not understand the surface, or creating elaborate plans for one-line work. Naming the path decision prevents both failure modes and makes escalation deliberate.

What it is NOT: It is not task execution, debugging, tool-call optimization, Linear task lifecycle management, or architecture decision recording. It chooses the work path; adjacent skills perform the work, investigate failures, manage tasks, or document durable decisions.

Adjacent concepts: task-lifecycle shapes work into tasks, task-execution executes a chosen plan, codebase-search handles exploration mechanics, tool-call-strategy optimizes individual calls, and diagnosis/troubleshooting handle observed failures.

One-line analogy: Task path optimization is choosing whether you need no map, a route preview, a scout, a convoy, or a fresh start before the trip begins.

Common misconception: More planning is not automatically safer. The best path is the smallest sufficient path that still handles the task's actual uncertainty and risk.

Domain Context

What is this skill? This skill provides decision frameworks for choosing the optimal execution path before starting work: plan-vs-act gates, agent architecture selection (chaining, routing, parallelization, orchestrator-worker, evaluator-optimizer), scope management heuristics, critical-path analysis across task networks, and context budget awareness. Use when deciding how to approach a task (plan first vs act immediately), decomposing complex work into parallelizable subtasks, choosing between subagent patterns, or when a task has failed twice and needs a fresh approach. Do NOT use for executing the chosen plan (use task-execution), debugging failures (use troubleshooting or diagnosis), or tool-level efficiency (use tool-call-strategy).

Key Files

Coverage

Decision frameworks for choosing the optimal execution path: complexity-first triage, plan-vs-act gates, five agent architecture patterns (prompt chaining, routing, parallelization, orchestrator-worker, evaluator-optimizer), scope management heuristics, critical-path analysis, context budget awareness, recovery from failed approaches, and the Writer/Reviewer pattern for high-risk quality assurance.

Philosophy of the skill

The shortest path between a problem statement and a working solution is rarely a straight line, but it is always a deliberate choice. Agents default to "start coding immediately" or "plan everything exhaustively" — both waste time depending on context. This skill exists because the decision of how to approach a task is separate from the act of executing it, and getting the approach wrong costs more than the approach selection itself. A 30-second triage that correctly identifies "act immediately" saves 10 minutes of unnecessary planning. A 2-minute plan on a complex task prevents 30 minutes of wrong-direction implementation. The key insight: match the weight of your approach to the weight of the problem.

Authority: Owns the pre-execution decision: what approach to use, how to decompose work, when to parallelize, when to start over. Defers to task-execution for executing the chosen plan and tool-call-strategy for individual tool call efficiency.

1. Complexity-First Triage

Before touching any code, assess task complexity to determine approach weight.

Rule: If you could describe the diff in one sentence, skip the plan. If you can't name the files you'll change, you're not ready to plan — you need to explore first. The concrete exploration paths are: task-researcher (key-files + RIPER sections), codebase-search (Glob/Grep/Read decision tree), and the RIPER mode escalation path (Read → Identify → Plan → Execute → Review) documented in task-researcher. Use task-researcher as the subagent when exploration should happen in an isolated context.

2. The Plan-vs-Act Decision Gate

Is the task scope clear and the fix small?
  YES --> Act immediately (commit to execution path)
  NO  --> Is the execution path predictable (known files, known pattern)?
            YES --> Lightweight plan (list files + changes, then execute)
            NO  --> Is it exploratory or research-oriented?
                      YES --> Explore-Plan-Execute (3-phase, use RIPER)
                      NO  --> Orchestrator-Worker (dynamic decomposition with subagents)

Decision signals

3. Five Agent Architecture Patterns

Choose the right pattern for the task shape. Anthropic's "Building effective agents" recommends starting with simple composable patterns and adding complexity only when it improves outcomes.

Foundational principle: Start with the simplest pattern that could work. Only increase complexity when the simpler pattern demonstrably fails.

How to read the status column

• Live infra means the pattern exists as a concrete script, command, or runtime surface in this repo today.
• Conceptual framing means the pattern is useful for thinking about execution shape, but it is not exposed as a named shared runtime primitive.
• Mixed means part of the pattern is implemented in a specific workflow, while the generalized pattern is still guidance rather than reusable infrastructure.

Pattern selection flowchart

Are all steps known in advance?
  YES --> Are they independent?
            YES --> Parallelization
            NO  --> Prompt Chaining
  NO  --> Does the task have distinct categories?
            YES --> Routing
            NO  --> Can quality be measured and iterated?
                      YES --> Evaluator-Optimizer
                      NO  --> Orchestrator-Worker

4. Scope Management Heuristics

Scope creep is the primary cause of task failure in agent workflows. These rules prevent it.

Before starting

1. Name the deliverable. One sentence: "When this is done, [X] will work."
2. List the files. If you can't name the files, you need exploration, not execution. Use task-researcher (subagent) or codebase-search (direct Glob/Grep/Read) to explore; RIPER mode (task-researcher key-files → overview) is the structured escalation path.
3. Set the boundary. "I will NOT touch [Y] even if I see issues."
4. Define success evidence. A command, test, or screenshot that proves completion.

During execution

5. One task per context. Never mix unrelated work in the same session.
6. Adjacent issues go to Linear. If you find a bug while fixing another bug, file it — don't fix it now unless it blocks you.
7. Two-failure rule. After two failed corrections on the same approach, stop. The approach is wrong, not the details. Clear context, rethink strategy.
8. Context pollution compounds. Each failed attempt adds noise. After the two-failure threshold, /clear and restart with lessons learned baked into the initial prompt.

After completion

9. Verify against the original deliverable. Not "does the code work" but "does it satisfy the one-sentence deliverable from step 1."
10. Capture the path. If the optimal path was non-obvious, document it for future agents.

5. Critical Path Analysis

When a task decomposes into subtasks, identify the critical path — the longest chain of dependent subtasks that determines total completion time.

Dependency classification

Parallelization decision

For each pair of subtasks:
  Do they share any files?
    YES --> Sequential (or use worktree isolation)
    NO  --> Do they share state (DB, env, running server)?
              YES --> Sequential
              NO  --> Parallel (use subagents)

Optimal ordering rules

1. Start with the riskiest subtask. If it fails, you learn early before investing in dependent work.
2. Parallelize verification. Typecheck, lint, and test can almost always run in parallel.
3. Front-load exploration. Read and understand before writing — reduces wrong-direction time.
4. Batch similar changes. Five similar file edits are faster as one scripted batch than five individual tool calls.

6. Context Budget Awareness

Context is a finite resource. Every file read, every command output, every tool call result consumes it. Performance degrades as context fills.

Context-efficient patterns

Context-expensive anti-patterns

7. Recovery: When the Current Approach Fails

Not every approach works. Recognizing failure early and switching cleanly is a skill.

Failure signals

• Same error after two different fix attempts
• Fix introduces new failures in unrelated areas
• Realization that the mental model of the system was wrong
• Context is polluted with multiple failed approaches

Recovery protocol

1. Stop. Do not make a third attempt on the same approach.
2. Commit or stash any partial progress worth keeping.
3. Clear context (/clear or spawn a fresh subagent).
4. Write a one-paragraph brief that includes: what was tried, why it failed, what the new hypothesis is.
5. Start the new approach from the brief, not from memory of the failed attempt.

The Writer/Reviewer pattern

For high-stakes tasks, use two separate contexts:

• Writer context: Implements the solution
• Reviewer context: Reviews with fresh eyes (no implementation bias)

This pattern catches errors that the writer's context has normalized. Use it for security changes, architectural decisions, and any task where correctness matters more than speed.

8. The METR Finding

External research from METR (2025) reported that experienced open-source developers in its randomized controlled trial took 19% longer with early-2025 AI tools, despite expecting a 24% speedup. Treat that result as a caution about hidden coordination, review, and quality-standard overhead — not as a measured truth about this repo's own agent system, and not as a universal claim that AI tools slow all developers.

For repo-specific overhead, check local measurement surfaces instead of borrowing the METR number as if it were native telemetry:

• scripts/analytics/session-scorecard.js and the generated session score artifacts
• scripts/model/usage-collector.js and USAGE.md
• task-level runtime evidence such as verification receipts, wrap summaries, and per-command loop outcomes

Implication for this skill: The optimal path is NOT "let the agent do everything." It is knowing:

• When to let the agent work autonomously (clear scope, known pattern)
• When to decompose into smaller agent-sized chunks (complex but parallelizable)
• When to take over manually (agent is looping, context is polluted)
• When to use the agent as a reviewer rather than an implementer

9. Source Notes

Verification

After applying this skill, verify:

• I assessed task complexity before choosing an approach
• I can name the specific files I will change
• I defined the deliverable in one sentence
• I chose the simplest agent pattern that fits the task shape
• I identified parallelizable subtasks and ran them concurrently where possible
• I did not mix unrelated work in the same context
• If an approach failed twice, I cleared context and started fresh

Do NOT Use When

Version 1.0.0 — 2026-04-02. Based on Anthropic's "Building Effective Agents" research, METR efficiency findings, and repo-specific execution patterns.

Skill Graph context

Classification

• Subject: software-engineering-method
• Public: true
• Scope: Choosing the optimal execution path before starting work — plan-vs-act gates, agent-architecture selection (chaining, routing, parallelization, orchestrator-worker, evaluator-optimizer), scope-management heuristics, critical-path analysis across task networks, and context-budget awareness, including the fresh-approach reset when a task has failed twice. Portable across any agentic execution; principle-grounded, not repo-bound. Excludes executing the chosen plan (task-execution), debugging failures (troubleshooting, diagnosis), and tool-level efficiency (tool-call-strategy).

When to use

• this task has failed twice, I need a fresh approach not another retry on the same path
• what is the shortest path to a solution here, plan vs act for this task
• assess this task's complexity and pick the lightest sufficient approach before I start
• is this work simple enough to just act, or should I plan the execution path first
• Triggers: task-path-optimization, execution-strategy, approach-selection

Not for

• reduce the number of tool calls in this read-heavy step
• troubleshoot why the deployment keeps timing out
• execute the implementation plan we already agreed on

Related skills

• Verify with: code-review
• Related: prioritization, context-engineering, tool-call-strategy, test-driven-development

Concept

• Mental model: Task path optimization is route planning before execution: classify the task shape, choose the lightest sufficient approach, sequence dependencies, isolate exploration when context would get polluted, and switch strategy after repeated failure instead of pushing harder on a bad path.
• Purpose: This skill prevents agents from either coding too soon on ambiguous work or over-planning simple work. It makes the execution path an explicit decision so planning, delegation, parallelization, review, and context reset are used only when the task shape justifies them.
• Boundary: This skill chooses the approach before execution. It does not execute the implementation, debug a concrete failure, optimize individual tool calls, manage Linear issue lifecycle, or record durable architecture decisions.
• Analogy: Task path optimization is like choosing a route before a trip: walking across the street needs no map, crossing a city needs traffic awareness, and crossing a mountain range needs checkpoints and fallback routes.
• Common misconception: The common mistake is treating more process as safer. The safest path is the smallest path that still handles ambiguity, dependency, risk, and verification.

Keywords

• optimal path, plan vs act, task decomposition, task complexity, lightest sufficient approach, agent architecture, scope management, shortest path to solution, failed twice, fresh approach