analysis-iterative

name	analysis-iterative
description	This skill MUST be invoked when the user says "brainstorm", "deep analysis", "let's think through", "analyze this with me", or "help me think through". SHOULD also invoke when feature descriptions lack Who/Problem/Value clarity during specification enrichment.

Iterative Analysis

Overview

Guide collaborative thinking by adapting questioning style, depth, and output to the complexity that emerges during conversation. Each question builds on the previous answer, and the format of each question adapts to the user's current state — confident, uncertain, or somewhere in between. Conclude with a structured synthesis document whose depth matches the conversation's depth.

When to Use

• Brainstorming sessions that need structured exploration
• Deep analysis of complex problems with multiple decision points
• Thinking through feature requirements before specification
• Enriching sparse feature descriptions for humaninloop:specify
• Exploring trade-offs that require deliberate choices
• When the user is unsure and needs help discovering what they think

When NOT to Use

• Quick clarifications — simple questions do not need iterative questioning
• Implementation details — use planning skills instead
• Specification review — use humaninloop:analysis-specifications instead
• When user has clear direction — use confirmations to verify, then wrap up fast. Do not slow down decisive users with unnecessary exploration.
• Time-sensitive decisions — iterative questioning takes time

Adaptive Flow

Opening ──→ Discovery ──→ Adaptive Questioning ──→ Conclusion
  │              │                │                      │
  │              │                │                      │
  Brief,         Reveals          Format adapts per      Synthesis depth
  topic-         complexity       turn: structured       matches
  specific       and thinking     options / open         conversation
  entry          depth            probes / confirmations depth

Opening establishes the topic and asks the first question. Do not recite a fixed introduction script. Adapt tone and framing to the topic — a migration planning session opens differently than a notification brainstorm.

Discovery happens through the first 1-2 questions. Their purpose is dual: advance the conversation AND reveal how deep the exploration needs to go. See the Discovery section below.

Adaptive Questioning is the core loop. Each turn: read the answer, pick the right question format, ask one question. Continue until convergence signals appear or the user signals completion. See Question Format Adaptation and Reading Confidence Signals below.

Conclusion generates the synthesis artifact. See Smart Wrap-up below.

How long each phase lasts adapts to complexity. A crisp 3-question brainstorm may spend one turn in discovery. A complex architecture decision may spend three.

Discovery

The first 1-2 questions serve a dual purpose: advance the conversation toward substance AND calibrate complexity.

Principle: Ask a question that is genuinely useful on its own merit — not a meta-question about "how deep should we go." Read the answer for complexity signals.

What to look for in the first answer:

• Crisp, specific, opinionated → User knows the domain. Move faster, lean toward structured options.
• Vague, hedging, "I'm not sure" → Exploration needed. Lean toward open probes. Do not default to a recommendation when the user has not yet formed a view.
• Long, detailed, multi-dimensional → Complex problem space. Plan for more questions and a comprehensive synthesis.

"Unsure" is a first-class signal. When the user says "I don't know" or "I'm not sure," it means probe deeper from a different angle — not fill in a default recommendation and move on. After 3+ consecutive "unsure" answers, reframe the question from a different angle or suggest narrowing the scope to a concrete sub-problem.

Example — crisp answer branch:

"A, definitely. These are for ops teams monitoring infrastructure."

→ Confident and specific. Next question can offer structured options and move quickly.

Example — unsure answer branch:

"Honestly, I'm not sure how to categorize it. We're moving from a monolith..."

→ Unsure with some detail. Next question should be an open probe to help the user map what they know before offering options.

Question Format Adaptation

Three formats, selected based on the user's current state:

Structured Options + Recommendation

Use when: a genuine decision point exists and the user has enough context to evaluate options.

[Brief context connecting to previous answer]

**Question [N]**: [Clear, focused question]

**Options:**
- **A) [Option]**: [What it means and its implications]
- **B) [Option]**: [What it means and its implications]
- **C) [Option]**: [What it means and its implications]

**Recommendation**: Option [X] because [reasoning based on what is known so far]

Open-Ended Probes

Use when: the user is uncertain, the problem space is not yet mapped, or an answer revealed unexpected complexity. No options — ask a question that helps the user externalize their thinking.

[Acknowledge what was shared]

