stableclaw 2026.4.6 → 2026.4.8

package/dist/extensions/open-prose/skills/prose/guidance/antipatterns.md

@@ -1,951 +0,0 @@
----
-role: antipatterns
-summary: |
-  Common mistakes and patterns to avoid in OpenProse programs.
-  Read this file to identify and fix problematic code patterns.
-see-also:
-  - prose.md: Execution semantics, how to run programs
-  - compiler.md: Full syntax grammar, validation rules
-  - patterns.md: Recommended design patterns
----
-
-# OpenProse Antipatterns
-
-This document catalogs patterns that lead to brittle, expensive, slow, or unmaintainable programs. Each antipattern includes recognition criteria and remediation guidance.
-
----
-
-## Structural Antipatterns
-
-#### god-session
-
-A single session that tries to do everything. God sessions are hard to debug, impossible to parallelize, and produce inconsistent results.
-
-```prose
-# Bad: One session doing too much
-session """
-  Read all the code in the repository.
-  Identify security vulnerabilities.
-  Find performance bottlenecks.
-  Check for style violations.
-  Generate a comprehensive report.
-  Suggest fixes for each issue.
-  Prioritize by severity.
-  Create a remediation plan.
-"""
-```
-
-**Why it's bad**: The session has no clear completion criteria. It mixes concerns that could be parallelized. Failure anywhere fails everything.
-
-**Fix**: Decompose into focused sessions:
-
-```prose
-# Good: Focused sessions
-parallel:
-  security = session "Identify security vulnerabilities"
-  perf = session "Find performance bottlenecks"
-  style = session "Check for style violations"
-
-session "Synthesize findings and prioritize by severity"
-  context: { security, perf, style }
-
-session "Create remediation plan"
-```
-
-#### sequential-when-parallel
-
-Running independent operations sequentially when they could run concurrently. Wastes wall-clock time.
-
-```prose
-# Bad: Sequential independent work
-let market = session "Research market"
-let tech = session "Research technology"
-let competition = session "Research competition"
-
-session "Synthesize"
-  context: [market, tech, competition]
-```
-
-**Why it's bad**: Total time is sum of all research times. Each session waits for the previous one unnecessarily.
-
-**Fix**: Parallelize independent work:
-
-```prose
-# Good: Parallel independent work
-parallel:
-  market = session "Research market"
-  tech = session "Research technology"
-  competition = session "Research competition"
-
-session "Synthesize"
-  context: { market, tech, competition }
-```
-
-#### spaghetti-context
-
-Context passed haphazardly without clear data flow. Makes programs hard to understand and modify.
-
-```prose
-# Bad: Unclear what context is actually used
-let a = session "Step A"
-let b = session "Step B"
-  context: a
-let c = session "Step C"
-  context: [a, b]
-let d = session "Step D"
-  context: [a, b, c]
-let e = session "Step E"
-  context: [a, c, d]  # Why not b?
-let f = session "Step F"
-  context: [a, b, c, d, e]  # Everything?
-```
-
-**Why it's bad**: Unclear which sessions depend on which outputs. Hard to parallelize or refactor.
-
-**Fix**: Minimize context to actual dependencies:
-
-```prose
-# Good: Clear, minimal dependencies
-let research = session "Research"
-let analysis = session "Analyze"
-  context: research
-let recommendations = session "Recommend"
-  context: analysis  # Only needs analysis, not research
-let report = session "Report"
-  context: recommendations
-```
-
-#### parallel-then-synthesize
-
-Spawning parallel agents for related analytical work, then synthesizing, when a single focused agent could do the entire job more efficiently.
-
-```prose
-# Antipattern: Parallel investigation + synthesis
-parallel:
-  code = session "Analyze code path"
-  logs = session "Analyze logs"
-  context = session "Analyze execution context"
-
-synthesis = session "Synthesize all findings"
-  context: { code, logs, context }
-# 4 LLM calls, coordination overhead, fragmented context
-```
-
-**Why it's bad**: For related analysis that feeds into one conclusion, the coordination overhead and context fragmentation often outweigh parallelism benefits. Each parallel agent sees only part of the picture.
-
-**Fix**: Use a single focused agent with multi-step instructions:
-
-```prose
-# Good: Single comprehensive investigator
-diagnosis = session "Investigate the error"
-  prompt: """Analyze comprehensively:
-  1. Check the code path that produced the error
-  2. Examine logs for timing and state
-  3. Review execution context
-  Synthesize into a unified diagnosis."""
-# 1 LLM call, full context, no coordination
-```
-
-**When parallel IS right**: When analyses are truly independent (security vs performance), when you want diverse perspectives that shouldn't influence each other, or when the work is so large it genuinely benefits from division.
-
-#### copy-paste-workflows
-
-Duplicating session sequences instead of using blocks. Leads to inconsistent changes and maintenance burden.
-
-```prose
-# Bad: Duplicated workflow
-session "Security review of module A"
-session "Performance review of module A"
-session "Synthesize reviews of module A"
-
-session "Security review of module B"
-session "Performance review of module B"
-session "Synthesize reviews of module B"
-
-session "Security review of module C"
-session "Performance review of module C"
-session "Synthesize reviews of module C"
-```
-
-**Why it's bad**: If the workflow needs to change, you must change it everywhere. Easy to miss one.
-
-**Fix**: Extract into a block:
-
-```prose
-# Good: Reusable block
-block review-module(module):
-  parallel:
-    sec = session "Security review of {module}"
-    perf = session "Performance review of {module}"
-  session "Synthesize reviews of {module}"
-    context: { sec, perf }
-
-do review-module("module A")
-do review-module("module B")
-do review-module("module C")
-```
-
----
-
-## Robustness Antipatterns
-
-#### unbounded-loop
-
-A loop without max iterations. Can run forever if the condition is never satisfied.
-
-```prose
-# Bad: No escape hatch
-loop until **the code is perfect**:
-  session "Improve the code"
-```
-
-**Why it's bad**: "Perfect" may never be achieved. The program could run indefinitely, consuming resources.
-
-**Fix**: Always specify `max:`:
-
-```prose
-# Good: Bounded iteration
-loop until **the code is perfect** (max: 10):
-  session "Improve the code"
-```
-
-#### optimistic-execution
-
-Assuming everything will succeed. No error handling for operations that can fail.
-
-```prose
-# Bad: No error handling
-session "Call external API"
-session "Process API response"
-session "Store results in database"
-session "Send notification"
-```
-
-**Why it's bad**: If the API fails, subsequent sessions receive no valid input. Silent corruption.
-
-**Fix**: Handle failures explicitly:
-
-```prose
-# Good: Error handling
-try:
-  let response = session "Call external API"
-    retry: 3
-    backoff: "exponential"
-  session "Process API response"
-    context: response
-catch as err:
-  session "Handle API failure gracefully"
-    context: err
-```
-
-#### ignored-errors
-
-Using `on-fail: "ignore"` when failures actually matter. Masks problems that should surface.
-
-```prose
-# Bad: Ignoring failures that matter
-parallel (on-fail: "ignore"):
-  session "Charge customer credit card"
-  session "Ship the product"
-  session "Send confirmation email"
-
-session "Order complete!"  # But was it really?
-```
-
-**Why it's bad**: The order might be marked complete even if payment failed.
-
-**Fix**: Use appropriate failure policy:
-
-```prose
-# Good: Fail-fast for critical operations
-parallel:  # Default: fail-fast
-  payment = session "Charge customer credit card"
-  inventory = session "Reserve inventory"
-
-# Only ship if both succeeded
-session "Ship the product"
-  context: { payment, inventory }
-
-# Email can fail without blocking
-try:
-  session "Send confirmation email"
-catch:
-  session "Queue email for retry"
-```
-
-#### vague-discretion
-
-Discretion conditions that are ambiguous or unmeasurable.
-
-```prose
-# Bad: What does "good enough" mean?
-loop until **the output is good enough**:
-  session "Improve output"
-
-# Bad: Highly subjective
-if **the user will be happy**:
-  session "Ship it"
-```
-
-**Why it's bad**: The VM has no clear criteria for evaluation. Results are unpredictable.
-
-**Fix**: Provide concrete, evaluatable criteria:
-
-```prose
-# Good: Specific criteria
-loop until **all tests pass and code coverage exceeds 80%** (max: 10):
-  session "Improve test coverage"
-
-# Good: Observable conditions
-if **the response contains valid JSON with all required fields**:
-  session "Process the response"
-```
-
-#### catch-and-swallow
-
-Catching errors without meaningful handling. Hides problems without solving them.
-
-```prose
-# Bad: Silent swallow
-try:
-  session "Critical operation"
-catch:
-  # Nothing here - error disappears
-```
-
-**Why it's bad**: Errors vanish. No recovery, no logging, no visibility.
-
-**Fix**: Handle errors meaningfully:
-
-```prose
-# Good: Meaningful handling
-try:
-  session "Critical operation"
-catch as err:
-  session "Log error for investigation"
-    context: err
-  session "Execute fallback procedure"
-  # Or rethrow if unrecoverable:
-  throw
-```
-
----
-
-## Cost Antipatterns
-
-#### opus-for-everything
-
-Using the most powerful (expensive) model for all tasks, including trivial ones.
-
-```prose
-# Bad: Opus for simple classification
-agent classifier:
-  model: opus
-  prompt: "Categorize items as: spam, not-spam"
-
-# Expensive for a binary classification
-for email in emails:
-  session: classifier
-    prompt: "Classify: {email}"
-```
-
-**Why it's bad**: Opus costs significantly more than haiku. Simple tasks don't benefit from advanced reasoning.
-
-**Fix**: Match model to task complexity:
-
-```prose
-# Good: Haiku for simple tasks
-agent classifier:
-  model: haiku
-  prompt: "Categorize items as: spam, not-spam"
-```
-
-#### context-bloat
-
-Passing excessive context that the session doesn't need.
-
-```prose
-# Bad: Passing everything
-let full_codebase = session "Read entire codebase"
-let all_docs = session "Read all documentation"
-let history = session "Get full git history"
-
-session "Fix the typo in the README"
-  context: [full_codebase, all_docs, history]  # Massive overkill
-```
-
-**Why it's bad**: Large contexts slow processing, increase costs, and can confuse the model with irrelevant information.
-
-**Fix**: Pass minimal relevant context:
-
-```prose
-# Good: Minimal context
-let readme = session "Read the README file"
-
-session "Fix the typo in the README"
-  context: readme
-```
-
-#### unnecessary-iteration
-
-Looping when a single session would suffice.
-
-```prose
-# Bad: Loop for what could be one call
-let items = ["apple", "banana", "cherry"]
-for item in items:
-  session "Describe {item}"
-```
-
-**Why it's bad**: Three sessions when one could handle all items. Session overhead multiplied.
-
-**Fix**: Batch when possible:
-
-```prose
-# Good: Batch processing
-let items = ["apple", "banana", "cherry"]
-session "Describe each of these items: {items}"
-```
-
-#### redundant-computation
-
-Computing the same thing multiple times.
-
-```prose
-# Bad: Redundant research
-session "Research AI safety for security review"
-session "Research AI safety for ethics review"
-session "Research AI safety for compliance review"
-```
-
-**Why it's bad**: Same research done three times with slightly different framing.
-
-**Fix**: Compute once, use many times:
-
-```prose
-# Good: Compute once
-let research = session "Comprehensive research on AI safety"
-
-parallel:
-  session "Security review"
-    context: research
-  session "Ethics review"
-    context: research
-  session "Compliance review"
-    context: research
-```
-
----
-
-## Performance Antipatterns
-
-#### eager-over-computation
-
-Computing everything upfront when only some results might be needed.
-
-```prose
-# Bad: Compute all branches even if only one is needed
-parallel:
-  simple_analysis = session "Simple analysis"
-    model: haiku
-  detailed_analysis = session "Detailed analysis"
-    model: sonnet
-  deep_analysis = session "Deep analysis"
-    model: opus
-
-# Then only use one based on some criterion
-choice **appropriate depth**:
-  option "Simple":
-    session "Use simple"
-      context: simple_analysis
-  option "Detailed":
-    session "Use detailed"
-      context: detailed_analysis
-  option "Deep":
-    session "Use deep"
-      context: deep_analysis
-```
-
-**Why it's bad**: All three analyses run even though only one is used.
-
-**Fix**: Compute lazily:
-
-```prose
-# Good: Only compute what's needed
-let initial = session "Initial assessment"
-  model: haiku
-
-choice **appropriate depth based on initial assessment**:
-  option "Simple":
-    session "Simple analysis"
-      model: haiku
-  option "Detailed":
-    session "Detailed analysis"
-      model: sonnet
-  option "Deep":
-    session "Deep analysis"
-      model: opus
-```
-
-#### over-parallelization
-
-Parallelizing so aggressively that overhead dominates or resources are exhausted.
-
-```prose
-# Bad: 100 parallel sessions
-parallel for item in large_collection:  # 100 items
-  session "Process {item}"
-```
-
-**Why it's bad**: May overwhelm the system. Coordination overhead can exceed parallelism benefits.
-
-**Fix**: Batch or limit concurrency:
-
-```prose
-# Good: Process in batches
-for batch in batches(large_collection, 10):
-  parallel for item in batch:
-    session "Process {item}"
-```
-
-#### premature-parallelization
-
-Parallelizing tiny tasks where sequential would be simpler and fast enough.
-
-```prose
-# Bad: Parallel overkill for simple tasks
-parallel:
-  a = session "Add 2 + 2"
-  b = session "Add 3 + 3"
-  c = session "Add 4 + 4"
-```
-
-**Why it's bad**: Coordination overhead exceeds task time. Sequential would be simpler and possibly faster.
-
-**Fix**: Keep it simple:
-
-```prose
-# Good: Sequential for trivial tasks
-session "Add 2+2, 3+3, and 4+4"
-```
-
-#### synchronous-fire-and-forget
-
-Waiting for operations whose results you don't need.
-
-```prose
-# Bad: Waiting for logging
-session "Do important work"
-session "Log the result"  # Don't need to wait for this
-session "Continue with next important work"
-```
-
-**Why it's bad**: Main workflow blocked by non-critical operation.
-
-**Fix**: Use appropriate patterns for fire-and-forget operations, or batch logging:
-
-```prose
-# Better: Batch non-critical work
-session "Do important work"
-session "Continue with next important work"
-# ... more important work ...
-
-# Log everything at the end or async
-session "Log all operations"
-```
-
----
-
-## Maintainability Antipatterns
-
-#### magic-strings
-
-Hardcoded prompts repeated throughout the program.
-
-```prose
-# Bad: Same prompt in multiple places
-session "You are a helpful assistant. Analyze this code for bugs."
-# ... later ...
-session "You are a helpful assistant. Analyze this code for bugs."
-# ... even later ...
-session "You are a helpful assistent. Analyze this code for bugs."  # Typo!
-```
-
-**Why it's bad**: Inconsistency when updating. Typos go unnoticed.
-
-**Fix**: Use agents:
-
-```prose
-# Good: Single source of truth
-agent code-analyst:
-  model: sonnet
-  prompt: "You are a helpful assistant. Analyze code for bugs."
-
-session: code-analyst
-  prompt: "Analyze the auth module"
-session: code-analyst
-  prompt: "Analyze the payment module"
-```
-
-#### opaque-workflow
-
-No structure or comments indicating what's happening.
-
-```prose
-# Bad: What is this doing?
-let x = session "A"
-let y = session "B"
-  context: x
-parallel:
-  z = session "C"
-    context: y
-  w = session "D"
-session "E"
-  context: [z, w]
-```
-
-**Why it's bad**: Impossible to understand, debug, or modify.
-
-**Fix**: Use meaningful names and structure:
-
-```prose
-# Good: Clear intent
-# Phase 1: Research
-let research = session "Gather background information"
-
-# Phase 2: Analysis
-let analysis = session "Analyze research findings"
-  context: research
-
-# Phase 3: Parallel evaluation
-parallel:
-  technical_eval = session "Technical feasibility assessment"
-    context: analysis
-  business_eval = session "Business viability assessment"
-    context: analysis
-
-# Phase 4: Synthesis
-session "Create final recommendation"
-  context: { technical_eval, business_eval }
-```
-
-#### implicit-dependencies
-
-Relying on conversation history rather than explicit context.
-
-```prose
-# Bad: Implicit state
-session "Set the project name to Acme"
-session "Set the deadline to Friday"
-session "Now create a project plan"  # Hopes previous info is remembered
-```
-
-**Why it's bad**: Relies on VM implementation details. Fragile across refactoring.
-
-**Fix**: Explicit context:
-
-```prose
-# Good: Explicit state
-let config = session "Define project: name=Acme, deadline=Friday"
-
-session "Create a project plan"
-  context: config
-```
-
-#### mixed-concerns-agent
-
-Agents with prompts that cover too many responsibilities.
-
-```prose
-# Bad: Jack of all trades
-agent super-agent:
-  model: opus
-  prompt: """
-    You are an expert in:
-    - Security analysis
-    - Performance optimization
-    - Code review
-    - Documentation
-    - Testing
-    - DevOps
-    - Project management
-    - Customer communication
-    When asked, perform any of these tasks.
-  """
-```
-
-**Why it's bad**: No focus means mediocre results across the board. Can't optimize model choice.
-
-**Fix**: Specialized agents:
-
-```prose
-# Good: Focused expertise
-agent security-expert:
-  model: sonnet
-  prompt: "You are a security analyst. Focus only on security concerns."
-
-agent performance-expert:
-  model: sonnet
-  prompt: "You are a performance engineer. Focus only on optimization."
-
-agent technical-writer:
-  model: haiku
-  prompt: "You write clear technical documentation."
-```
-
----
-
-## Logic Antipatterns
-
-#### infinite-refinement
-
-Loops that can never satisfy their exit condition.
-
-```prose
-# Bad: Perfection is impossible
-loop until **the code has zero bugs**:
-  session "Find and fix bugs"
-```
-
-**Why it's bad**: Zero bugs is unachievable. Loop runs until max (if specified) or forever.
-
-**Fix**: Use achievable conditions:
-
-```prose
-# Good: Achievable condition
-loop until **all known bugs are fixed** (max: 20):
-  session "Find and fix the next bug"
-
-# Or: Diminishing returns
-loop until **no significant bugs found in last iteration** (max: 10):
-  session "Search for bugs"
-```
-
-#### assertion-as-action
-
-Using conditions as actions—checking something without acting on the result.
-
-```prose
-# Bad: Check but don't use result
-session "Check if the system is healthy"
-session "Deploy to production"  # Deploys regardless!
-```
-
-**Why it's bad**: The health check result isn't used. Deploy happens unconditionally.
-
-**Fix**: Use conditional execution:
-
-```prose
-# Good: Act on the check
-let health = session "Check if the system is healthy"
-
-if **system is healthy**:
-  session "Deploy to production"
-else:
-  session "Alert on-call and skip deployment"
-    context: health
-```
-
-#### false-parallelism
-
-Putting sequential-dependent operations in a parallel block.
-
-```prose
-# Bad: These aren't independent!
-parallel:
-  data = session "Fetch data"
-  processed = session "Process the data"  # Needs data!
-    context: data
-  stored = session "Store processed data"  # Needs processed!
-    context: processed
-```
-
-**Why it's bad**: Despite being in parallel, these must run sequentially due to dependencies.
-
-**Fix**: Be honest about dependencies:
-
-```prose
-# Good: Sequential where needed
-let data = session "Fetch data"
-let processed = session "Process the data"
-  context: data
-session "Store processed data"
-  context: processed
-```
-
-#### exception-as-flow-control
-
-Using try/catch for expected conditions rather than exceptional errors.
-
-```prose
-# Bad: Exceptions for normal flow
-try:
-  session "Find the optional config file"
-catch:
-  session "Use default configuration"
-```
-
-**Why it's bad**: Missing config is expected, not exceptional. Obscures actual errors.
-
-**Fix**: Use conditionals for expected cases:
-
-```prose
-# Good: Conditional for expected case
-let config_exists = session "Check if config file exists"
-
-if **config file exists**:
-  session "Load configuration from file"
-else:
-  session "Use default configuration"
-```
-
-#### excessive-user-checkpoints
-
-Prompting the user for decisions that have obvious or predictable answers.
-
-```prose
-# Antipattern: Asking the obvious
-input "Blocking error detected. Investigate?"  # Always yes
-input "Diagnosis complete. Proceed to triage?"  # Always yes
-input "Tests pass. Deploy?"  # Almost always yes
-```
-
-**Why it's bad**: Each checkpoint is a round-trip waiting for user input. If the answer is predictable 90% of the time, you're adding latency for no value.
-
-**Fix**: Auto-proceed for obvious cases, only prompt when genuinely ambiguous:
-
-```prose
-# Good: Auto-proceed with escape hatches for edge cases
-if observation.blocking_error:
-  # Auto-investigate (don't ask - of course we investigate errors)
-  let diagnosis = do investigate(...)
-
-  # Only ask if genuinely ambiguous
-  if diagnosis.confidence == "low":
-    input "Low confidence diagnosis. Proceed anyway?"
-
-  # Auto-deploy if tests pass (but log for audit)
-  if fix.tests_pass:
-    do deploy(...)
-```
-
-**When checkpoints ARE right**: Irreversible actions (production deployments to critical systems), expensive operations (long-running jobs), or genuine decision points where the user's preference isn't predictable.
-
-#### fixed-observation-window
-
-Waiting for a predetermined duration when the signal arrived early.
-
-```prose
-# Antipattern: Fixed window regardless of findings
-loop 30 times (wait: 2s each):  # Always 60 seconds
-  resume: observer
-    prompt: "Keep watching the stream"
-# Runs all 30 iterations even if blocking error detected on iteration 1
-```
-
-**Why it's bad**: Wastes time when the answer is already known. If the observer detected a fatal error at +5 seconds, why wait another 55 seconds?
-
-**Fix**: Use signal-driven exit conditions:
-
-```prose
-# Good: Exit on significant signal
-loop until **blocking error OR completion** (max: 30):
-  resume: observer
-    prompt: "Watch the stream. Signal IMMEDIATELY on blocking errors."
-# Exits as soon as something significant happens
-```
-
-Or use `early_exit` if your runtime supports it:
-
-```prose
-# Good: Explicit early exit
-let observation = session: observer
-  prompt: "Monitor for errors. Signal immediately if found."
-  timeout: 120s
-  early_exit: **blocking_error detected**
-```
-
----
-
-## Security Antipatterns
-
-#### unvalidated-input
-
-Passing external input directly to sessions without validation.
-
-```prose
-# Bad: Direct injection
-let user_input = external_source
-
-session "Execute this command: {user_input}"
-```
-
-**Why it's bad**: User could inject malicious prompts or commands.
-
-**Fix**: Validate and sanitize:
-
-```prose
-# Good: Validate first
-let user_input = external_source
-let validated = session "Validate this input is a safe search query"
-  context: user_input
-
-if **input is valid and safe**:
-  session "Search for: {validated}"
-else:
-  throw "Invalid input rejected"
-```
-
-#### overprivileged-agents
-
-Agents with more permissions than they need.
-
-```prose
-# Bad: Full access for simple task
-agent file-reader:
-  permissions:
-    read: ["**/*"]
-    write: ["**/*"]
-    bash: allow
-    network: allow
-
-session: file-reader
-  prompt: "Read the README.md file"
-```
-
-**Why it's bad**: Task only needs to read one file but has full system access.
-
-**Fix**: Least privilege:
-
-```prose
-# Good: Minimal permissions
-agent file-reader:
-  permissions:
-    read: ["README.md"]
-    write: []
-    bash: deny
-    network: deny
-```
-
----
-
-## Summary
-
-Antipatterns emerge from:
-
-1. **Laziness**: Copy-paste instead of abstraction, implicit instead of explicit
-2. **Over-engineering**: Parallelizing everything, using opus for all tasks
-3. **Under-engineering**: No error handling, unbounded loops, vague conditions
-4. **Unclear thinking**: God sessions, mixed concerns, spaghetti context
-
-When reviewing OpenProse programs, ask:
-
-- Can independent work be parallelized?
-- Are loops bounded?
-- Are errors handled?
-- Is context minimal and explicit?
-- Are models matched to task complexity?
-- Are agents focused and reusable?
-- Would a stranger understand this code?
-
-Fix antipatterns early. They compound over time into unmaintainable systems.