sf-agent-framework/sf-core/config/reflection-engine.yaml

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# Reflection Engine Configuration
# Version: 1.0.0
# Last Updated: 2025-11-25

version: 1.0.0
framework: sf-agent-framework
feature: reflection-engine

# ═══════════════════════════════════════════════════════════════════════════
# REFLECTION ENGINE SETTINGS
# ═══════════════════════════════════════════════════════════════════════════

reflection_engine:
  enabled: true
  max_iterations: 3
  improvement_threshold: 0.80 # 80% quality score required
  auto_improve: true

  # When to trigger reflection
  reflection_triggers:
    - on-completion # After agent completes work
    - on-error # When errors occur
    - on-user-request # User explicitly requests reflection
    - on-low-quality # When quality score is low

  # Self-correction settings
  self_correction:
    enabled: true
    auto_apply: false # Require user approval for changes
    max_auto_iterations: 2 # Max auto-iterations without approval
    require_approval_below: 0.70 # Require approval if score below 70%

# ═══════════════════════════════════════════════════════════════════════════
# REFLECTION CHECKLIST
# ═══════════════════════════════════════════════════════════════════════════

reflection_checklist:
  # ─────────────────────────────────────────────────────────────────────────
  # CODE QUALITY (25% weight)
  # ─────────────────────────────────────────────────────────────────────────
  code_quality:
    weight: 0.25
    description: "General code quality and maintainability"

    checks:
      follows-coding-standards:
        description: "Code follows naming conventions and formatting standards"
        severity: medium
        auto_fixable: true
        patterns:
          - consistent-naming
          - proper-indentation
          - line-length-limit

      has-appropriate-comments:
        description: "Code has adequate comments and documentation"
        severity: low
        auto_fixable: true
        patterns:
          - class-documentation
          - method-documentation
          - complex-logic-comments

      handles-edge-cases:
        description: "Code handles edge cases and null checks"
        severity: high
        auto_fixable: false
        patterns:
          - null-checks
          - boundary-conditions
          - empty-collection-handling

      includes-error-handling:
        description: "Proper error handling implemented"
        severity: high
        auto_fixable: false
        patterns:
          - try-catch-blocks
          - meaningful-error-messages
          - exception-logging

      no-code-smells:
        description: "No major code smells detected"
        severity: medium
        auto_fixable: false
        smells:
          - duplicated-code
          - long-methods
          - large-classes
          - too-many-parameters

  # ─────────────────────────────────────────────────────────────────────────
  # SALESFORCE BEST PRACTICES (30% weight)
  # ─────────────────────────────────────────────────────────────────────────
  salesforce_best_practices:
    weight: 0.30
    description: "Salesforce-specific best practices and patterns"

    checks:
      bulkified:
        description: "Code is properly bulkified for governor limits"
        severity: critical
        auto_fixable: false
        patterns:
          - no-soql-in-loops
          - no-dml-in-loops
          - collection-processing
          - map-usage-for-lookups

      within-governor-limits:
        description: "Code respects Salesforce governor limits"
        severity: critical
        auto_fixable: false
        limits:
          - max-soql-queries: 100
          - max-dml-statements: 150
          - max-heap-size: 6MB
          - max-cpu-time: 10000ms

      secure-coding:
        description: "Code follows security best practices"
        severity: high
        auto_fixable: false
        patterns:
          - with-security-enforced
          - sharing-keywords
          - input-validation
          - output-encoding
          - no-hardcoded-credentials

      test-coverage-adequate:
        description: "Test coverage is adequate (>75%)"
        severity: high
        auto_fixable: false
        requirements:
          - min-coverage: 75
          - test-classes-exist: true
          - assertions-present: true
          - negative-tests: true

      uses-platform-features:
        description: "Leverages Salesforce platform features appropriately"
        severity: medium
        auto_fixable: false
        patterns:
          - platform-events
          - custom-metadata
          - custom-settings
          - platform-cache

  # ─────────────────────────────────────────────────────────────────────────
  # ARCHITECTURE (25% weight)
  # ─────────────────────────────────────────────────────────────────────────
  architecture:
    weight: 0.25
    description: "Architectural quality and design patterns"

    checks:
      scalable-design:
        description: "Design can scale to large data volumes"
        severity: high
        auto_fixable: false
        considerations:
          - data-volume-handling
          - query-selectivity
          - batch-processing
          - asynchronous-processing

      maintainable:
        description: "Code is maintainable and readable"
        severity: medium
        auto_fixable: true
        patterns:
          - single-responsibility
          - short-methods
          - clear-naming
          - low-complexity

      follows-patterns:
        description: "Follows established Salesforce patterns"
        severity: medium
        auto_fixable: false
        patterns:
          - trigger-handler-pattern
          - service-layer-pattern
          - selector-pattern
          - domain-layer-pattern

      properly-documented:
        description: "Architecture is well documented"
        severity: medium
        auto_fixable: true
        documentation:
          - class-level-docs
          - method-level-docs
          - inline-comments
          - readme-files

      loose-coupling:
        description: "Components are loosely coupled"
        severity: medium
        auto_fixable: false
        patterns:
          - dependency-injection
          - interface-usage
          - event-driven
          - minimal-dependencies

  # ─────────────────────────────────────────────────────────────────────────
  # COMPLETENESS (20% weight)
  # ─────────────────────────────────────────────────────────────────────────
  completeness:
    weight: 0.20
    description: "Work completeness and readiness"

    checks:
      requirements-met:
        description: "All requirements are met"
        severity: critical
        auto_fixable: false
        verification:
          - user-stories-complete
          - acceptance-criteria-met
          - edge-cases-handled

      all-use-cases-covered:
        description: "All use cases are covered"
        severity: high
        auto_fixable: false
        coverage:
          - happy-path
          - error-scenarios
          - edge-cases
          - boundary-conditions

      no-todos-remaining:
        description: "No TODO items remaining in code"
        severity: medium
        auto_fixable: false
        keywords:
          - TODO
          - FIXME
          - HACK
          - XXX

      deployment-ready:
        description: "Code is ready for deployment"
        severity: high
        auto_fixable: false
        requirements:
          - tests-passing
          - documentation-complete
          - no-console-logs
          - no-debug-code

      user-stories-complete:
        description: "All user stories are complete"
        severity: high
        auto_fixable: false
        criteria:
          - definition-of-done-met
          - demo-ready
          - stakeholder-approved