[Open question that helps the user articulate what they know,
or surfaces information needed for the next decision]

Confirmations

Use when: the user has clearly decided and the remaining question is just verification. Do not belabor obvious conclusions.

[Acknowledge the decision and its implications]

That seems settled. [Brief implication or transition to next topic]

Meta-principle: Pick the format that serves the user's current state. If uncertain which format to use, prefer the open probe — it gathers information without forcing premature commitment.

Example — same topic, different formats based on state:

Structured: "Which versioning mechanism fits best? A) URL path, B) Header, C) Query parameter"

Open probe: "What's the technical sophistication of the external partners who need to consume this API?"

Confirmation: "URL versioning for all consumers — that sounds settled. Moving on to deprecation policy."

Reading Confidence Signals

Recalibrate after every answer. The user's state can shift mid-conversation.

Signal	Meaning	Response
Crisp, specific, immediate	High confidence	Move faster. Structured options.
Hedging, "it depends," "I think maybe"	Moderate uncertainty	Slow down. Mix of probes and options.
"I don't know," "I'm not sure"	Low confidence	Switch to open probes. Help discover before deciding.
Disagrees with recommendation	Deliberate preference	Explore reasoning, push back once, then respect the choice.
Quick agreement without elaboration	Possible passive acceptance	Light challenge: "Just to pressure-test — what makes you prefer this over [alternative]?"

Disagreement handling: When the user picks differently than recommended — explore their reasoning, present counterarguments respectfully but directly, and if they maintain their choice after the challenge, accept it and integrate. Mark the decision as Contested in the synthesis.

Smart Wrap-up

Convergence signals — watch for these:

• Answers are becoming confirmatory, not exploratory
• Key trade-offs have been explicitly addressed
• No new dimensions are emerging
• User's confidence in direction is increasing

Nudge format: Suggest wrap-up, but always offer an exit:

The core decisions feel settled. Should the synthesis be generated, or is there
another dimension to explore?

Asymmetry principle: Wrapping up too early is worse than wrapping up too late. An extra question costs one turn. A missing decision costs rework. When in doubt, ask one more question.

Never force synthesis. The skill may nudge, but the user always has final say on when to conclude.

Output

Generate the synthesis document using SYNTHESIS.md.

Confidence indicators — assign based on conversation observation:

Indicator	Meaning
Confident	Clear, reasoned choice with no hesitation
Assumed	Inferred from context, never explicitly confirmed
Contested	User disagreed with recommendation; deliberate choice
Unsure	Expressed uncertainty; decided provisionally
Deferred	Explicitly postponed — not enough information now

Output scales with conversation. A 3-question brainstorm produces Problem Statement, Key Decisions, and Next Steps. A 10-question deep exploration produces all sections including Decision Trail and Risks. Never pad a lean conversation with filler sections.

Common Mistakes

Always Using Structured Options

Not every turn needs options and a recommendation. When the user is unsure, open probes help them discover what they think. Structured options on an uncertain user force premature decisions.

Ignoring "Unsure" Signals

"I don't know" means probe deeper, not "doesn't care." Treating uncertainty as indifference leads to recommendations the user passively accepts but does not own.

Multiple Questions Per Turn

One question per turn — always. Multiple questions fracture attention and produce shallow answers across all of them instead of one thoughtful answer.

Questions That Don't Connect

Every question must show how the previous answer shapes the direction. Jumping topics without connecting breaks the collaborative momentum.

Premature Synthesis

The skill may nudge toward wrap-up but must not force it. If core decisions are not yet made or key trade-offs are unaddressed, continue asking.

Rigid Opening Script

Do not recite a fixed "I'll ask you a series of questions" introduction. Adapt the opening to the topic's tone and the user's apparent energy.

Padding the Synthesis

Match output depth to conversation depth. A 3-question session does not need a Decision Trail, Risks section, or Open Questions. Include only sections with real content.

---

Modes

This skill supports specialized modes for specific use cases.

Specification Input Enrichment

When invoked with mode:specification-input, run a focused variant for enriching sparse feature descriptions. See SPECIFICATION-INPUT.md for the question agenda and ENRICHMENT.md for the output template.

Reference

See ADAPTIVE-EXAMPLES.md for annotated conversations showing these principles in action.