# Cross-Project Technical Pattern Registry

## Purpose

This registry captures recurring technical lessons, workarounds, design choices, and failure modes that appear across Beawit's applications and automation workflows. It exists so agents can recognize when a new task is an instance of a known pattern and apply proven countermeasures instead of rediscovering the problem.

This is the **generalization layer** of the agent continual-learning system:
- **Plasticity**: new patterns are added as they are discovered.
- **Stability**: old patterns are versioned and never silently overwritten.
- **Generalization**: patterns are retrieved by symptom, cause, or affected domain and injected into task context.

## Registry Structure

```
patterns/
├── README.md                  # This file
├── patterns.json              # Machine-readable manifest
├── ollama-structured-output-fallback.md
├── json-escaping-downstream-api.md
├── api-version-deprecation.md
├── pty-device-code-auth.md
├── queue-poll-async-job.md
├── llm-as-parser-fallback.md
├── credential-rotation-recovery.md
├── reverse-proxy-container-binding.md
├── human-approval-risky-publish.md
└── transient-failure-retry.md
```

## Pattern File Template

Every `.md` pattern uses the same sections:

```markdown
# Pattern: <Short Name>

## Symptom
What the agent or user sees when the pattern is active.

## Affected Projects
List of known projects/workflows where this pattern has occurred.

## Root Cause
Why it happens.

## Standard Fix
The proven workaround, safety net, or design choice.

## When to Apply
Trigger conditions for applying this pattern to a new task.

## Verification
How to confirm the fix actually worked.

## Related Patterns
Links to other patterns that often appear together.
```

## How Patterns Are Used

1. **Manual reference** — read the registry before designing a new integration or workflow.
2. **Automatic retrieval** — `architecture/pipeline.js` loads relevant patterns into the context packet based on keyword matching against the task input.
3. **Skill/workflow design** — when a new workaround is applied, propose a new pattern entry if the underlying shape is reusable.

## Feedback Loop: Proposing New Patterns

When an agent applies a workaround or fixes a recurring failure, it should ask: *"is this lesson reusable across projects?"* If yes, run the proposal helper:

```bash
node scripts/utils/propose-pattern.js \
  --task "n8n workflow sends LLM-generated text to LinkedIn" \
  --fix "JSON.stringify the post body and validate with JSON.parse before the HTTP Request node" \
  --projects "linkedin-automation" \
  --symptom "LinkedIn API returns malformed JSON payload errors" \
  --root-cause "LLM output contains unescaped quotes and newlines"
```

The helper:
1. Loads the existing `patterns/patterns.json` manifest.
2. Compares the new lesson against existing patterns using keyword overlap.
3. Proposes either:
   - **An update** to an existing pattern (e.g., add an affected project), or
   - **A new pattern** file + manifest entry.
4. Outputs a preview. By default it is **dry-run only**.
5. If the preview looks right, run the same command with `--apply` to write the files.

After applying, run `node architecture/pipeline.js "sample query"` to verify the new or updated pattern is retrievable.

## Adding or Updating a Pattern Manually

1. Create or edit the `.md` file.
2. Update `patterns.json` with id, tags, related patterns, and affected projects.
3. Run `node architecture/pipeline.js "sample query"` to verify the pattern is retrievable.
4. Update `MEMORY.md` Cross-Project Patterns if the pattern is stable and reusable.