How AIOX Pattern Capture and Gotcha-Registry Learning System Works: A Deep Dive into Workflow Intelligence

AIOX's learning subsystem combines Pattern Capture to observe and store successful CLI command sequences as reusable workflow patterns, while the Gotcha Registry records critical failures to warn against repeated mistakes, creating a continuous feedback loop that improves suggestions over time.

The SynkraAI/aiox-core repository implements a dual-pipeline learning architecture that transforms raw command execution into actionable workflow intelligence. This pattern capture and gotcha-registry learning system operates through five specialized modules that observe successful agent interactions, validate reusable sequences, and catalog failures to prevent recurrence. Together, these mechanisms enable the platform to evolve its recommendations automatically based on empirical outcomes rather than static rules.

How Pattern Capture Records Successful Workflows

The pattern capture pipeline transforms ephemeral CLI sessions into persistent, reusable workflow patterns through a multi-stage process involving hooks, validation, and intelligent storage.

The Capture Hook and Session Buffering

Every agent command execution flows through onTaskComplete in .aiox-core/workflow-intelligence/learning/capture-hook.js. This hook maintains a per-session buffer (sessionBuffer) that accumulates normalized commands and participating agent IDs. When the system detects a workflow-ending command via _isWorkflowEnd, the complete session buffer transfers to the PatternCapture module for processing.

Pattern Creation and Validation

The PatternCapture class in .aiox-core/workflow-intelligence/learning/pattern-capture.js validates sessions against three criteria: the capture feature must be enabled, the session must represent a successful execution, and the command sequence must exceed the minSequenceLength threshold (default 3 commands). Valid sessions generate pattern objects containing a UUID, the command sequence, participating agents, timestamps, and an inferred workflow label. These patterns undergo schema validation through PatternValidator before acceptance.

Persistent Storage and Pruning

Accepted patterns persist via PatternStore in .aiox-core/workflow-intelligence/learning/pattern-store.js. The save method merges duplicate sequences, increments occurrence counters, updates success rates, and automatically prunes older entries when the store exceeds the maxPatterns limit. The underlying storage resides in data/learned-patterns.yaml, creating a curated catalog that the suggestion engine queries for recommendations.

How the Gotcha Registry Learns from Failures

While pattern capture preserves successes, the gotcha registry prevents repeated failures by indexing critical errors and their contexts.

Detecting Critical Failures

The system routes QA results and execution errors through QAFeedbackProcessor in .aiox-core/workflow-intelligence/learning/qa-feedback.js. This processor analyzes outcomes via _determineOutcome, associating failures with their originating patternId from the execution context. When encountering critical severity failures, the processor triggers gotcha creation rather than simple logging.

Gotcha Creation and Storage

Critical failures invoke _createGotchaFromFailure, which constructs structured gotcha objects containing the problematic pattern, error details, failure reason, suggested alternatives, and searchable keywords. These records store via GotchaRegistry.recordGotcha in .aiox-core/workflow-intelligence/learning/gotcha-registry.js. The registry maintains .aiox/gotchas.json, validating required fields and merging similar entries through _findSimilar while updating occurrence counters and confidence scores. An in-memory keyword index built via _buildIndex enables fast retrieval.

Querying and Retrieval

Before executing commands, consumers invoke GotchaRegistry.queryGotchas(context) with partial patterns, actions, or file lists. The method scores stored entries by keyword overlap, filters results by relevanceThreshold and minConfidence, and returns the top-5 most relevant warnings sorted by relevance multiplied by confidence.

The Feedback Loop Between Success and Failure

These pipelines interact through confidence adjustment mechanisms. When QAFeedbackProcessor detects repeated pattern failures, it invokes _adjustPatternConfidence in PatternStore to degrade the pattern's reliability score. If confidence drops below minConfidenceThreshold, the system automatically deprecates the pattern. Conversely, the suggestion engine prioritizes patterns lacking associated gotchas and maintaining high confidence scores, effectively surfacing proven workflows while suppressing error-prone sequences.

Implementation Examples

Capturing a Workflow Pattern

