Recovery Strategies for Pattern Development

CRITICAL: Don't spin your wheels when stuck. Follow this escalation path AGGRESSIVELY.

When encountering any difficulty with pattern development - whether it's TypeScript errors, unexpected behavior, or uncertainty about framework features - immediately begin this recovery sequence. Do NOT:

• Continue trying the same approach repeatedly
• Guess at solutions without checking documentation
• Waste time in unproductive loops

If you find yourself stuck for more than 2-3 attempts, MOVE TO THE NEXT STEP.

Use this escalation path:

Step 1: Re-read Documentation (First Response to Being Stuck)

ALWAYS start here when encountering pattern development issues:

"Use the pattern-dev skill to refresh your understanding of framework patterns"

The pattern-dev skill reads all latest pattern documentation from labs. Pay particular attention to:

• ~/Code/labs/docs/common/DEBUGGING.md - Common pitfalls and anti-patterns
  • Quick error reference table
  • Type errors (Cell<>, OpaqueRef<>, etc.)
  • Style errors (object vs string syntax)
  • Reactivity issues (bidirectional binding, computed(), ifElse())
  • Runtime errors (DOM access, LLM in handlers, etc.)
• ~/Code/labs/docs/common/PATTERNS.md - Pattern examples and best practices
• ~/Code/labs/docs/common/CELLS_AND_REACTIVITY.md - Reactivity system details
• ~/Code/labs/docs/common/TYPES_AND_SCHEMAS.md - Type system rules

When to use:

• Encountering any TypeScript errors
• Pattern compiles but doesn't work as expected
• UI not updating reactively
• Confused about Cell<>, OpaqueRef<>, bidirectional binding
• Before asking user for clarification on framework behavior

When to move to Step 2:

• After reading relevant docs but still unclear on solution
• Error persists after applying documented fixes
• Need to see concrete examples of working code
• After 1-2 attempts based on documentation

Step 2: Study Similar Working Patterns

After refreshing documentation, look at existing working patterns in this priority order:

1. Labs patterns (highest priority - canonical examples):

$PARENT_DIR/labs/packages/patterns/
# These are the most up-to-date, authoritative examples
# If a pattern exists here, it's the gold standard

2. Patterns repository (if available - well-tested real-world examples):

$PARENT_DIR/patterns/
# These are well-tested real-world patterns
# Skip this if patterns repo not cloned

3. Community patterns - examples (curated examples):

patterns/examples/
# These are specifically chosen as good examples

4. Community patterns - jkomoros (user patterns):

patterns/jkomoros/
# Prefer root-level (stable) over WIP/
# These may be more complex/experimental

Within each directory:

• ✅ Prefer non-WIP patterns (stable, tested)
• ⚠️ Use WIP/ patterns only if non-WIP doesn't exist
• 📁 Check root level first, then WIP/ as fallback

How to find similar patterns:

# Get parent directory for relative paths
PARENT_DIR="$(git rev-parse --show-toplevel)/.."

# Search for patterns using specific features
grep -r "generateObject" $PARENT_DIR/labs/packages/patterns/
grep -r "computed(" patterns/examples/
grep -r "handler<" $PARENT_DIR/labs/packages/patterns/

# List available patterns
ls $PARENT_DIR/labs/packages/patterns/
ls $PARENT_DIR/patterns/ 2>/dev/null || echo "patterns repo not cloned"
ls patterns/examples/
ls patterns/jkomoros/

When to move to Step 3:

• Can't find similar patterns for your use case
• Examples don't solve your specific problem
• After studying 2-3 similar patterns without clarity
• Ready to try a fresh approach with new knowledge

Step 3: Reset and Try Again (Minor Confusion)

If still stuck after Steps 1-2:

1. Reset to your last commit: git reset --hard HEAD
2. Reflect on what you learned from documentation and examples
3. Try a different approach incorporating that knowledge
4. Start with the simplest possible version that works
5. Add complexity incrementally, testing after each addition

When to move to Step 4:

• After 1-2 reset attempts without progress
• Problem persists despite fresh approaches
• Suspect this might be a framework limitation or bug
• Need architectural guidance beyond documentation

Step 4: Ask User (Significant Confusion)

If Steps 1-3 don't resolve the issue:

1. Explain what you've tried (docs, examples, approaches)
2. Show specific error messages or unexpected behavior
3. Ask user for clarification or guidance
4. Consider if this is a framework limitation vs implementation issue

Additional Resources

After exhausting Steps 1-4, consider:

• Community docs - Check blessed, folk_wisdom, and superstitions for empirical knowledge
• Issue filing - Document complex framework questions for authors (requires user permission)

Remember: This recovery strategy is your safety net. Follow it systematically to avoid spinning your wheels!