decision-explorer

Decision Explorer

When to invoke

Use this skill when someone asks for help choosing a plugin mechanism: "interactive decision", "help me choose", "decision tree", "I'm not sure whether to use", "skill or agent", or "command or hook".

This skill provides a guided conversational exploration that asks questions one at a time and narrows the design space step by step. At the end, it produces a copyable architecture recommendation with the chosen mechanism, rationale, and suggested file structure.

The plugin-design-advisor skill is a reference for heuristics and anti-patterns -- consult it when you already know the landscape and need to look something up. This skill is for when you don't know where to start. It walks you through the decision interactively, so you don't need to read the full framework yourself.

---

How to guide the user

Conversational flow rules

Ask one question at a time. Present options as a numbered list. Wait for the user's answer before proceeding to the next node -- do not skip ahead or combine questions.

With each question, provide the signal examples listed under that node. These help the user recognize which answer fits their situation. If the user is unsure, talk through the signals together before moving on.

Track the path taken: which questions were asked and how the user answered. Use this path summary when generating the final recommendation so the rationale connects directly to the user's answers.

Decision tree

Q1: Does this capability need its own context window?

Signals to consider:

• Subtask is large enough to fill a significant portion of the context window
• There are parallel independent workstreams
• A different model is appropriate for the subtask
• The subtask needs different tool permissions than the main context

Options:

1. Yes -- proceed to Q2a.
2. No -- proceed to Q3.

Q2a: Are there multiple independent subtasks that can run in parallel?

Signals to consider:

• Each subtask produces independent output
• There is no data dependency between subtasks
• Results are aggregated after all subtasks complete

Options:

1. Yes -- recommend Agent (parallel). Note: if the domain knowledge driving these agents is reusable, consider pairing with a Skill that each agent loads at runtime.
2. No -- proceed to Q2b.

Q2b: Is the main benefit isolation, model tiering, or tool restriction?

Signals to consider:

• Subtask needs read-only tool access
• A cheaper model is sufficient for the subtask (e.g., extraction or formatting)
• Subtask output needs confidence scoring or structured filtering

Options:

1. Yes -- recommend Agent (isolated).
2. No -- the capability may not need an agent after all. Proceed to Q3.

Q3: Is the trigger a user action or a system event?

Signals to consider for user action:

• User types a slash command
• User asks for a workflow by name or description

Signals to consider for system event:

• Fires on file write
• Fires on session start
• Fires on tool invocation

Options:

1. User action -- proceed to Q4a.
2. System event -- proceed to Q4c.

Q4a: Does it orchestrate multiple steps with user decisions between them?

Signals to consider:

• Workflow has analyze/plan/execute phases
• User reviews intermediate results before the next step
• Multiple agents are coordinated with results aggregated

Options:

1. Yes -- recommend Command.
2. No -- proceed to Q4b.

Q4b: Is it reusable domain knowledge or a one-off workflow?

Signals to consider for knowledge:

• Pattern libraries, coding standards, decision frameworks, reference material
• Content is useful across multiple tasks or agents
• Auto-invocation from conversation context is the right trigger

Signals to consider for workflow:

• Single-use procedure or one-time setup
• Steps are specific to one scenario

Options:

1. Knowledge -- recommend Skill.
2. Workflow -- recommend Command (simple).

Q4c: Should it fire invisibly without user initiation?

Signals to consider:

• User would forget to invoke it manually
• Enforces conventions or guardrails automatically
• Action is lightweight and fast

Options:

1. Yes -- recommend Hook. Remind the user to include suppression logic so the hook doesn't fire redundantly (e.g., check session state or whether the relevant skill is already in context).
2. No -- recommend Command (user-triggered on event notification).

After reaching a recommendation

Before presenting the final output, perform these checks against the path taken through the decision tree.

Combo pattern check

If the recommendation is Agent and the user described reusable domain knowledge during the conversation (pattern libraries, coding standards, decision frameworks), recommend Skill+Agent instead. The skill captures the knowledge; the agent loads it at runtime and applies it in an isolated context.

If the recommendation is Hook and the conversation also identified a user-facing workflow component (setup steps, configuration review, or multi-step orchestration), recommend Hook+Command instead. The hook enforces the guardrail automatically; the command gives the user an explicit way to run the broader workflow on demand.

Anti-pattern warnings

Based on the path through the tree, warn about relevant anti-patterns when the answers suggest a mismatch:

• Agent recommended but the subtask seems trivial: Warn about agent-as-skill. If the subtask doesn't need isolation, parallelism, a different model, or separate tool permissions, it belongs in a skill, not an agent.
• Agent recommended but the domain knowledge is reusable across contexts: Warn about skill-as-agent. If the knowledge driving the agent would be useful to other agents or inline in conversation, extract it into a skill and have the agent load it at runtime.
• Skill recommended but it contains procedural steps with tool calls: Warn about procedure-as-skill. Skills inject knowledge -- they don't execute multi-step procedures. Procedural content belongs in a command or agent.
• Command recommended but the trigger is a system event the user might forget: Warn about command-without-hook. If the user is unlikely to remember invoking the command at the right moment, pair it with a hook or replace the command with a hook entirely.
• Hook recommended but no suppression logic was considered: Warn about hook-without-suppression. Every hook needs a mechanism to avoid firing redundantly (session state checks, context detection, or similar guards).

Cross-reference

Point the user to the plugin-design-advisor skill for the full heuristics, anti-pattern definitions, classification matrix, and worked examples. That skill is the comprehensive reference; this decision tree is a guided entry point into it.

Output

Present the final recommendation as a fenced markdown code block so the user can copy it directly. Fill in the template using the tracked path through the decision tree -- the justification should connect the user's answers to the recommendation.

```markdown
## Architecture

- **Mechanism:** [Skill | Agent | Command | Hook | Skill+Agent | Hook+Command]
- **Justification:** [1-2 sentences derived from the decision path taken]
- **Anti-patterns avoided:** [which ones and why]
- **Signals matched:** [list the signals from the classification matrix that apply]
```

After presenting the recommendation, offer to walk through another capability if the user has more components to classify.