Guided Focus

Guided Focus

Structured, one-at-a-time questioning to converge on requirements and decisions before planning or execution. Each question presents options with descriptions, trade-off differences, and a recommended choice with reasoning.

Quick Start

> /guided-focus

> /guided-focus 5

> Help me clarify before we plan

> Ask me questions first, then plan

When to Use

• Complex tasks with multiple valid approaches that need alignment before planning
• Ambiguous requirements where scope, goals, or constraints are unclear
• High-impact decisions (architecture, tech stack, migration strategy) that benefit from structured exploration
• User explicitly asks to clarify or align before starting work

When NOT to use: Single-file edits, bug fixes with clear reproduction steps, tasks where the user provides explicit requirements, or when the user has already described a clear plan.

Workflow

Phase 0: Activation

• Manual: User invokes /guided-focus or asks to clarify first
• Proactive: When detecting a complex/ambiguous task, ask: "This task has multiple valid approaches. Want to run guided focus first to align on direction?" — proceed only if user confirms
• Do NOT trigger proactively for: single-file edits, bug fixes with clear reproduction steps, tasks with explicit requirements, or when the user has already described a clear plan

Phase 1: Configuration

Defaults (user can override via arguments or during the session):

| Parameter | Default | Override Example | |-----------|---------|------------------| | Question count | 10 | /guided-focus 5 or /guided-focus --questions 5 | | Min options per question | 3 | /guided-focus --min-options 4 |

Phase 2: Questioning Loop

Ask questions one at a time. Wait for user response before proceeding.

Question format (use bullet list, not table — safe for narrow terminals):

### Question [current]/[total] — [Topic]

[Context sentence explaining why this question matters]

**A. [Option name]**
- Description: [what this option means]
- Difference: [how it differs from other options]
- Recommendation: Weak / Moderate / Strong

**B. [Option name]**
- Description: ...
- Difference: ...
- Recommendation: ...

**C. [Option name]**
- Description: ...
- Difference: ...
- Recommendation: ...

**Recommended: [letter] — [option name]**: [1-2 sentence reasoning]

Recommendation scale: Weak = viable but not ideal, Moderate = good fit, Strong = best fit for this context.

Question behavior rules:

• Dependency awareness: Adapt subsequent questions based on previous answers. Skip questions that become irrelevant, add questions that become necessary. When adjusting, tell the user: "Based on your answer to Q[N], I'm [skipping Q about X / adding a question about Y] because [reason]."
• Progress indicator: Always show [current]/[total] and update total if it changes
• Dynamic adjustment: May increase or decrease question count based on task complexity, but never exceed 15 questions total. Always inform the user: "I'm [adding/reducing] questions because [reason]. New total: [N]."

User response flexibility:

• Select an option (A/B/C)
• Combine options (A+B) — if combined options conflict, explain the conflict and ask the user to choose one or describe a reconciliation
• Provide a free-form answer
• Ask a counter-question for clarification
• Skip and defer: "skip" or "later" — mark as deferred, addressed in Phase 3
• Express confidence level: "B, but not sure" → marked as uncertain in summary
• End early: "enough", "done", or "wrap up" → immediately proceed to Phase 3

Phase 3: Deferred Question Resolution

If any questions were skipped/deferred during Phase 2:

1. Present all deferred questions in a single list
2. Ask once: "Want to revisit these, or proceed with them marked as undecided?"
3. If revisit → ask each deferred question with context from other answers
4. If proceed → mark all as undecided in summary

Phase 4: Summary

Generate a structured summary of all decisions:

## Focus Summary

**1. [Topic]**: [Decision] [confidence]
**2. [Topic]**: [Decision] [confidence]
...

### Uncertain Decisions
- **[Topic]**: [Decision marked as uncertain] — may need revisiting during implementation

### Undecided
- **[Topic]**: Deferred — [reason or context]

Confidence markers: [confirmed] | [uncertain] | [undecided]

Phase 5: Review & Handoff

After presenting the summary:

1. Ask: "Want to modify any decisions, or add more questions?"
2. If yes → allow edits or additional questions, regenerate summary
3. If no → ask: "Ready to proceed? Options: plan (enter plan mode), execute (start directly)"

Guidelines

DO

• One question at a time — never batch multiple questions
• Adapt questions dynamically — use dependency awareness, not a fixed script
• Explain adjustments — always tell the user why questions are added/removed/reordered
• Respect all response types — selections, combinations, free-form, counter-questions, skips
• Show progress — always display [current]/[total]
• Surface uncertainty — mark low-confidence decisions visibly in the summary
• Wrap up early — if requirements are clear before reaching the question count, propose to end and proceed to summary

DON'T

• Start without confirmation when triggered proactively — always ask first
• Ask obvious questions — skip questions where the answer is clearly implied by context
• Force linear order — if a user's answer makes a later question urgent, reorder
• Over-question — if requirements are clear, wrap up. The number of questions is dynamic but must not exceed the hard cap of 15

Notes

• Questions should progress from high-level (scope, goals, constraints) to specific (implementation details, trade-offs)
• The first 2-3 questions should establish context and scope; detailed questions come after
• If the user's project already has constraints (existing codebase, tech stack), detect and incorporate them rather than asking about known facts

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VdustR
• Source: VdustR/vp-claude-code-marketplace
• License: MIT
• Homepage: https://github.com/VdustR/skills

Install and usage instructions live in the source repository linked above.