This skill should be used when describing patterns or anti-patterns for detection by LLM agents across any domain (code analysis, business processes, security audits, UX design, data quality, medical diagnosis, etc.). Uses narrative storytelling structure ("The Promise" → "The Betrayal" → "The Consequences" → "The Source") to achieve 70% faster pattern identification compared to checklist or formal specification approaches. Triggers when creating pattern descriptions for any systematic analysis, detection tasks, or when delegating pattern-finding to sub-agents.
Story-based framing uses narrative structure to describe patterns and anti-patterns across any domain, enabling LLM agents to identify them 70% faster than traditional approaches (checklists, formal specifications, or symptom-based descriptions). Experimental evidence from code analysis shows narrative descriptions requiring only 3 search steps versus 10 steps for refactoring-style descriptions.
The technique structures pattern descriptions as a causal story that mirrors the investigation thought process, frontloading the most distinctive criteria to eliminate false positives early. This approach is domain-independent - it works for code analysis, business process audits, security reviews, UX analysis, data quality checks, medical diagnosis, and any systematic pattern detection task.
Use story-based framing when:
Applies to any domain where patterns need to be detected:
Story-based pattern descriptions follow a four-act structure that establishes causal relationships:
flowchart TD
Start([Pattern Detection Task]) --> Act1[Act 1: The Promise<br/>What the system claims to do<br/>or appears correct]
Act1 --> Act2[Act 2: The Betrayal<br/>Where reality violates the promise]
Act2 --> Act3[Act 3: The Consequences<br/>Observable symptoms from violation]
Act3 --> Act4[Act 4: The Source<br/>Root cause explanation]
Act4 --> Fix[The Fix<br/>Resolution approach]
Fix --> End([Pattern Documented])
Act1 -.->|Filters 90% non-matches| Search1[Search Impact: Most distinctive criterion]
Act2 -.->|Narrows to true matches| Search2[Search Impact: Second distinctive criterion]
Act3 -.->|Validates matches| Search3[Search Impact: Verification criteria]
Act4 -.->|Informs fixes| Search4[Search Impact: Understand if isolated or systemic]
Describe what the system/process/code claims to do or appears to implement correctly at first glance.
Purpose: Establish the initial correct-looking state that creates false confidence.
Examples across domains:
Container(Generic[T]) promises to preserve type T throughout its operations."Search Impact: Identifies the most distinctive structural criterion that filters 90% of non-matches immediately.
Reveal where the implementation/reality violates the promise.
Purpose: Show the specific point where correctness breaks down.
Examples across domains:
content: UnionType instead of content: T, storing a union type rather than the promised generic parameter."Search Impact: Provides the second most distinctive criterion that narrows remaining candidates to true matches.
Describe the observable symptoms that result from the violation.
Purpose: Provide verification criteria that confirm the pattern is present.
Examples across domains:
isinstance() checks and # type: ignore comments to work around the type mismatch."Search Impact: Enables agents to validate matches and distinguish true positives from similar-looking but different patterns.
Explain why the pattern exists - the root cause or architectural decision that led to this.
Purpose: Provide context that explains origin and suggests fixes.
Examples across domains:
dict[str, TypeA | TypeB]) where specific type information is lost at the storage boundary."Search Impact: Helps agents understand whether the pattern is isolated or systemic, informing fix strategies.
Use this template when creating pattern descriptions for any domain:
# Pattern: {Memorable Descriptive Name}
## The Story
### Act 1: The Promise
{What the system/process/code claims to do or appears to implement correctly}
**Observable characteristics**: {What you would see that makes this look correct initially}
### Act 2: The Betrayal
{Where the reality violates the promise}
**The breaking point**: {Specific moment/location/condition where correctness fails}
### Act 3: The Consequences
{Observable symptoms that result from the violation}
**Symptoms**:
- {Symptom 1}
- {Symptom 2}
- {Symptom 3}
### Act 4: The Source
{Why the pattern exists - root cause}
**Origin**: {Architectural decision, legacy constraint, incentive misalignment, etc.}
## The Fix
{Brief description of the correct solution}
**Resolution approach**: {How to address the root cause}
Experimental validation from code analysis domain (see resources/code-analysis/experiment_results.md):
| Style | Steps | Efficiency | | --------------------------- | ----- | ---------------------- | | Narrative (story-based) | 3 | ⭐⭐⭐⭐⭐ Best (100%) | | XML structured | 4 | ⭐⭐⭐⭐ (80%) | | Checklist | 7 | ⭐⭐⭐ (43%) | | Formal mathematical | 7 | ⭐⭐⭐ (43%) | | Refactoring (symptom-based) | 10 | ⭐⭐ Slowest (30%) |
Key Insight: Narrative framing provides causal flow that matches investigation intuition, while symptom-based approaches require validating each "red flag" separately. This finding is domain-independent - the cognitive benefit of causal storytelling applies to any pattern detection task.
Place the most unique, identifying characteristics in Act 1 and Act 2. These should eliminate 90%+ of false positives immediately.
Poor ordering (generic symptoms first):
Good ordering (distinctive structure first):
Connect each act with causal transitions that explain why the next act follows.
Weak transitions:
Strong transitions:
Include realistic examples for the target domain, using varied names/scenarios to avoid agents matching on specific identifiers.
Vary details across examples to ensure structural pattern matching:
This prevents agents from searching for literal names instead of structural patterns.
Choose pattern names that evoke the core problem, appropriate to the domain:
Checklist: "□ Violates spec □ Has workarounds □ Causes errors"
Story: "Promise: Implements spec X → Betrayal: Violates constraint Y"
Formal: "∃ system S such that: S claims property P and ∀ inputs I: S violates P(I)"
Story: "System promises property P but violates it under condition I"
Symptom: "Red Flag #1: Errors occur, Red Flag #2: Workarounds exist, Red Flag #3: Users complain"
Story: "Promise violation causes errors and workarounds because..."
flowchart TD
Start([Receive Detection Task]) --> Check1{Does candidate match<br/>Act 1: The Promise?}
Check1 -->|No - 90% filtered| Reject1[Discard as non-match]
Check1 -->|Yes| Check2{Does candidate show<br/>Act 2: The Betrayal?}
Check2 -->|No| Reject2[Discard as false positive]
Check2 -->|Yes| Check3{Are symptoms from<br/>Act 3: The Consequences<br/>present?}
Check3 -->|No| Reject3[Discard - similar but different pattern]
Check3 -->|Yes| Validate[Validate: Does Act 4: The Source<br/>explain the root cause?]
Validate -->|Yes| Report[Report Match with Evidence]
Validate -->|No| Investigate[Further Investigation Needed]
Report --> End([Pattern Instance Documented])
Investigate --> End
Reject1 --> End
Reject2 --> End
Reject3 --> End
style Check1 fill:#e1f5ff
style Check2 fill:#fff4e1
style Check3 fill:#ffe1e1
style Validate fill:#e1ffe1
style Report fill:#90EE90
When creating prompts for LLM-based detection agents:
Search for instances of "{Pattern Name}" in {domain}:
**The Promise**: {What appears correct initially} **The Betrayal**: {Where reality violates the promise} **The Consequences**: {Observable symptoms} **The Source**: {Why this exists}
Report: {identifier}, {location}, evidence for each act.
When documenting anti-patterns or failure modes:
assets/narrative_template.mdWhen delegating pattern-finding tasks to sub-agents:
Task(
subagent_type="Explore",
description="Find {pattern name} in {domain}",
prompt="""
Locate instances matching this pattern:
Act 1 (The Promise): {What should be true}
Act 2 (The Betrayal): {What actually happens}
Act 3 (The Consequences): {Observable symptoms}
Act 4 (The Source): {Why this exists}
Report all matches with evidence.
"""
)
For related patterns, create a shared narrative universe:
Pattern Family: "Communication Breakdown"
Each uses similar four-act structure but different specific betrayals.
For complex patterns with sub-patterns:
Main Story: "The Broken Promise"
For patterns with subtle differences:
Pattern A: "The False Promise" (claims X but delivers Y) Pattern B: "The Partial Promise" (claims X and delivers some X but not all)
Key Difference: Act 2 betrayal point - complete violation vs. partial delivery.
Complete use case with experimental validation, pattern examples, and practical applications.
See: resources/code-analysis/ directory for:
experiment_results.md - 70% efficiency improvement validationexample_patterns.md - Fully-worked code pattern examplespractical_guide.md - How to apply to linting, reviews, refactoring[Create similar use case directory when needed]
[Create similar use case directory when needed]
[Create similar use case directory when needed]
narrative_template.md - Blank template for creating new pattern descriptionsnarrative_structure.txt - Four-act structure with guidance for each sectionAdditional domain-specific use cases can be added as needed to demonstrate versatility across domains.
npx skills add BbgnsurfTech/story-based-framing下载完整 Skill 目录，包含 SKILL.md 及所有相关文件
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer