story-based-framing

name

story-based-framing

description

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 for Pattern Detection

Overview

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.

When to Use This Skill

Use story-based framing when:

• Creating pattern descriptions for LLM agents to identify in any domain
• Documenting anti-patterns, failure modes, or problematic behaviors
• Delegating pattern-finding tasks to sub-agents
• Designing automated detection or review workflows
• Building checklists that need to prioritize distinctive criteria
• Teaching pattern recognition to humans or AI systems

Applies to any domain where patterns need to be detected:

• Software: Code smells, architectural issues, security vulnerabilities
• Business: Process inefficiencies, communication breakdowns, requirement gaps
• Security: Misconfigurations, access control issues, compliance violations
• UX/Design: Dark patterns, accessibility issues, false affordances
• Data: Quality issues, pipeline failures, stale caches
• Medical: Diagnostic patterns, symptom clusters, treatment protocols
• Operations: Incident patterns, resource bottlenecks, failure cascades

Core Narrative Structure

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]

Act 1: The Promise

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:

• Code: "A generic class Container(Generic[T]) promises to preserve type T throughout its operations."
• Business: "The approval workflow promises that all requests are reviewed within 24 hours."
• Security: "The firewall configuration claims to restrict access to authorized IP ranges only."
• UX: "The 'Skip' button appears to offer users a choice to bypass the upsell."

Search Impact: Identifies the most distinctive structural criterion that filters 90% of non-matches immediately.

Act 2: The Betrayal

Reveal where the implementation/reality violates the promise.

Purpose: Show the specific point where correctness breaks down.

Examples across domains:

• Code: "But the constructor accepts content: UnionType instead of content: T, storing a union type rather than the promised generic parameter."
• Business: "But requests from certain departments bypass the approval queue entirely, going straight to completion."
• Security: "But the configuration includes a rule allowing 0.0.0.0/0 that overrides all other restrictions."
• UX: "But clicking 'Skip' actually selects the default upsell option and only skips the payment method selection."

Search Impact: Provides the second most distinctive criterion that narrows remaining candidates to true matches.

Act 3: The Consequences

Describe the observable symptoms that result from the violation.

Purpose: Provide verification criteria that confirm the pattern is present.

Examples across domains:

• Code: "Methods contain isinstance() checks and # type: ignore comments to work around the type mismatch."
• Business: "Teams report inconsistent response times, and audit logs show approval timestamps that don't match reality."
• Security: "Penetration tests successfully access restricted resources from unauthorized networks."
• UX: "Customer complaints increase by 40%, with users reporting 'hidden fees' and 'deceptive checkout flow.'"

Search Impact: Enables agents to validate matches and distinguish true positives from similar-looking but different patterns.

Act 4: The Source

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:

• Code: "Values originate from heterogeneous storage (dict[str, TypeA | TypeB]) where specific type information is lost at the storage boundary."
• Business: "The legacy system integration predates the approval workflow, and 'VIP' customers were grandfathered in without documentation."
• Security: "The 'allow all' rule was added during an emergency incident 2 years ago and never removed."
• UX: "The product team was incentivized on conversion rate, leading to design choices that maximize immediate sales over user trust."

Search Impact: Helps agents understand whether the pattern is isolated or systemic, informing fix strategies.

Narrative Template

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}

Pattern Description Effectiveness Data

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.

Design Principles

Frontload Distinctive Criteria

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):

1. "Has error messages"
2. "Has workarounds"
3. "Violates specification X"

Good ordering (distinctive structure first):

1. "Claims to implement specification X"
2. "But actually violates constraint Y"
3. "Resulting in error messages and workarounds"

Use Causal Language

Connect each act with causal transitions that explain why the next act follows.

Weak transitions:

• "Additionally..." (implies independent facts)
• "Also..." (suggests a list)
• "Furthermore..." (just adds more items)

Strong transitions:

• "Because of this violation..." (shows causation)
• "This forces..." (shows consequence)
• "Which originates from..." (traces root cause)