The following example simulates a session that ends with a workflow-ending command, triggering automatic pattern capture:

// Simulate a session that ends with a workflow‑ending command
const { onTaskComplete } = require('./.aiox-core/workflow-intelligence/learning/capture-hook');

// Run a series of commands
await onTaskComplete('develop', { sessionId: 's1', agentId: '@dev' });
await onTaskComplete('run-tests', { sessionId: 's1' });
await onTaskComplete('create-pr', { sessionId: 's1' });

// The last command triggers capture; the promise resolves with the stored pattern
// {
//   success: true,
//   action: 'stored',
//   patternId: 'c3f9e2a1‑…'
// }

Recording a Gotcha from Critical QA Failure

This example demonstrates how QAFeedbackProcessor creates a gotcha when processing a critical QA result:

const QAFeedbackProcessor = require('./.aiox-core/workflow-intelligence/learning/qa-feedback');
const GotchaRegistry = require('./.aiox-core/workflow-intelligence/learning/gotcha-registry');

// Prepare the learning modules
const patternStore = require('./.aiox-core/workflow-intelligence/learning/pattern-store').createPatternStore();
const gotchaRegistry = new GotchaRegistry();

const feedback = new QAFeedbackProcessor({
  patternStore,
  gotchaRegistry,
});

// Simulated QA result indicating a critical failure
const qaResult = { status: 'failed', severity: 'critical', issues: ['timeout'] };
feedback.processQAResult(qaResult, { patternId: 'c3f9e2a1‑…', storyId: 'WIS-5' });

// The processor creates a gotcha and stores it in .aiox/gotchas.json

Querying Relevant Gotchas Before Execution

Query the registry to retrieve warnings relevant to a planned command sequence:

const gotchaReg = new GotchaRegistry();
gotchaReg.load(); // populate index

const context = {
  pattern: 'develop run-tests create-pr',
  action: 'create-pr',
  files: ['package.json'],
};

const warnings = gotchaReg.queryGotchas(context);
// warnings is an array of up‑to‑5 gotchas sorted by relevance × confidence

Summary

• Pattern Capture observes successful CLI sequences through CaptureHook and onTaskComplete, storing valid workflows exceeding three commands in data/learned-patterns.yaml via PatternStore.
• Gotcha Registry indexes critical failures through QAFeedbackProcessor and GotchaRegistry, maintaining searchable warnings in .aiox/gotchas.json with keyword indexing for fast retrieval.
• Continuous feedback adjusts pattern confidence based on gotcha associations, automatically deprecating unreliable workflows while elevating proven sequences.
• Integration enables the AIOX suggestion engine to recommend high-confidence patterns while preemptively warning against documented failure modes via queryGotchas.

Frequently Asked Questions

What is the minimum sequence length required for pattern capture in AIOX?

AIOX requires sessions to exceed the minSequenceLength configuration, which defaults to 3 commands according to the source code in pattern-capture.js. The PatternCapture module enforces this threshold to ensure stored patterns represent meaningful multi-step workflows rather than trivial single commands.

How does the Gotcha Registry determine if a failure is worth recording?

The QAFeedbackProcessor classifies outcomes via _determineOutcome, creating gotchas only for failures marked with critical severity. The system associates these with specific pattern IDs and stores them through GotchaRegistry.recordGotcha if they meet validation requirements including error details and searchable keywords.

Where does AIOX store learned patterns and recorded gotchas?

Successful patterns persist in data/learned-patterns.yaml through the PatternStore module, while critical failures accumulate in .aiox/gotchas.json via GotchaRegistry. Both storage mechanisms implement merging logic to update existing entries rather than creating duplicates, tracking occurrence counts and confidence metrics for each entry.

How does the system prevent recommendation of error-prone patterns?

The feedback loop connects both pipelines through confidence adjustment. When patterns accumulate gotchas via QAFeedbackProcessor._adjustPatternConfidence, their reliability scores degrade. Patterns falling below minConfidenceThreshold face automatic deprecation, while the suggestion engine prioritizes patterns with high confidence and no associated gotchas during recommendation ranking.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}