Skip to main content

Abstract Anti-Pattern: Use Case Exposed Design Flaw

Type: Abstract Anti-Pattern (Design Flaw Pattern)
Category: Design Robustness
Severity: HIGH
Status: DOCUMENTED
Version: 1.0.0
Anchored To: BR-010 – RW Doc-Init Detection Bug
Related: E4:S13:T04 – Assess system impacts

Executive Summary​

This document defines and documents an abstract anti-pattern where a valid use case exposes a design flaw in system logic. The pattern demonstrates how legitimate user workflows can reveal weaknesses in design assumptions, even after the flaw is fixed. This knowledge is valuable for:

  1. Design Robustness: Understanding how valid use cases can reveal design weaknesses
  2. Pattern Recognition: Identifying similar design flaws in other systems
  3. Learning: Capturing lessons about edge cases and design assumptions
  4. Prevention: Avoiding similar design flaws in future systems

Key Insight: A valid use case remains relevant even after the bug is fixed, because it represents a pattern that warns about flawed design assumptions.

The Pattern: Use Case Exposed Design Flaw​

Definition​

An abstract anti-pattern is a pattern where:

  • A valid use case (legitimate user workflow) exists
  • The use case exposes a design flaw (bug or weakness in system logic)
  • The flaw is fixed, but the use case remains relevant as knowledge
  • The use case serves as a warning pattern about flawed design assumptions

Characteristics​

  1. Valid Use Case: The workflow is legitimate and should be supported
  2. Design Flaw: The system logic fails to handle the use case correctly
  3. Emergent Discovery: The flaw is discovered through real-world usage, not design review
  4. Knowledge Value: The use case remains valuable even after the fix
  5. Pattern Recognition: The pattern can be applied to identify similar flaws

Concrete Example: RW Doc-Init Detection Bug​

Canonical Reference: BR-010 – RW Doc-Init Detection Bug serves as the authoritative source for this concrete example. This abstract anti-pattern document generalizes the pattern from that bug report.

The Use Case​

Scenario: Story + all task docs created together in story's abstract space (v0.E.S.0+0)

See: BR-010 for complete bug details.

Workflow:

  1. Developer creates a new Story document
  2. Developer creates all Task documents for that Story in the same commit
  3. All documents committed together in story's abstract space (v0.E.S.0+0)
  4. Developer begins implementation work on Task 1
  5. Release Workflow (RW) runs to version the work

Why It's Valid:

  • Efficient workflow (create all task docs at once)
  • Logical grouping (story and its tasks together)
  • Time-saving (single commit for related documentation)
  • Common practice (batch creation of related documents)

The Design Flaw​

Bug: RW doc-init detection logic incorrectly sets BUILD=0 instead of BUILD=1

Root Cause:

  • detect_first_time_est_doc function checked if task doc was created in THIS commit
  • Function checked if prior version exists
  • Flawed Logic: If task doc NOT created in this commit AND no prior version → incorrectly returned is_first_time = True
  • This caused RW to set BUILD=0 (doc-init) instead of BUILD=1 (first functional build)

