stefan-jansen/claude-code-toolkit/scqa-framework

SCQA Framework Skill

Foundation: McKinsey's SCQA (Situation-Complication-Question-Answer) framework, derived from Barbara Minto's pyramid principle

Core Concept: Build compelling narrative by establishing situation, introducing complication, raising question, then delivering answer.

Why This Works:

• Engages reader with familiar situation
• Creates tension with complication (problem)
• Raises question reader now wants answered
• Delivers answer with impact (reader is primed)
• Natural storytelling flow

The SCQA Structure

Four elements in sequence:

1. Situation (S)

What: The stable, uncontroversial starting point everyone agrees on

Purpose: Establish common ground with reader

Example:

"Software engineers use AI coding assistants to boost productivity."

Characteristics:

• Non-controversial (reader nods along)
• Familiar to target audience
• Sets the stage for complication

2. Complication (C)

What: The problem, change, or challenge that disrupts the situation

Purpose: Create tension and make reader care

Example:

"But generic AI agents produce unreliable code - state corruption, context loss, hallucinations. Teams abandon them after weeks of frustration."

Characteristics:

• Introduces conflict/problem
• Makes status quo untenable
• Resonates with audience pain
• Creates urgency

3. Question (Q)

What: The question reader now wants answered (often implicit)

Purpose: Focus attention on the answer you're about to provide

Example:

"How can we get AI productivity benefits without the reliability chaos?"

Characteristics:

• Natural question arising from complication
• What reader is now thinking
• Can be explicit or implicit
• Sets up your answer

4. Answer (A)

What: Your solution, recommendation, or core message

Purpose: Deliver the answer reader is now primed to receive

Example:

"CAF provides production-grade architecture that prevents AI chaos through stateless, file-based patterns proven over 6 months."

Characteristics:

• Directly addresses question
• This is your core message
• Reader is now receptive
• Rest of content supports this answer

Complete Example

Topic: Introducing CAF

Situation:

Claude Code has become a popular AI coding assistant, with developers using it daily for everything from bug fixes to feature development.

Complication:

However, Claude Code out-of-box is a generic assistant. It doesn't understand your domain, workflows, or constraints. As projects grow complex, generic responses become frustrating - developers spend more time correcting AI suggestions than coding.

Question (implicit):

How can we customize Claude Code for our specific domain without losing the ease of the IDE-based experience?

Answer:

The Claude Agent Framework (CAF) transforms Claude Code into domain-specific agents through simple markdown-based customization. Define domain commands, specialized agents, and behavioral skills - no programming required.

Variations

SCQ (Implicit Answer)

When to use: Answer is your entire document

Structure:

• Situation
• Complication
• Question
• [Your entire article/doc is the answer]

Example opening:

Situation: AI coding assistants promise productivity gains.

Complication: Generic assistants don't understand domain specifics.

Question: How do we customize AI for our domain?

[Rest of white paper answers this question]

SCA (Implicit Question)

When to use: Question is obvious from complication

Structure:

• Situation
• Complication
• Answer (question implied)

Example:

Situation: Developers use AI assistants daily.

Complication: But generic AI produces unreliable code - state corruption, context loss.

Answer: CAF prevents this through stateless architecture.

[Implied question: "How do we prevent AI reliability issues?"]

CSA (Situation Assumed)

When to use: Audience already knows situation

Structure:

• Complication (jump right to problem)
• [Situation implied]
• Answer

Example:

Complication: Generic AI assistants keep producing unreliable code.

Answer: Domain-specific customization through CAF solves this.

[Implied situation: "We're using AI assistants"]

Application to Content Types

Application 1: Opening Hook

Use SCQA for article/document opening:

# [Title]
 
[Situation - 1 paragraph]
Establish the current state that readers recognize.
 
[Complication - 1-2 paragraphs]
Introduce the problem or challenge that disrupts equilibrium.
Make readers feel the pain.
 
[Question - optional, can be implicit]
What readers are now asking.
 
[Answer - 1 paragraph]
Your core message / solution / recommendation.
This is what the rest of the document will elaborate on.
 
---
 
[Rest of document provides evidence and detail for the answer]

Application 2: Persuasive Narrative

Structure for convincing readers:

Situation: "Here's how things are..." Complication: "But this problem exists..." Question: "So what should we do?" Answer: "We recommend [solution]"

Body: Provide evidence for answer Closing: Reinforce answer + call to action

Application 3: Problem-Solution Content

SCQA maps to problem-solution:

• Situation + Complication = Problem definition
• Question = Bridge to solution
• Answer = Solution statement
• Body = Solution elaboration

Application 4: Positioning Statement

SCQA for competitive positioning:

Situation: "Current alternatives exist (Alt A, Alt B)" Complication: "But they have these limitations..." Question: "What's needed?" Answer: "We provide [unique value] that alternatives don't"

Integration with Pyramid Principle

SCQA + Pyramid work together:

SCQA: How to structure the opening/hook (narrative flow) Pyramid: How to structure the answer and supporting arguments (hierarchical)

