--- name: decision-funnel description: Structured investigate-iterate-synthesize pipeline (5->5->3->1) that sends parallel agents to explore different facets of a problem, iterates on findings, progressively synthesizes, and produces a detailed execution plan realizes: - orchestrator-workers - parallelization - checkpointing - planning - prompt-chaining --- # Decision Funnel: 5→5→3→1 Investigation Method A progressive investigation and synthesis pipeline. 5 parallel agents investigate, 5 parallel agents iterate and develop the findings, 3 agents synthesize, and 1 agent produces the final unified plan. The power comes from **breadth of investigation** and **progressive synthesis** — each wave compresses and refines what came before. The orchestrator decides dynamically how to use each wave based on what the previous wave produced. Based on the Double Diamond framework (British Design Council), Nominal Group Technique (NGT), and structured ideation best practices adapted for AI agent workflows. **CRITICAL: Agent Type Discipline.** When this skill's output specifies agent types for execution, it MUST use specialized `subagent_type` values from the Task tool (e.g., `frontend-excellence:react-specialist`, `backend-development:backend-architect`, `feature-dev:code-reviewer`). NEVER default to generic types like `general-purpose`, `Explore`, or `Bash` when a domain-specific specialist exists. See Phase 0 Domain Detection and D.4 Agent Type Selection for the mapping. **CRITICAL: Parallel Subagent Dispatch.** This skill MUST use the Task tool to dispatch work in parallel wherever phases are designed for independent execution. DO NOT run independent work sequentially in your own context — this wastes context window and removes the independence guarantee. Specifically: - **Phase 1 (5 investigators):** Launch ALL 5 in a SINGLE message with 5 Task tool calls. They run in parallel. - **Phase 2 (5 iterators):** Launch ALL 5 in a SINGLE message with 5 Task tool calls. They run in parallel. - **Phase 3 (3 synthesizers):** Launch ALL 3 in a SINGLE message with 3 Task tool calls. They run in parallel. - **Execution waves:** Launch all work units in a wave as parallel Task tool calls in a single message. - To dispatch in parallel, include multiple `Task(...)` invocations in the same assistant message. The system runs them concurrently. **CRITICAL: Disk Checkpoints Between Phases.** Every phase transition MUST write artifacts to disk BEFORE dispatching the next phase's agents. This is a BLOCKING requirement — if you skip the disk write step, a crash loses all work from the completed phase. Specifically: - **After Phase 0**: Write `phase-0/problem-statement.md` + `context-packets/phase-0-packet.md` + `STATUS.md` BEFORE dispatching Phase 1 investigators. - **After Phase 1**: Write `context-packets/phase-1-packet.md` + update `STATUS.md` BEFORE dispatching Phase 2 iterators. - **After Phase 2**: Write `context-packets/phase-2-packet.md` + update `STATUS.md` BEFORE dispatching Phase 3 synthesizers. - **After Phase 3**: Write `context-packets/phase-3-packet.md` + update `STATUS.md` BEFORE dispatching Phase 4 final synthesizer. - **After Phase 4**: Update `STATUS.md` after the execution plan is written to disk. If you find yourself about to dispatch agents without having written the preceding checkpoint files, STOP. Write the files first. No exceptions. **CRITICAL: Every Agent Writes Its Own Output to Disk.** Agents MUST write their output to their designated file path BEFORE returning. The orchestrator should NEVER rely on extracting content from an agent's return value as the primary record. Each agent prompt MUST include the exact file path where the agent should write its output. If an agent returns without having written its file, treat it as a failed agent and re-dispatch. This applies to ALL phases: - Phase 1 investigators write to `{ARTIFACT_ROOT}/phase-1/area-{N}-{slug}.md` - Phase 2 iterators write to `{ARTIFACT_ROOT}/phase-2/iterator-{N}-{focus}.md` - Phase 3 synthesizers write to `{ARTIFACT_ROOT}/phase-3/synthesis-{N}.md` - Phase 4 final synthesizer writes to `{ARTIFACT_ROOT}/phase-4/execution-plan.md` **CRITICAL: Use MCP Servers for Data.** Throughout every phase, actively use available MCP servers to query for real data rather than relying on assumptions or stale knowledge. This includes but is not limited to: - **Context7** (`mcp__context7__*` / `mcp__plugin_context7_context7__*`) — Query up-to-date library documentation, API references, and code examples for any technology in the problem space. Use this before making claims about how a library or framework works. - **Issue tracker** (e.g., GitHub Issues via `gh issue list / view`) — Read issue descriptions, acceptance criteria, comments, and linked context. Never fabricate issue details. - **Codebase tools** (e.g., `mcp__plugin_serena_serena__*`) — Use symbolic code analysis tools to understand existing architecture, find symbols, trace references, and read implementations. Prefer these over reading entire files. - **Browser/Playwright** (e.g., `mcp__playwright__*`) — Validate UI assumptions by actually looking at the current state of the application during investigation phases, not just during execution. - **Any other available MCP servers** — Check what's available and use them when they provide relevant data for the problem at hand. The goal is to ground every phase in real data. Phase 1 investigators should reference actual code patterns found via MCP tools. Phase 2 iterators should verify claims against real documentation. Phase 4 work unit specs should reference real file paths confirmed by codebase queries. ``` INPUT (broad problem/requirement) │ ▼ Phase 0: NORMALIZE ─── Define the problem, carve it into investigation areas │ ▼ Phase 1: INVESTIGATE ── 5 parallel agents (tasks assigned by orchestrator) │ ▼ Phase 2: ITERATE ────── 5 parallel agents (tasks assigned by orchestrator based on Phase 1) │ ▼ Phase 3: SYNTHESIZE ─── 3 parallel agents (tasks assigned by orchestrator based on Phase 2) ▼ Phase 4: COMMIT ─────── 1 agent produces the final unified execution plan │ ▼ OUTPUT (detailed execution plan ready for orchestration) ``` --- ## When to Use This Skill Use the decision funnel when: - A problem has multiple valid approaches and picking wrong is expensive - You need to defend against recency bias, novelty bias, or anchoring - The output must be a structured execution plan with work unit specs, sequencing, and verification - The decision will affect architecture, UX flow, or system design significantly Do NOT use for: - Single-line fixes or obvious changes - Tasks where the approach is already decided - Pure research or information gathering --- ## Input Requirements Before running the funnel, gather these from the conversation or explicitly ask: | Field | Description | |-------|-------------| | **Context** | What the conversation has established so far (requirements, constraints, prior decisions) | | **Goal** | What "done" looks like — concrete, measurable | | **Constraints** | Technical, scope, compatibility, accessibility, performance, etc. | | **Non-goals** | Explicitly out of scope (prevents scope creep during divergence) | | **Current state** | What exists today; relevant files, architecture, patterns | | **Risks & sensitivities** | What must not break; backwards compatibility needs | | **Verification** | How we validate the result works (tests, e2e, manual checks, visual inspection) | If any of these are ambiguous, ask the user before starting Phase 0. Do not assume. **Data gathering:** Use MCP servers to fill in gaps. Query the issue tracker for requirements, use codebase tools to understand current state, and fetch library docs via Context7 for any technology you're unfamiliar with. Do this BEFORE Phase 0, not during it. --- # Phase 0 — Normalize the Problem **Mode: CONVERGENT. No solutioning yet.** The goal is to ensure everyone (human and agent) agrees on what the problem actually is before generating solutions. 1. **Restate the problem** in 5–10 bullet points. Strip opinions and solutions — focus on observable facts, user needs, and system requirements. 2. **List assumptions and unknowns.** Flag anything that could invalidate an approach if the assumption is wrong. 3. **Identify the problem domains** — classify which domains this problem touches (see Domain Detection below). This determines which specialist agent types are used across all phases. 4. **Define evaluation criteria with weights** BEFORE seeing any options (prevents retrofitting criteria to justify a favorite). 5. **Carve the problem into 5 investigation areas.** This is the most important step — it determines what Phase 1's 5 parallel investigators will each focus on. Each area should be a different **facet** of the problem, not a different solution. Examples: - For a UI redesign: area 1 = current component structure, area 2 = accessibility gaps, area 3 = design system patterns, area 4 = performance implications, area 5 = state management needs - For an auth refactor: area 1 = current token flow, area 2 = security attack vectors, area 3 = session management patterns, area 4 = cross-app SSO requirements, area 5 = migration path from current system - For a data model change: area 1 = current schema + queries, area 2 = downstream consumers, area 3 = migration strategy, area 4 = performance impact, area 5 = backwards compatibility **Rules for area carving:** - Areas explore different ASPECTS of the problem, not different solutions - Each area should map to a domain specialist agent type - Areas should have minimal overlap — if two areas would investigate the same files, merge them - Each area should be independently investigable (no area depends on another's results) ### Standard Evaluation Criteria Adjust weights per problem. These are defaults: | Criterion | Weight | Description | |-----------|--------|-------------| | User impact | 20% | How much does this improve the user's experience? | | Correctness | 20% | Does it solve the actual problem completely? | | Complexity | 15% | How much cognitive/code complexity does it add? (lower is better) | | Risk | 15% | What can go wrong? How bad is the failure mode? | | Testability | 10% | Can we write clear, automated tests for this? | | Maintainability | 10% | Will this be easy to understand and modify in 6 months? | | Time-to-validate | 10% | How quickly can we prove it works or doesn't? | ### Domain Detection Analyze the problem and tag all applicable domains. Each domain activates a specialist investigation lens (Phase 1) and a specialist agent type for all phases. | Domain | Detected When | Investigation Focus | Agent Type | |--------|--------------|---------------------|------------| | **UI/Visual** | Problem involves layouts, styling, visual hierarchy, animations, theming | Aesthetics, consistency, visual hierarchy, responsiveness | UI/CSS specialist | | **React/Components** | Problem involves component architecture, state, props, hooks, rendering | Component boundaries, re-render efficiency, hook correctness | React specialist | | **State Management** | Problem involves stores, sync, real-time updates, caching | Data flow, race conditions, consistency guarantees | State management agent | | **API/Backend** | Problem involves endpoints, data fetching, auth, server logic | Contracts, error handling, security, performance | Backend/API agent | | **Database** | Problem involves schema, queries, migrations, data modeling | Normalization, query patterns, migration safety | Database agent | | **GraphQL** | Problem involves schema design, resolvers, federation, subscriptions | Schema design, N+1 risks, type safety, caching | GraphQL specialist | | **Auth/Security** | Problem involves authentication, authorization, tokens, encryption | Attack vectors, token handling, OWASP compliance | Security specialist | | **Accessibility** | Problem involves screen readers, keyboard nav, ARIA, color contrast | WCAG compliance, assistive tech compatibility, focus management | Accessibility specialist | | **Performance** | Problem involves load times, bundle size, rendering speed, memory | Bottlenecks, measurement methodology, regression risk | Performance specialist | | **Testing** | Problem involves test strategy, coverage, E2E, mocking | Coverage gaps, flakiness risk, test maintainability | Testing specialist | | **DevOps/Infra** | Problem involves CI/CD, deployment, monitoring, scaling | Deployment safety, rollback capability, observability | DevOps agent | | **Mobile/Native** | Problem involves iOS, Android, React Native, responsive mobile UX | Platform conventions, gesture handling, offline behavior | Mobile specialist | **Rules:** - Tag 2–5 domains. If you tag more than 5, the problem may need to be decomposed into separate funnels. - If you tag fewer than 2, you may be thinking too narrowly — most real problems span multiple domains. - The detected domains directly determine which specialist agent types are used in Phase 1 investigation areas and throughout the funnel. See each phase for how they're used. **Output:** Problem statement + assumptions + domain tags + weighted criteria table + **5 investigation areas with assigned agent types**. ### DISK CHECKPOINT: Phase 0 → Phase 1 **BLOCKING — do NOT dispatch Phase 1 investigators until all three writes complete.** 1. **Write `{ARTIFACT_ROOT}/phase-0/problem-statement.md`** — the full Phase 0 output (problem restatement, assumptions, domain tags, evaluation criteria, 5 investigation areas with agent types). 2. **Write `{ARTIFACT_ROOT}/context-packets/phase-0-packet.md`** — the compressed context packet that Phase 1 investigators will receive. Use the Context Packet Format (see Context Management section). 3. **Write `{ARTIFACT_ROOT}/STATUS.md`** — initial recovery manifest marking Phase 0 complete and Phase 1 as in-progress. Include the problem summary, domain tags, and artifact paths. Verify all three files exist on disk before proceeding. If any write fails, retry before dispatching agents. --- # Phase 1 — "5": Investigate **Mode: DIVERGENT. Breadth of understanding.** **CRITICAL: Dispatch all 5 investigators as PARALLEL subagents using the Task tool.** All 5 Task calls MUST be in the SAME assistant message so they run concurrently. Do NOT investigate sequentially in your own context. ### How to plan the wave: The orchestrator reads the Phase 0 output, decides what this wave of 5 agents needs to investigate, and assigns each agent a specific task. ### Each investigator receives: - The phase-0-packet (problem statement, constraints, criteria) - Their specific assigned task from the orchestrator's plan ### Each investigator must: 1. **Write output to their designated file** at `{ARTIFACT_ROOT}/phase-1/area-{N}-{slug}.md` — this is the agent's PRIMARY deliverable, not the return value. Write the file BEFORE returning. 2. **Analyze** their assigned area 3. **Produce multiple suggestions** within their area 4. **Provide an overall recommendation** for their area ### Investigator agent type selection: Each investigator's `subagent_type` is determined by the domain of their assigned task (from the Domain Detection table → Agent Type Selection mapping in D.4). Match the agent type to the task's domain. ### After all 5 investigators return: The orchestrator reads all 5 investigation reports and produces a **phase-1-packet** — a compressed summary of the wave's findings. **Output:** 5 investigation reports (one per area) + phase-1-packet. ### DISK CHECKPOINT: Phase 1 → Phase 2 **BLOCKING — do NOT dispatch Phase 2 iterators until all writes complete.** 1. **Verify all 5 investigation reports exist on disk** at `{ARTIFACT_ROOT}/phase-1/area-{N}-{slug}.md`. If any are missing (agent failed to write), re-dispatch that investigator. 2. **Write `{ARTIFACT_ROOT}/context-packets/phase-1-packet.md`** — compressed findings from all 5 investigators. Use the Context Packet Format. This is what Phase 2 iterators will receive — NOT the raw reports. 3. **Update `{ARTIFACT_ROOT}/STATUS.md`** — mark Phase 1 complete, Phase 2 in-progress. List all 5 investigation report paths. Verify all files exist on disk before proceeding. If any write fails, retry before dispatching agents. --- # Phase 2 — "5": Iterate and Develop **Mode: DIVERGENT→CONVERGENT. Build on what was found.** **CRITICAL: Dispatch all 5 iterators as PARALLEL subagents using the Task tool.** All 5 Task calls MUST be in the SAME assistant message. ### How to plan the wave: The orchestrator reads the phase-1-packet, decides what this wave of 5 agents needs to accomplish based on what Phase 1 produced, and assigns each agent a specific task. ### Each iterator receives: - The phase-0-packet (problem + criteria) - The phase-1-packet (compressed findings from all 5 investigators) - Their specific assigned task from the orchestrator's plan ### Each iterator must: 1. **Write output to their designated file** at `{ARTIFACT_ROOT}/phase-2/iterator-{N}-{focus}.md` — this is the agent's PRIMARY deliverable. Write the file BEFORE returning. 2. **Analyze** the Phase 1 findings through their assigned task 3. **Produce multiple suggestions** 4. **Provide an overall recommendation** for their area ### Iterator agent type selection: Iterators should generally be `feature-dev:code-architect`. For highly domain-specific tasks, use the domain specialist from the Agent Type Selection table. ### After all 5 iterators return: The orchestrator reads all 5 iterator reports and produces a **phase-2-packet** — a compressed summary of the wave's findings. **Output:** 5 iterator reports + phase-2-packet. ### DISK CHECKPOINT: Phase 2 → Phase 3 **BLOCKING — do NOT dispatch Phase 3 synthesizers until all writes complete.** 1. **Verify all 5 iterator reports exist on disk** at `{ARTIFACT_ROOT}/phase-2/iterator-{N}-{focus}.md`. If any are missing, re-dispatch that iterator. 2. **Write `{ARTIFACT_ROOT}/context-packets/phase-2-packet.md`** — catalog of all distinct suggestions and recommendations, grouped by similarity, annotated with evaluation criteria fit. This is what Phase 3 synthesizers will receive. 3. **Update `{ARTIFACT_ROOT}/STATUS.md`** — mark Phase 2 complete, Phase 3 in-progress. List all 5 iterator report paths. Verify all files exist on disk before proceeding. --- # Phase 3 — "3": Synthesize **Mode: CONVERGENT. Compress and reconcile.** **CRITICAL: Dispatch all 3 synthesizers as PARALLEL subagents using the Task tool.** All 3 Task calls MUST be in the SAME assistant message. ### How to plan the wave: The orchestrator reads the phase-2-packet, decides what this wave of 3 agents needs to accomplish based on what Phase 2 produced, and assigns each agent a specific task. ### Each synthesizer receives: - The phase-0-packet (problem + criteria) - The phase-2-packet (all developed suggestions from the 5 iterators) - Their specific assigned task from the orchestrator's plan ### Each synthesizer must: 1. **Write output to their designated file** at `{ARTIFACT_ROOT}/phase-3/synthesis-{N}.md` — this is the agent's PRIMARY deliverable. Write the file BEFORE returning. 2. **Analyze** the Phase 2 findings through their assigned task 3. **Produce multiple suggestions** 4. **Provide an overall recommendation** for their area ### Synthesizer agent type: Use `feature-dev:code-architect` for all 3. They need broad architectural thinking, not domain specialization. ### After all 3 synthesizers return: The orchestrator reads all 3 synthesis reports and produces a **phase-3-packet** — a compressed summary of the wave's findings, to be used as input for the Phase 4 final synthesis. **Output:** 3 synthesis reports + phase-3-packet. ### DISK CHECKPOINT: Phase 3 → Phase 4 **BLOCKING — do NOT dispatch the Phase 4 final synthesizer until all writes complete.** 1. **Verify all 3 synthesis reports exist on disk** at `{ARTIFACT_ROOT}/phase-3/synthesis-{N}.md`. If any are missing, re-dispatch that synthesizer. 2. **Write `{ARTIFACT_ROOT}/context-packets/phase-3-packet.md`** — comparison of the 3 synthesis outputs against evaluation criteria, areas of agreement/divergence, strongest candidates. This plus the raw Phase 3 artifacts are what Phase 4 receives. 3. **Update `{ARTIFACT_ROOT}/STATUS.md`** — mark Phase 3 complete, Phase 4 in-progress. List all 3 synthesis report paths. Verify all files exist on disk before proceeding. --- # Phase 4 — "1": Final Synthesis into Execution Plan **Mode: COMMIT. One plan, fully detailed.** A single agent takes the 3 Phase 3 outputs and produces the final unified execution plan. This is NOT just "pick the best of 3" — it's a final synthesis that may combine elements from multiple Phase 3 outputs. ### The final synthesizer receives: - The phase-0-packet (problem + criteria) - The phase-3-packet (3 synthesis outputs, compared) - The full Phase 3 artifacts (all 3 synthesis write-ups) — this is the one place where the agent reads raw artifacts, because it needs the full detail to produce the final plan ### The final synthesizer must: 1. **Write the execution plan to `{ARTIFACT_ROOT}/phase-4/execution-plan.md`** — this is the agent's PRIMARY deliverable. Write the file BEFORE returning. 2. **Select and combine** the strongest elements from across Phase 3 outputs 3. **Justify the selection** against the evaluation criteria with specific reasoning 4. **Verify completeness** — does the final plan address every aspect of the original problem statement from Phase 0? 5. **Check for blind spots** — did any investigation area's concerns get lost during synthesis? 6. **Produce the full execution plan** (see Output — Execution Plan below) ### Final synthesizer agent type: Use `feature-dev:code-architect`. ### DISK CHECKPOINT: Phase 4 Complete **BLOCKING — the funnel is not complete until these writes succeed.** 1. **Verify the execution plan exists on disk** at `{ARTIFACT_ROOT}/phase-4/execution-plan.md`. If the Phase 4 agent failed to write it, extract the plan from the agent's return value and write it yourself. 2. **Update `{ARTIFACT_ROOT}/STATUS.md`** — mark Phase 4 complete. Fill in the "Chosen Approach" section with 2-3 sentences. Mark all phases as complete in the Phase Completion checklist. --- # Output — Execution Plan The execution plan must be detailed enough that an orchestration system (e.g., subagent-workflow) can execute it without further clarification. ## Structure: ### A) ELI5 Explanation Non-technical summary anyone could understand. 3–5 sentences. ### B) 5-Sentence Summary What will change, at a technical level, in exactly 5 sentences. ### C) Table of Contents Every section of the plan with 1–2 sentence summaries. ### D) Full Detailed Plan #### D.1) Architecture / Approach Summary How the chosen plan works. Diagrams if helpful. Key patterns and decisions. #### D.2) Step-by-Step Implementation Sequence Ordered list of what gets built/changed and in what order. Include dependency arrows between steps. #### D.3) Work Unit Specs Define the units of work that the orchestration workflow will turn into real GitHub Issues. **This skill does NOT create issues** — it produces specs. The orchestration workflow (e.g., `Skill(subagent-workflow)`) is responsible for creating actual issues, assigning them, and tracking their state. Each work unit spec: ``` ### Work Unit: {TITLE} **Objective:** What this unit accomplishes **Files/areas touched:** List of files or modules **Implementation notes:** Key decisions, patterns to follow, gotchas **Acceptance criteria:** - [ ] Criterion 1 - [ ] Criterion 2 **Tests/verification:** - [ ] Test 1 - [ ] Test 2 **Risks/rollback:** What could go wrong and how to undo it **Dependencies:** Which other work units must complete before this one **Recommended agent type:** `subagent_type` value (see D.4) ``` ##### Recommended Ticket Breakdown After the work unit specs, include a **recommended ticket breakdown** — guidance for the orchestration workflow on how to turn these work units into actual tickets in the issue tracker. This is a recommendation, not the tickets themselves. ``` ## Recommended Ticket Breakdown ### Ticket strategy: {one-ticket-per-unit | grouped | phased} | Suggested Ticket | Work Units Covered | Rationale | |------------------|--------------------|-----------| | "{ticket title}" | Units 1, 2 | Same component, tightly coupled changes | | "{ticket title}" | Unit 3 | Independent, can parallelize | | "{ticket title}" | Units 4, 5 | Sequential dependency, same feature area | ### Parallelization recommendation - **Wave 1 (parallel):** Tickets A, B — no dependencies - **Wave 2 (after wave 1):** Ticket C — depends on A - **Wave 3 (after wave 2):** Ticket D — integration/verification ### Sizing guidance - Each ticket should be completable by a single agent in one session - If a work unit is too large for one agent session, split it and note the split - Group tightly-coupled work units into one ticket to avoid cross-ticket coordination ``` The orchestration workflow reads this breakdown and creates the actual tickets. This keeps the decision funnel's output as a plan/recommendation while giving the orchestrator clear guidance. #### D.4) Agent/Task Orchestration Plan How the orchestration workflow should divide work across parallel agents. Agent types MUST be selected from the available `subagent_type` options in the Task tool (see Agent Type Selection below). - **Agent assignments per work unit** — map each unit to a specific `subagent_type` based on domain match - **Context allocation per agent** — what each agent receives (keep minimal; summarize, don't dump) - **Expected outputs per agent** — files, PRs, test results, notes - **Parallelization strategy** — which work units can run simultaneously vs. sequentially **IMPORTANT: Parallel dispatch mechanics.** The orchestrator MUST launch independent work units as multiple Task tool calls in a SINGLE assistant message. This is how the Task tool achieves parallelism — multiple calls in one message run concurrently. Sequential messages = sequential execution. Specifically: ``` // CORRECT — parallel (all in one message): Task(subagent_type="react-specialist", prompt="Work unit 1: ...") Task(subagent_type="backend-architect", prompt="Work unit 2: ...") Task(subagent_type="css-expert", prompt="Work unit 3: ...") // WRONG — sequential (separate messages): Message 1: Task(subagent_type="react-specialist", prompt="Work unit 1: ...") Message 2: Task(subagent_type="backend-architect", prompt="Work unit 2: ...") Message 3: Task(subagent_type="css-expert", prompt="Work unit 3: ...") ``` ##### Agent Type Selection When assigning agents to work units, select from the available specialized `subagent_type` values in the Task tool. Match the work unit's primary domain to the most specific agent type available. **Do NOT default to generic agent types (e.g., "general-purpose", "Explore", "Bash") when a specialist exists.** Map domains from Phase 0 to agent types: | Domain | Preferred `subagent_type` | Fallback | |--------|--------------------------|----------| | UI/Visual | `frontend-excellence:css-expert`, `ui-design:ui-designer` | `frontend-excellence:component-architect` | | React/Components | `frontend-excellence:react-specialist` | `frontend-excellence:component-architect` | | State Management | `frontend-excellence:state-manager` | `frontend-excellence:react-specialist` | | API/Backend | `backend-development:backend-architect` | `javascript-typescript:typescript-pro` | | Database | `database-design:database-architect`, `database-design:sql-pro` | `backend-development:backend-architect` | | GraphQL | `backend-development:graphql-architect` | `backend-development:backend-architect` | | Auth/Security | `backend-development:backend-architect` | `javascript-typescript:typescript-pro` | | Accessibility | `accessibility-compliance:ui-visual-validator` | `ui-design:accessibility-expert` | | Performance | `frontend-excellence:frontend-optimizer` | `frontend-excellence:react-specialist` | | Testing | `backend-development:tdd-orchestrator` | `javascript-typescript:typescript-pro` | | DevOps/Infra | `shell-scripting:bash-pro` | `Bash` | | Mobile/Native | `multi-platform-apps:mobile-developer` | `multi-platform-apps:flutter-expert` | | Code Review | `feature-dev:code-reviewer`, `code-refactoring:code-reviewer` | `feature-dev:code-reviewer` | | Architecture | `feature-dev:code-architect` | `backend-development:backend-architect` | | Codebase Analysis | `feature-dev:code-explorer` | `Explore` | **Rules:** - Every work unit in the orchestration plan MUST specify an explicit `subagent_type` value - If a work unit spans multiple domains, pick the agent whose specialty covers the most critical aspect - For review work units, always use a `code-reviewer` variant - For initial codebase exploration before implementation, use `feature-dev:code-explorer` #### D.5) Checkpoints Between Milestones After each milestone: - What to verify (tests, lint, typecheck, e2e, visual inspection) - What constitutes "stop and fix before continuing" - What constitutes "good enough, proceed" #### D.6) Branch and Merge Strategy - Sync from mainline before starting (if applicable) - Feature branch naming convention - Commit strategy (per work unit? per milestone?) - Final verification before merge/handoff --- # Artifact Tracking Write all phase outputs to an organized directory structure: ``` {ARTIFACT_ROOT}/ ├── STATUS.md ← RECOVERY MANIFEST (always up-to-date) ├── phase-0/ │ └── problem-statement.md ← Problem, domains, criteria, 5 investigation areas ├── phase-1/ │ ├── area-1-{slug}.md ← Investigator 1 findings │ ├── area-2-{slug}.md ← Investigator 2 findings │ ├── area-3-{slug}.md ← Investigator 3 findings │ ├── area-4-{slug}.md ← Investigator 4 findings │ └── area-5-{slug}.md ← Investigator 5 findings ├── phase-2/ │ ├── iterator-1-{focus}.md ← Iterator 1 output │ ├── iterator-2-{focus}.md ← Iterator 2 output │ ├── iterator-3-{focus}.md ← Iterator 3 output │ ├── iterator-4-{focus}.md ← Iterator 4 output │ └── iterator-5-{focus}.md ← Iterator 5 output ├── phase-3/ │ ├── synthesis-1.md ← Synthesizer 1 output │ ├── synthesis-2.md ← Synthesizer 2 output │ └── synthesis-3.md ← Synthesizer 3 output ├── phase-4/ │ └── execution-plan.md ← Final unified plan ├── context-packets/ │ ├── phase-0-packet.md │ ├── phase-1-packet.md │ ├── phase-2-packet.md │ └── phase-3-packet.md └── execution/ ← Created during orchestration ├── ticket-status.md └── agent-outputs/ ├── ticket-1/ ├── ticket-2/ └── ... ``` **Artifact root: `docs/{topic-slug}/`** where `{topic-slug}` is a short kebab-case name derived from the investigation topic (e.g., `docs/round-recap-flow/`, `docs/ui-redesign/`, `docs/auth-refactor/`). This keeps investigation artifacts alongside project documentation and makes them discoverable by future sessions. If the user specifies a different location (e.g., `tmp/`), use that instead. ### Recovery Manifest: STATUS.md **This file is the single source of truth for crash recovery.** It MUST be updated at every phase transition and every ticket state change. A new conversation with zero context should be able to read this one file and know exactly where things stand. Write `STATUS.md` at `{ARTIFACT_ROOT}/STATUS.md` with this format: ```markdown # Decision Funnel Status: {topic} ## Current State - **Phase:** {0|1|2|3|4|execution} - **Sub-state:** {e.g., "Phase 1: investigators 1-3 complete, 4-5 pending" or "Execution: work units 1-3 done, unit 4 in progress"} - **Last updated:** {ISO timestamp} - **Artifact root:** {absolute path} ## Problem Summary {2-3 sentences from Phase 0 — what we're solving} ## Chosen Approach {Filled after Phase 4 — 2-3 sentences on what was selected and why} ## Domain Tags {List from Phase 0} ## Phase Completion - [x] Phase 0: Normalize — {artifact path} - [x] Phase 1: Investigate (5 areas) — {artifact path} - [ ] Phase 2: Iterate (5 iterators) — iterators 1-3 done, 4-5 pending - [ ] Phase 3: Synthesize (3 synthesizers) - [ ] Phase 4: Final plan - [ ] Execution ## Execution Progress (if in execution) | Ticket | Title | Agent Type | Status | Branch/PR | Notes | |--------|-------|------------|--------|-----------|-------| | 1 | ... | `react-specialist` | done | PR #45 | merged | | 2 | ... | `backend-architect` | in-progress | feat/... | blocked on ticket 1 | | 3 | ... | `css-expert` | pending | — | — | ## Context Packets Available - phase-0-packet.md: {1-line summary} - phase-1-packet.md: {1-line summary} - ... ## Recovery Instructions To resume from this state: 1. Read this STATUS.md 2. Read the context packet for the current phase 3. Read any incomplete artifacts for the sub-state 4. Continue from where the sub-state indicates ``` **Update rules (MANDATORY — these are enforced by DISK CHECKPOINT blocks in each phase):** - Update STATUS.md BEFORE starting each phase (mark it in-progress) — this happens as part of the DISK CHECKPOINT at the end of the preceding phase - Update STATUS.md AFTER completing each phase (mark it done, link artifacts) — this happens as part of the DISK CHECKPOINT at the end of the completing phase - During execution, update after each ticket completes or changes state - Never delete previous entries — only update status fields - **If STATUS.md does not exist when you are about to dispatch agents for ANY phase, STOP.** You have skipped a checkpoint. Write STATUS.md before proceeding. --- # Context Management **This is critical.** Without discipline here, agents run out of context window or produce degraded output from consuming too much upstream content. This is the most common failure mode of the 5→5→3→1 method. ### Context Budget Rules Each agent dispatched via the Task tool has a finite context window. The funnel generates a LOT of content across phases. You must actively manage what goes into each agent's prompt. #### Budget Tiers | What the agent receives | Approximate token cost | Rule | |------------------------|----------------------|------| | Full phase output (e.g., all 5 options) | 3,000–8,000 tokens per option | NEVER send to downstream agents | | Context packet (1–2 pages) | 500–1,000 tokens | Safe to send; this is the designed handoff artifact | | Single work unit spec with implementation notes | 200–500 tokens | Safe to send | | Full execution plan | 2,000–5,000 tokens | Only send to orchestrator; individual agents get their work unit only | | Codebase reads (file contents) | Varies wildly | Agent reads on-demand; do NOT pre-load files into prompt | #### The Context Waterfall (what each phase/agent sees) ``` Phase 0 (orchestrator): problem input only ↓ produces phase-0-packet (problem + areas + criteria) Phase 1 investigators: phase-0-packet + their specific area assignment (5 parallel) ↓ orchestrator reads all 5 reports, produces phase-1-packet Phase 2 iterators: phase-0-packet + phase-1-packet (compressed findings) (5 parallel) ↓ orchestrator reads all 5 reports, produces phase-2-packet Phase 3 synthesizers: phase-0-packet + phase-2-packet (compressed Phase 2 output) (3 parallel) ↓ orchestrator reads all 3 syntheses, produces phase-3-packet Phase 4 final synth: phase-0-packet + phase-3-packet + full Phase 3 artifacts (1 agent) ↓ produces execution-plan Execution agents: goal (from phase-0-packet) + plan (from phase-4) + their specific work unit(s) ONLY ``` **Key principle: each agent sees packets from AT MOST 2 prior phases, never the raw artifacts. Exception: Phase 4 reads Phase 3 raw artifacts because it needs full detail for final synthesis.** #### Context Packet Format (strict) Each context packet MUST fit this template. If it exceeds ~1,000 tokens, it's too long — cut prose, keep data. ```markdown # Context Packet: Phase {N} ## Decisions Made - {bullet list of key decisions, max 5} ## Key Data - {scores, rankings, numbers — not prose} ## Carry-Forward Concerns - {max 3 items that the next phase must address} ## Artifacts (read only if needed) - {file path}: {1-line description} ``` #### Anti-Bloat Rules 1. **Never paste file contents into agent prompts.** Tell the agent which file to read; let it read on-demand. 2. **Never send "for reference" context.** If the agent doesn't need it for their specific work unit, don't include it. 3. **Summarize, don't excerpt.** If an investigator wrote 500 words about a risk, the packet says "Area 3 found high risk in auth integration — token flow incompatible with proposed change." That's it. 4. **One work unit per agent prompt when possible.** If an agent handles 2+ units, they must be tightly related (same files, same feature). Otherwise, dispatch separate agents. 5. **Agent prompts should be under 2,000 tokens** (excluding the skill/system prompt). If your prompt to a dispatched agent exceeds this, you're sending too much context. --- # Crash Recovery Sessions crash, context gets lost, conversations expire. The funnel is designed to be **fully recoverable from local artifacts alone** — no conversation history required. ### What Gets Lost in a Crash - The conversation context (messages, reasoning, intermediate thinking) - Any agent state that wasn't written to disk - The orchestrator's mental model of what's in progress ### What Survives a Crash - Everything in `{ARTIFACT_ROOT}/` — STATUS.md, phase outputs, context packets, execution artifacts - Git state — branches, commits, worktrees, PRs - GitHub Issue state — issue labels, assignees, linked PRs, comments ### Recovery Procedure When starting a new conversation after a crash, or when the user says "recover" or "where were we": #### Step 1: Find the artifact root ``` Look for STATUS.md in docs/ subdirectories: docs/*/STATUS.md If multiple exist, show the user the list and ask which to resume. ``` #### Step 2: Read STATUS.md This tells you: - Which phase was in progress - Which sub-steps were complete - Which tickets were in flight - Where all artifacts live #### Step 3: Read the relevant context packets Based on the current phase from STATUS.md, read ONLY the packets needed: - If resuming Phase 2: read phase-0-packet + phase-1-packet - If resuming Phase 3: read phase-0-packet + phase-2-packet - If resuming execution: read phase-0-packet + phase-4-packet (execution plan) **Do NOT read all artifacts.** The packets contain everything you need. Only read raw phase artifacts if a packet is missing or STATUS.md indicates an artifact was incomplete. #### Step 4: Check git and ticket state ```bash # Check for in-flight branches git branch --list 'feat/*' --list 'fix/*' # Check for active worktrees git worktree list # Check for open PRs gh pr list --state open ``` Cross-reference with STATUS.md's execution progress table. #### Step 5: Resume Based on what you find: | State | Action | |-------|--------| | **Mid-phase (e.g., Phase 1 investigators 1-3 done)** | Read completed artifacts + packets, dispatch remaining agents, continue | | **Between phases (e.g., Phase 2 done, Phase 3 not started)** | Read the latest packet, proceed to next phase | | **Mid-execution (some tickets done)** | Read execution plan + ticket-status.md, dispatch agents for remaining tickets | | **Execution done but not merged** | Check PR state, run verification, proceed to merge | | **STATUS.md missing** | Scan artifact root for what exists, reconstruct state from file timestamps and contents, write STATUS.md before proceeding | #### Step 6: Announce state to user Before doing anything, tell the user: ``` Recovered funnel state for "{topic}": - Phase: {current phase} - Progress: {what's done / what's pending} - Next action: {what you'll do next} Proceed? ``` ### Preventing Data Loss During Execution These rules prevent the "crash and lose everything" scenario: 1. **Write STATUS.md before AND after every state transition.** This is a ~100-token write. Do it every time. No exceptions. 2. **Agents must write their output to disk before reporting completion.** Never rely on agent return values as the sole record. 3. **Commit incrementally during execution.** After each ticket completes and passes checks, commit to the feature branch. Don't batch commits at the end. 4. **Execution agents write to `{ARTIFACT_ROOT}/execution/agent-outputs/ticket-{N}/`.** Each agent writes: - `summary.md` — what was done, what files changed - `status.md` — pass/fail, test results, any issues 5. **The orchestrator updates `{ARTIFACT_ROOT}/execution/ticket-status.md`** after each agent completes, with a simple table matching the STATUS.md format. --- # Stop Condition **Do not execute.** This skill produces a plan only. Output the execution plan and stop. To execute, the user must explicitly invoke their orchestration workflow (e.g., `Skill(subagent-workflow)`) with the plan as input. --- # Quick Invocation For rapid use, reference this skill and provide input from the current conversation: ``` Use the decision funnel (5→5→3→1) on the following. Output a fully structured execution plan ready for orchestration. Here is the input: {paste or reference the requirement/spec/problem from the conversation} ``` --- # Troubleshooting **Agents in a wave produced redundant output:** The orchestrator's task assignments for that wave weren't differentiated enough. Re-read the previous wave's output and reconsider how to assign tasks to the agents. **Agents didn't follow their assigned task:** The prompt was too vague or included too much context that distracted from the specific task. Re-dispatch with a more focused prompt and less background context. **Context packets are too long:** Enforce the 1–2 page limit strictly. If you can't summarize a phase in 2 pages, the phase output needs restructuring, not a longer summary. **User wants to skip phases:** The funnel's value comes from the full pipeline. Skipping Phase 2 (iteration) is the most common request and the most dangerous — without it, raw investigation findings go directly to synthesis without being developed. Push back gently but firmly. **Agent ran out of context / output degraded:** The agent prompt was too large. Check: (1) Are you sending raw phase artifacts instead of context packets? (2) Are you sending multiple work units to one agent? (3) Are you pre-loading file contents into the prompt instead of letting the agent read on-demand? Fix: follow the Context Waterfall strictly — each agent sees packets from at most 2 prior phases. Agent prompts should be under 2,000 tokens. **Crashed mid-funnel, no conversation context:** Read `{ARTIFACT_ROOT}/STATUS.md`. It contains the full recovery state. Follow the Crash Recovery procedure — read STATUS.md, then the relevant context packets, then resume from the indicated sub-state. Do NOT re-read all phase artifacts. **STATUS.md is missing or stale:** Scan the artifact root directory. Check which phase folders exist and which contain complete artifacts. Look at file timestamps to determine order. Reconstruct STATUS.md from what you find, write it, then proceed with recovery. **This situation means the DISK CHECKPOINT rules were violated in the previous session.** After recovering, ensure all missing checkpoint artifacts (problem-statement.md, context packets) are reconstructed before dispatching any new agents. **Context packets are missing but phase artifacts exist:** This means the orchestrator completed a phase but skipped the DISK CHECKPOINT. Reconstruct the missing context packet by reading the raw phase artifacts and compressing them into the Context Packet Format. Write the packet to disk, then update STATUS.md, before proceeding to the next phase. **Multiple funnel artifact roots exist:** List all `docs/*/STATUS.md` files, show the user their topics and states, and ask which to resume.