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

> Explore how AIOX pattern capture and Gotcha Registry learning improve workflow intelligence by observing successful commands and preventing repeated errors for smarter suggestions.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: deep-dive
- Published: 2026-03-15

---

**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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/workflow-intelligence/learning/gotcha-registry.js). The registry maintains [`.aiox/gotchas.json`](https://github.com/SynkraAI/aiox-core/blob/main/.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:

```javascript
// 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:

```javascript
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:

```javascript
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`](https://github.com/SynkraAI/aiox-core/blob/main/data/learned-patterns.yaml) via `PatternStore`.
- **Gotcha Registry** indexes critical failures through `QAFeedbackProcessor` and `GotchaRegistry`, maintaining searchable warnings in [`.aiox/gotchas.json`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/data/learned-patterns.yaml) through the `PatternStore` module, while critical failures accumulate in [`.aiox/gotchas.json`](https://github.com/SynkraAI/aiox-core/blob/main/.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.