Combined structure:

Opening (SCQA):
├─ Situation
├─ Complication
├─ Question
└─ Answer [This is Level 1 of pyramid]
 
Body (Pyramid):
├─ Argument 1 supporting Answer [Level 2]
│  └─ Evidence [Level 3]
├─ Argument 2 supporting Answer [Level 2]
│  └─ Evidence [Level 3]
└─ Argument 3 supporting Answer [Level 2]
   └─ Evidence [Level 3]
 
Closing:
└─ Reinforce Answer + CTA

SCQA gets reader to care about your answer. Pyramid organizes proof of answer.

Crafting Effective Components

Crafting Situation

Good situation:

• ✅ Familiar to audience
• ✅ Non-controversial
• ✅ Concise (1 paragraph)
• ✅ Sets stage for complication

Bad situation:

• ❌ Controversial (audience disagrees)
• ❌ Unfamiliar (audience confused)
• ❌ Too long (reader loses interest)
• ❌ Doesn't connect to complication

Crafting Complication

Good complication:

• ✅ Resonates with audience pain
• ✅ Creates urgency
• ✅ Makes status quo untenable
• ✅ Leads naturally to question

Bad complication:

• ❌ Audience doesn't relate
• ❌ No urgency (so what?)
• ❌ Too dramatic (not believable)
• ❌ Doesn't set up your answer

Crafting Question

Good question:

• ✅ Natural from complication
• ✅ What reader is thinking
• ✅ Your answer addresses it
• ✅ Can be implicit (often better)

Bad question:

• ❌ Disconnected from complication
• ❌ Too broad or vague
• ❌ Your answer doesn't address it
• ❌ Stated explicitly when obvious

Crafting Answer

Good answer:

• ✅ Directly addresses question
• ✅ Your core message
• ✅ Concise and memorable
• ✅ Rest of content supports it

Bad answer:

• ❌ Doesn't answer question
• ❌ Vague or generic
• ❌ Too complex (save detail for body)
• ❌ Not your actual core message

Common Mistakes

Mistake 1: Starting with Complication

❌ Don't jump to problem without context:

AI coding assistants produce unreliable code...

Why: Reader doesn't have context. What AI assistants? Who's using them?

✅ Establish situation first:

Software engineers use AI coding assistants daily. But these assistants produce unreliable code...

Mistake 2: Weak Complication

❌ Complication doesn't create urgency:

Situation: Developers use AI assistants.
Complication: Sometimes the suggestions could be better.

Why: "Could be better" doesn't create enough tension.

✅ Strong complication with real pain:

Situation: Developers use AI assistants.
Complication: But 40% abandon them within weeks due to state corruption and unreliable output - wasted time, broken code, lost trust.

Mistake 3: Answer Doesn't Match Question

❌ Mismatched Q&A:

Question: How do we make AI assistants more reliable?
Answer: CAF provides markdown-based customization.

Why: Answer talks about customization, not reliability.

✅ Matched Q&A:

Question: How do we make AI assistants more reliable?
Answer: CAF prevents failures through stateless architecture and file-based persistence.

Mistake 4: Answer Too Complex

❌ Answer tries to explain everything:

Answer: CAF is a meta-framework that provides commands, agents, and skills organized in a plugin architecture with markdown-based configuration that allows...

Why: Too much detail. Save for body.

✅ Concise answer, details later:

Answer: CAF transforms Claude Code into domain-specific agents through markdown-based customization.
 
[Body provides details about commands, agents, skills]

Quality Checklist

When applying SCQA, verify:

• [ ] Situation is familiar and non-controversial
• [ ] Complication creates real tension/urgency
• [ ] Complication resonates with audience pain
• [ ] Question naturally arises from complication
• [ ] Question is what reader now wants answered
• [ ] Answer directly addresses question
• [ ] Answer is your core message
• [ ] Answer is concise (details in body)
• [ ] Flow is natural (S→C→Q→A)
• [ ] Reader is now primed to hear evidence

Integration with Positioning

SCQA + Positioning Manifest:

From positioning manifest:

• Core message = Your Answer (A)
• Audience context/pain = Informs Complication (C)
• Desired action = Influences how you state Answer

Example:

{
  "core_message": "CAF transforms Claude Code into domain agents",
  "audience_context": "Developers frustrated by generic AI assistants"
}

Becomes SCQA:

• S: Developers use AI assistants
• C: But generic assistants frustrate with domain-ignorant responses
• Q: How to get domain-specific AI?
• A: CAF transforms Claude Code into domain agents

References

Foundation: McKinsey's SCQA framework, derived from Barbara Minto's pyramid principle

Key insight: People engage with stories that start where they are (Situation), introduce tension (Complication), raise a question they want answered (Question), then deliver the answer (Answer).

Application: Use SCQA for openings and persuasive narratives. Use Pyramid for organizing supporting evidence.

Skill Version: 1.0 Created: 2025-10-31 Used by: author agent (optional, for narrative structure) Key Innovation: Narrative engagement that primes reader to receive core message