@event4u/agent-config 1.26.0 → 1.28.0

package/docs/guidelines/agent-infra/scqa-framework.md

@@ -0,0 +1,526 @@
+---
+external_source: "https://github.com/ginobefun/deep-reading-analyst-skill/tree/26cd7dc9920e025d39751e396e707399022e49ef/src/deep-reading-analyst/references/scqa_framework.md"
+refresh_trigger: "Upstream `ginobefun/deep-reading-analyst-skill` major rewrite of `references/scqa_framework.md` (new element added beyond S-C-Q-A, restructured examples, or SHA pin invalidated by file rename)."
+sunset_criterion: "Replace with a 50-line pointer guideline if (a) the four-element decomposition is fully internalized in `agent-docs-writing` + `requesting-code-review` + `refine-prompt` + `refine-ticket` AND (b) the example library has been rewritten with project-native scenarios."
+adopted_under: "Reference-Guideline Sunset Policy — authoritative-link path. The bulk is reference content (examples ARE the framework); splitting kills the value. Full body adopted with SHA-pinned upstream URL above."
+---
+
+# SCQA Framework (Structure Thinking)
+
+Reference guideline for Wing-1 structured-communication and
+analysis work — McKinsey's S-C-Q-A decomposition for transforming
+complex problems into clear narrative structures. Full-body adopt
+under the **Reference-Guideline Sunset Policy authoritative-link
+path** (see frontmatter `upstream` / `refresh_trigger` keys). The
+reference frontmatter above pins the upstream SHA and names the
+refresh trigger.
+
+Cross-referenced from:
+
+- [`deep-reading-analyst`](../../../.agent-src.uncompressed/skills/deep-reading-analyst/SKILL.md)
+  — Step 2B structural decomposition (always run, all depths).
+- [`agent-docs-writing`](../../../.agent-src.uncompressed/skills/agent-docs-writing/SKILL.md)
+  — narrative structure for module docs and AGENTS.md.
+- [`requesting-code-review`](../../../.agent-src.uncompressed/skills/requesting-code-review/SKILL.md)
+  — PR description structure (S = current state, C = pain point,
+  Q = scope, A = the diff).
+- [`refine-prompt`](../../../.agent-src.uncompressed/skills/refine-prompt/SKILL.md)
+  — reconstruct a free-form prompt into S-C-Q-A acceptance criteria.
+- [`refine-ticket`](../../../.agent-src.uncompressed/skills/refine-ticket/SKILL.md)
+  — Jira / Linear ticket clarification through the four-element lens.
+
+> **The 4 elements:** S (Situation) · C (Complication) · Q (Question)
+> · A (Answer). **Core value:** converting complexity into clarity
+> through narrative structure.
+
+## When to Use
+
+Ideal for:
+- 📊 Understanding article argumentation structure
+- 📝 Organizing complex problem logic
+- 💼 Analyzing business cases
+- 🎯 Evaluating solution reasonableness
+- 📋 Restructuring information for logical flow
+- 🗣️ Preparing presentations or reports
+
+## The Four Elements in Detail
+
+### S - Situation (Context)
+
+**Definition**: Stable, mutually-agreed background facts
+
+#### Identification Method
+```markdown
+## Identifying Situation
+
+Look for "background" descriptions in article:
+- Industry status
+- Historical development
+- Market environment
+- Existing consensus
+- Basic facts
+
+Extraction formula:
+"At [time], [subject] in [field/industry] is in [state]"
+```
+
+#### Quality Situation Characteristics
+- ✅ Objective description, minimal subjective judgment
+- ✅ Generally agreed upon
+- ✅ Sets stage for upcoming complication
+- ✅ Relevant but doesn't delve into details
+
+#### Example
+```markdown
+**Situation**:
+"Over the past decade, remote work technology (video conferencing, collaboration tools) has matured.
+Many knowledge companies began piloting flexible work arrangements pre-pandemic.
+Employee expectations for work flexibility continue rising."
+
+Analysis:
+- ✅ States facts
+- ✅ Neutral description
+- ✅ Establishes discussion scope
+```
+
+### C - Complication (Conflict/Challenge)
+
+**Definition**: Change, problem, or challenge that disrupts balance
+
+#### Identification Method
+```markdown
+## Identifying Complication
+
+Look for "turning point" signal words:
+- But, however, yet
+- The problem is
+- The challenge is
+- Concerningly
+- X situation emerged
+
+Types:
+1. External changes: market, technology, policy shifts
+2. Internal problems: resource shortages, capability gaps
+3. Expectation gaps: expectations vs. reality
+4. Emerging threats: competition, risks
+```
+
+#### Quality Complication Characteristics
+- ✅ Creates tension and urgency
+- ✅ Clarifies "why change is needed"
+- ✅ Contrasts with Situation
+- ✅ Naturally leads to Question
+
+#### Example
+```markdown
+**Complication**:
+"However, sudden widespread remote work exposed many problems:
+- Managers struggle to assess team productivity
+- Employees feel isolated and disconnected
+- Company culture faces dilution risks
+- Cybersecurity threats significantly increased"
+
+Analysis:
+- ✅ Contrasts with Situation
+- ✅ Creates urgency
+- ✅ Specific and tangible
+```
+
+### Q - Question (Core Query)
+
+**Definition**: The central question arising from the complication
+
+#### Identification Method
+```markdown
+## Identifying Question
+
+Explicit questions:
+- Questions article directly poses
+- "How to...?"
+- "Should we...?"
+
+Implicit questions:
+- Derived from S→C logic
+- Questions author wants to answer but doesn't explicitly state
+
+Question types:
+1. Decision question: Should we do A or B?
+2. Method question: How to achieve X?
+3. Cause question: Why does Y happen?
+4. Prediction question: What will happen?
+```
+
+#### Quality Question Characteristics
+- ✅ Directly stems from Complication
+- ✅ Specific and answerable
+- ✅ Valuable to readers
+- ✅ Sets scope for Answer
+
+#### Example
+```markdown
+**Question**:
+"How should companies successfully transition to long-term remote work
+while maintaining productivity?"
+
+Analysis:
+- ✅ Directly addresses C's problems
+- ✅ Specific and actionable
+- ✅ Sets scope (remote work)
+```
+
+### A - Answer (Solution)
+
+**Definition**: The solution or conclusion addressing the Question
+
+#### Identification Method
+```markdown
+## Identifying Answer
+
+Look for:
+- Article's core recommendations
+- Proposed solutions
+- Derived conclusions
+- Action plans
+
+Structure types:
+1. Single solution: "The answer is X"
+2. Multiple steps: "Need to do A, B, C"
+3. Framework tool: "Use Y framework"
+4. Guiding principles: "Follow Z principles"
+```
+
+#### Quality Answer Characteristics
+- ✅ Directly answers Question
+- ✅ Actionable or understandable
+- ✅ Logically supported
+- ✅ Considers implementation feasibility
+
+#### Example
+```markdown
+**Answer**:
+"Successful transition requires four key steps:
+1. Establish clear remote work policies and expectations
+2. Invest in collaboration tech and security infrastructure
+3. Train managers in asynchronous management
+4. Create virtual social and culture-building mechanisms"
+
+Analysis:
+- ✅ Addresses Q's core need
+- ✅ Structured and executable
+- ✅ Covers multiple C problems
+```
+
+## Application Methods
+
+### Method 1: Deconstruction Analysis (Understanding Articles)
+
+```markdown
+# SCQA Deconstruction: [Article Title]
+
+## S - Situation
+[Extract and summarize article's background setup]
+- Key fact 1
+- Key fact 2
+- Key fact 3
+
+## C - Complication
+[Identify problems/challenges article points out]
+- Conflict 1
+- Conflict 2
+- Conflict 3
+
+## Q - Question
+[Clarify or infer article's core question]
+Explicit: [Direct quote]
+Implicit: [Derived from SC]
+
+## A - Answer
+[Summarize article's solution]
+Core solution: [Summary]
+Supporting points: [List]
+
+## 🔍 Assessment
+
+### Logical Completeness
+- S→C: Transition natural?
+- C→Q: Does question stem from complication?
+- Q→A: Does answer address question?
+
+### Quality Scoring
+- S objectivity: [1-5]
+- C urgency: [1-5]
+- Q specificity: [1-5]
+- A feasibility: [1-5]
+
+### Identified Issues
+- [ ] S too subjective
+- [ ] C disconnected from S
+- [ ] Q not explicitly stated
+- [ ] A answers wrong question
+- [ ] Logical leaps
+```
+
+### Method 2: Restructuring (Improving Articles)
+
+```markdown
+# SCQA Restructuring
+
+## Original Structure Problems
+- Issue 1: [e.g., Unclear Situation]
+- Issue 2: [e.g., Jumps to Answer without setup]
+- Issue 3: [e.g., Weak Complication]
+
+## Optimized SCQA
+
+### S - Situation (Improved)
+[Reframe clearer background based on article info]
+
+### C - Complication (Improved)
+[Strengthen conflict, increase urgency]
+
+### Q - Question (Improved)
+[Clarify core question, focus discussion]
+
+### A - Answer (Improved)
+[Structure answer, enhance persuasiveness]
+
+## Improvement Impact
+Before: [Unclear in original]
+After: [Clearer after optimization]
+```
+
+### Method 3: Comparative Analysis (Multiple Articles)
+
+```markdown
+# SCQA Comparison: Topic [X]
+
+## Article 1
+S: [Background]
+C: [Conflict]
+Q: [Question]
+A: [Answer]
+
+## Article 2
+S: [Background]
+C: [Conflict]
+Q: [Question]
+A: [Answer]
+
+## Cross-Analysis
+
+### S Differences
+- Shared understanding: [What both acknowledge]
+- Divergence: [Different perspectives]
+
+### C Differences
+- Article 1 emphasizes: [X problem]
+- Article 2 emphasizes: [Y problem]
+- Insight: Different C leads to different problem framing
+
+### Q Differences
+- Article 1 tries to answer: [...]
+- Article 2 tries to answer: [...]
+- Insight: Question setting determines answer space
+
+### A Differences
+- Solution comparison: [Similarities/differences]
+- Complementarity: [Combinable parts]
+- Conflicts: [Contradictions]
+```
+
+## SCQA Variations
+
+### 1. Standard (S-C-Q-A)
+```
+Stable background → Problem emerges → Question posed → Answer given
+```
+Use for: Problem-oriented articles
+
+### 2. Direct Lead (A-S-C-Q-A)
+```
+State conclusion first → Explain background → Problem → Question → Detailed answer
+```
+Use for: Executive summaries, fast-paced reading
+
+### 3. Suspense (C-S-Q-A)
+```
+Throw out conflict → Explain background → Pose question → Provide answer
+```
+Use for: Attention-grabbing, marketing articles
+
+### 4. Exploratory (S-C-Q-A-Q-A)
+```
+Background → Problem 1 → Answer 1 → Deeper problem 2 → Answer 2
+```
+Use for: Complex problems requiring layered depth
+
+## Practical Example
+
+### Example: Startup Article
+
+**Article Title**: "Why Most Startups Fail"
+
+```markdown
+## SCQA Deconstruction
+
+### S - Situation
+Startup ecosystem has flourished over past 20 years.
+Venture capital abundant, tech infrastructure mature,
+barriers to entry dramatically lowered. Hundreds of thousands of new startups form annually.
+
+### C - Complication
+However, statistics show:
+- 90% of startups fail within 3 years
+- Failure rates rising, not declining
+- Even well-funded companies struggle
+
+"Why are failure rates higher today when conditions are better?"
+
+### Q - Question
+Implicit core question:
+"What fundamental factors cause startup failure?
+How to identify and avoid these fatal mistakes?"
+
+### A - Answer
+Article identifies three fatal issues:
+1. Solving fake needs (42% of failures)
+2. Running out of cash (29%)
+3. Team problems (23%)
+
+With corresponding solutions...
+
+## Assessment
+
+Logical completeness:
+✅ S→C: Sharp contrast, creates suspense
+✅ C→Q: Naturally leads to "why"
+✅ Q→A: Answer highly targeted
+
+Quality scoring:
+- S: 4/5 (objective but could focus more)
+- C: 5/5 (data-driven, creates urgency)
+- Q: 4/5 (implicit question, should state explicitly)
+- A: 4/5 (practical but needs more validation)
+
+Improvement suggestions:
+Explicitly state Q after C, don't let readers guess
+```
+
+## Integration with Other Frameworks
+
+### SCQA + Pyramid Principle
+
+```markdown
+# Structured Expression
+
+SCQA: Set problem framework
+├── S-C-Q: Introduce core question
+└── A: Pyramid structure expansion
+    ├── Point 1
+    │   ├── Support 1.1
+    │   └── Support 1.2
+    ├── Point 2
+    └── Point 3
+```
+
+### SCQA + Critical Thinking
+
+```markdown
+# Deep Analysis
+
+Layer 1: SCQA identifies argument structure
+Layer 2: Critical thinking evaluates each part
+- Is S objective?
+- Is C real?
+- Is Q reasonable?
+- Is A effective?
+```
+
+### SCQA + 5W2H
+
+```markdown
+# Completeness Check
+
+SCQA: Understand overall structure
+5W2H: Check detail completeness
+- Is S's background sufficient (When, Where)?
+- Is C's problem clear (What, Why)?
+- Is A's solution feasible (How, How much, Who)?
+```
+
+## Common Questions
+
+### Q1: What if article lacks obvious SCQA structure?
+
+A: Proactive reconstruction
+```markdown
+Even if article is messy, you can:
+1. Extract information fragments
+2. Categorize into SCQA buckets
+3. Identify missing pieces
+4. Reorganize understanding
+```
+
+### Q2: Hard to distinguish S from C?
+
+A: Key is "stability vs. change"
+```markdown
+S: Stable background, mutually agreed
+C: Change or problem disrupting balance
+
+Test method:
+- If you remove this sentence, does problem still exist?
+  - Yes → Likely C
+  - No → Likely S
+```
+
+### Q3: Article has multiple SCQAs?
+
+A: Layered analysis
+```markdown
+Overall SCQA: Entire article
+Sub-SCQAs: Each section
+
+Example:
+Overall: S-C-Q-A
+└── Section 1: S1-C1-Q1-A1
+└── Section 2: S2-C2-Q2-A2
+```
+
+## Practice Exercises
+
+### Exercise 1: Daily SCQA Deconstruction
+Choose one article, spend 10 minutes identifying SCQA
+
+### Exercise 2: Elevator Pitch
+Use 30 seconds to introduce any topic in SCQA structure:
+- 5 sec: S
+- 10 sec: C
+- 5 sec: Q
+- 10 sec: A
+
+### Exercise 3: Comparative Reading
+For 2-3 articles on same topic, compare SCQA differences
+
+### Exercise 4: Restructure Writing
+Take your own writing, reorganize using SCQA
+
+## Key Quotes
+
+> "Structure creates clarity. Clarity creates impact."
+
+> "Good structure makes complex ideas simple.
+> Bad structure makes simple ideas complex."
+
+> "SCQA doesn't limit creativity—
+> it makes your ideas easier to understand."
+
+---
+
+**Remember**: SCQA is a thinking tool, not a writing formula. Use flexibly to serve clarity and deep understanding.
+
+---
+
+## ADOPT citation
+
+Adopted from [`ginobefun/deep-reading-analyst-skill`](https://github.com/ginobefun/deep-reading-analyst-skill) @ commit `26cd7dc9` · `src/deep-reading-analyst/references/scqa_framework.md` · MIT License.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.26.0",
+    "version": "1.28.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/schemas/skill.schema.json

@@ -42,6 +42,21 @@
       "enum": ["senior"],
       "description": "Optional tier marker. `senior` opts the skill into the Senior-Tier Required Structure check (Context-First lead, Related Skills, Proactive Triggers, Output Artifacts) per .agent-src.uncompressed/rules/skill-quality.md."
     },
+    "external_source": {
+      "type": "string",
+      "format": "uri",
+      "description": "SHA-pinned upstream URL for skills adopted under the Reference-Guideline Sunset Policy split path (skill body links to upstream reference modules). Required together with `refresh_trigger` and `sunset_criterion`."
+    },
+    "refresh_trigger": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Event that mandates a rewrite of this skill (e.g. upstream major rewrite, dispatch table reshape, SHA pin invalidation). Required when `external_source` is set."
+    },
+    "sunset_criterion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Conditions under which the skill should be archived and replaced with a 50-line pointer (e.g. all referenced modules adopted as project-local guidelines, dispatch logic moved to a project-native router). Required when `external_source` is set."
+    },
     "council_depth": {
       "type": "string",
       "enum": ["deep"],