# ═══════════════════════════════════════════════════════════════════════════
# SEVERITY LEVELS
# ═══════════════════════════════════════════════════════════════════════════

severity_levels:
  critical:
    weight: 1.0
    requires_fix: true
    blocks_deployment: true
    color: red

  high:
    weight: 0.75
    requires_fix: true
    blocks_deployment: false
    color: orange

  medium:
    weight: 0.5
    requires_fix: false
    blocks_deployment: false
    color: yellow

  low:
    weight: 0.25
    requires_fix: false
    blocks_deployment: false
    color: blue

# ═══════════════════════════════════════════════════════════════════════════
# IMPROVEMENT STRATEGIES
# ═══════════════════════════════════════════════════════════════════════════

improvement_strategies:
  code_refactoring:
    enabled: true
    max_method_length: 50
    max_class_length: 500
    max_parameters: 5
    max_complexity: 10

  documentation_enhancement:
    enabled: true
    require_class_docs: true
    require_method_docs: true
    require_parameter_docs: true

  test_improvement:
    enabled: true
    min_coverage: 75
    require_assertions: true
    require_negative_tests: true

  security_hardening:
    enabled: true
    enforce_sharing: true
    require_input_validation: true
    require_security_enforced: true

# ═══════════════════════════════════════════════════════════════════════════
# REPORTING
# ═══════════════════════════════════════════════════════════════════════════

reporting:
  generate_reports: true
  report_format: json
  include_suggestions: true
  include_code_samples: true

  metrics_to_track:
    - overall-score
    - category-scores
    - issues-found
    - improvements-applied
    - iterations-needed
    - time-to-quality

# ═══════════════════════════════════════════════════════════════════════════
# INTEGRATION
# ═══════════════════════════════════════════════════════════════════════════

integration:
  workflow_integration:
    enabled: true
    run_after_phases:
      - implementation
      - testing

  agent_integration:
    enabled: true
    agents_with_reflection:
      - sf-developer-lean
      - sf-architect
      - sf-qa-lean
      - sf-admin-lean

  checkpoint_integration:
    enabled: true
    create_checkpoint_before_reflection: true
    allow_rollback: true

# ═══════════════════════════════════════════════════════════════════════════
# CUSTOMIZATION
# ═══════════════════════════════════════════════════════════════════════════

customization:
  allow_custom_checks: true
  custom_checks_directory: .sf-agent/reflection-checks/

  allow_weight_override: true
  weight_overrides_file: .sf-agent/reflection-weights.yaml

  allow_threshold_override: true
  project_specific_thresholds: true