
scqa-framework
by applied-artificial-intelligence
Production-tested commands, skills, and workflow patterns for Claude Code. Developed through 6+ months of daily use. Includes explore→plan→next→ship workflow, session handoffs, MCP integrations, and domain skills. Copy what works, adapt to your needs.
SKILL.md
name: scqa-framework description: Narrative structure for complex topics - Situation, Complication, Question, Answer foundation: McKinsey SCQA framework (derived from pyramid principle) use_case: Opening hooks, persuasive narratives, problem-solution content
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
Score
Total Score
Based on repository quality metrics
SKILL.mdファイルが含まれている
ライセンスが設定されている
100文字以上の説明がある
GitHub Stars 100以上
1ヶ月以内に更新
10回以上フォークされている
オープンIssueが50未満
プログラミング言語が設定されている
1つ以上のタグが設定されている
Reviews
Reviews coming soon