Why It's a Flaw:

  • Function assumed: "No prior version = doc-init"
  • Missing Check: Function didn't verify if task doc already exists (even if not created in this commit)
  • Design Assumption: Assumed doc-init can only happen when doc is created in current commit
  • Reality: Task doc can exist from previous commit (story's abstract space), but no task-level version exists yet

The Fix​

Solution:

  • Added check: If task document already exists (using locate_task_doc function) → NOT doc-init
  • If task doc exists but wasn't created in this commit → is_first_time = False → BUILD=1
  • Only returns is_first_time = True if task doc is created in THIS commit AND docs-only AND no prior version

Files Updated:

  • packages/frameworks/workflow mgt/scripts/validation/validate_version_bump.py
  • packages/frameworks/workflow mgt/KB/Documentation/Developer_Docs/vwmp/release-workflow-agent-execution.md

Why the Use Case Remains Relevant​

Even though the bug is fixed, the use case is still valuable because:

  1. Pattern Recognition:

    • Demonstrates how valid workflows can expose design assumptions
    • Shows the importance of checking for existing state, not just creation state
    • Illustrates edge case: documents created in parent context (story) vs. child context (task)

  2. Design Warning:

    • Warns against assuming "no prior version = first time"
    • Highlights need to check for existing artifacts, not just creation events
    • Demonstrates importance of state verification vs. event detection

  3. Learning Value:

    • Teaches about batch creation workflows
    • Shows how parent-child relationships can create versioning edge cases
    • Illustrates the difference between "created in this commit" vs. "already exists"

  4. Prevention:

    • Helps identify similar flaws in other systems
    • Provides pattern for testing edge cases
    • Guides design review to consider batch operations

Abstract Anti-Pattern Taxonomy​

Classification​

Type: Abstract Anti-Pattern (Design Flaw Pattern)
Category: Design Robustness
Subcategory: State Detection Logic
Severity: HIGH
Frequency: Unknown (single documented case, but pattern is generalizable)

Pattern Structure​

  1. Valid Use Case: Legitimate workflow that should be supported
  2. Design Flaw: System logic that fails to handle the use case
  3. Root Cause: Flawed design assumption or missing check
  4. Fix: Correction that addresses the root cause
  5. Knowledge Value: Why the use case remains relevant after the fix

Pattern Recognition Criteria​

An abstract anti-pattern exists when:

  • ✅ A valid use case exists (legitimate workflow)
  • ✅ The use case exposes a design flaw (bug or weakness)
  • ✅ The flaw is fixed, but the use case remains valuable
  • ✅ The use case serves as a warning pattern about design assumptions

Design Flaw Pattern: State Detection Logic​

The Pattern​

Name: State Detection Logic Flaw
Type: Design Flaw Pattern
Category: Logic Design

Description: System logic that determines state based on incomplete information, leading to incorrect assumptions about object lifecycle or existence.

Common Manifestations​

  1. Creation Event Assumption:

    • Flaw: Assumes object doesn't exist if not created in current operation
    • Reality: Object may exist from previous operation
    • Fix: Check for object existence, not just creation event

  2. Version History Assumption:

    • Flaw: Assumes "no prior version = first time"
    • Reality: Object may exist but not have version history yet
    • Fix: Check for object existence AND version history

  3. Parent Context Assumption:

    • Flaw: Assumes child objects don't exist if parent was just created
    • Reality: Child objects may be created in same operation as parent
    • Fix: Check for child object existence independently

Prevention Strategies​

  1. State Verification:

    • Always check for object existence, not just creation events
    • Verify state independently of operation context
    • Don't assume state from parent context

  2. Complete Checks:

    • Check multiple conditions (existence, version, state)
    • Don't rely on single condition for state determination
    • Consider edge cases (batch operations, parent-child relationships)

  3. Design Review:

    • Review logic for assumptions about object lifecycle
    • Test with batch operations and parent-child scenarios
    • Consider valid use cases that might expose flaws

Knowledge Capture Framework​

How to Capture Abstract Anti-Patterns​

  1. Identify the Use Case:

    • Document the valid workflow that exposed the flaw
    • Explain why the workflow is legitimate
    • Describe the user's intent and context

  2. Document the Design Flaw:

    • Describe the bug or weakness
    • Identify the root cause (flawed assumption)
    • Explain why the logic failed

  3. Record the Fix:

    • Document the solution
    • Explain how it addresses the root cause
    • Note any files or systems affected

  4. Capture the Knowledge Value:

    • Explain why the use case remains relevant
    • Identify the pattern or warning it represents
    • Describe how it can prevent similar flaws

  5. Classify the Pattern:

    • Categorize the abstract anti-pattern
    • Identify similar patterns or related flaws
    • Link to other knowledge artifacts

Storage Location​

Recommended Location: docs/knowledge/analysis/abstract-anti-patterns/

File Naming: abstract-anti-pattern-{category}-\{name\}.md

Example: abstract-anti-patterns-state-detection-logic.md

Integration with Persistent Knowledge Base​

Agentic Knowledge Management:

  • Agents can search for abstract anti-patterns when reviewing code
  • Patterns can be used to identify potential design flaws
  • Knowledge can be updated as new examples are discovered

Cursor Integration:

  • Patterns indexed and vectorized for semantic search
  • Agents can reference patterns during code review
  • Knowledge persists across sessions and workspaces
  • State Verification Pattern: Always verify object existence before assuming state
  • Batch Operation Pattern: Consider batch operations when designing state detection
  • Parent-Child Context Pattern: Don't assume child state from parent context
  • Event-Based State Assumption: Assuming state from creation events only
  • Version History Assumption: Assuming "no version = first time"
  • Context Inheritance Assumption: Assuming child state from parent context

Recommendations​

For Designers​

  1. Consider Valid Use Cases:

    • Think about legitimate workflows that might expose flaws
    • Test with batch operations and parent-child scenarios
    • Don't assume single-operation workflows only

  2. Verify State, Don't Assume:

    • Always check for object existence
    • Verify state independently of operation context
    • Don't rely on single condition for state determination

  3. Review for Assumptions:

    • Identify design assumptions in logic
    • Test assumptions with edge cases
    • Consider what valid use cases might break

For Developers​

  1. Document Valid Use Cases:

    • When a bug is found, document the use case that exposed it
    • Explain why the use case is legitimate
    • Capture the pattern for future reference

  2. Capture Knowledge:

    • Don't discard use cases after bugs are fixed
    • Document abstract anti-patterns
    • Share knowledge with team

  3. Learn from Patterns:

    • Use abstract anti-patterns to identify similar flaws
    • Apply pattern recognition to code review
    • Build knowledge base of design warnings

Conclusion​

The Use Case Exposed Design Flaw pattern demonstrates that valid use cases remain valuable even after bugs are fixed. They serve as warning patterns about flawed design assumptions and help prevent similar flaws in the future.

By capturing these patterns as abstract anti-patterns, we build a knowledge base that:

  • Warns about common design flaws
  • Guides design review and testing
  • Helps identify similar issues in other systems
  • Supports agentic knowledge management

This knowledge is persistent and curated, forming part of the agentic library system that makes Cursor smarter and more informed.

Last Updated: 2025-12-18T00:00:00Z
Version: 1.0.0
Status: DOCUMENTED
Canonical Anchor: BR-010 – RW Doc-Init Detection Bug
Related Work: E4:S13:T04 – Assess system impacts