Provide Domain-Appropriate Examples

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:

• Example 1: Manufacturing process, Product A, Factory 1
• Example 2: Software deployment, Service B, Region 2
• Example 3: Customer onboarding, User C, Channel 3

This prevents agents from searching for literal names instead of structural patterns.

Make It Memorable

Choose pattern names that evoke the core problem, appropriate to the domain:

• Code: "The Fake Generic", "The Type Eraser", "The Mutable Default"
• Business: "The Phantom Requirement", "The Meeting Creep", "The Priority Inversion"
• Security: "The Open Backdoor", "The Privileged Escalation", "The Stale Credential"
• UX: "The Dark Pattern", "The False Affordance", "The Frustration Loop"

Comparison with Other Approaches

vs. Checklists

Checklist: "□ Violates spec □ Has workarounds □ Causes errors"

• Problem: Flat structure with no priority guidance
• Result: Agent must validate each item sequentially (7 steps)

Story: "Promise: Implements spec X → Betrayal: Violates constraint Y"

• Advantage: Clear hierarchy, distinctive criteria first
• Result: Fast elimination of non-matches (3 steps)

vs. Formal Specifications

Formal: "∃ system S such that: S claims property P and ∀ inputs I: S violates P(I)"

• Problem: Notation overhead slows pattern recognition
• Result: Requires translation from symbols to reality (7 steps)

Story: "System promises property P but violates it under condition I"

• Advantage: Direct mapping to observable behavior
• Result: Immediate recognition (3 steps)

vs. Symptom-Based (Red Flags)

Symptom: "Red Flag #1: Errors occur, Red Flag #2: Workarounds exist, Red Flag #3: Users complain"

• Problem: Describes effects, not causes; many symptoms overlap across different patterns
• Result: Each flag requires separate validation (10 steps)

Story: "Promise violation causes errors and workarounds because..."

• Advantage: Shows causal chain from root cause to symptoms
• Result: Faster validation through understanding (3 steps)

Practical Usage

Pattern Detection Workflow

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

For Automated Detection

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.

For Documentation

When documenting anti-patterns or failure modes:

1. Use the narrative template from assets/narrative_template.md
2. Fill in domain-specific examples
3. Include the fix as Act 5 (optional)
4. Store in appropriate documentation location

For Sub-Agent Delegation

When 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.
    """
)

Advanced Techniques

Multi-Pattern Stories

For related patterns, create a shared narrative universe:

Pattern Family: "Communication Breakdown"

• Pattern 1: "The Missing Context" (information promised but not delivered)
• Pattern 2: "The Assumed Knowledge" (sender assumes receiver knows background)
• Pattern 3: "The Delayed Feedback" (response promised quickly but arrives late)

Each uses similar four-act structure but different specific betrayals.

Nested Narratives

For complex patterns with sub-patterns:

Main Story: "The Broken Promise"

• Sub-Story A: "Promise breaks due to configuration error"
• Sub-Story B: "Promise breaks due to integration issue"
• Sub-Story C: "Promise breaks due to resource constraint"

Comparative Narratives

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.

Domain-Specific Use Cases

Code Analysis

Complete use case with experimental validation, pattern examples, and practical applications.

See: resources/code-analysis/ directory for:

• experiment_results.md - 70% efficiency improvement validation
• example_patterns.md - Fully-worked code pattern examples
• practical_guide.md - How to apply to linting, reviews, refactoring

Business Process Analysis

[Create similar use case directory when needed]

Security Auditing

[Create similar use case directory when needed]

UX/Design Review

[Create similar use case directory when needed]

Resources

assets/

• narrative_template.md - Blank template for creating new pattern descriptions
• narrative_structure.txt - Four-act structure with guidance for each section

resources/code-analysis/

• Complete use case for software code analysis with experimental validation

Future Resources

Additional domain-specific use cases can be added as needed to demonstrate versatility across domains.