---
name: clawql-ouroboros-workflows
description: Run iterative specification-first workflows with ouroboros_* tools, lineage checks, and clear boundaries vs raw infra (kubectl/Helm).
---

# ClawQL ouroboros workflows

## When to apply

- Task requirements are **ambiguous** and need **iterative convergence** over a **Seed** (goal, acceptance criteria, ontology-shaped extraction).
- You want **traceable lineage** (`ouroboros_get_lineage_status`) across generations, not only a one-off answer.

## What the tools **do** and **do not** do

| Tool | Purpose |
|------|---------|
| `ouroboros_create_seed_from_document` | Turn **document text** (or pasted incident report) into a structured **Seed** (`goal`, `acceptance_criteria`, ontology fields, `metadata.seed_id`). |
| `ouroboros_run_evolutionary_loop` | Run **Wonder / Reflect / Execute / Evaluate** cycles on that Seed until `maxGenerations` or convergence. |
| `ouroboros_get_lineage_status` | Read **stored generations** for a `seed_id` (durable if Postgres-backed ouroboros DB is configured). |

**They do not:** call `kubectl`, `helm`, SSH, or the Kubernetes API. The default **Executor** only does meaningful *ClawQL-internal* work when the Seed includes **`brownfield_context.context_references`** entries shaped as **`clawql_execute`** or **`clawql_search`** objects (see `website/src/app/ouroboros/page.mdx` § *Route hints*). If `context_references` is only plain strings (e.g. a document id), execution stays a **stub** (`"No internal tool route selected"`).

So: **Ouroboros = spec / ontology / acceptance iteration + optional OpenAPI-routed execution.** **Infra triage = kubectl, logs, Helm values, cluster events** — run that in parallel or first when failures are scheduler- or container-exit-driven.

## Recommended workflow (skill order)

1. **`ouroboros_create_seed_from_document`** — Set `extractedText` to the **requirements doc**, **design notes**, or a **redacted** paste of `kubectl describe` / `logs` / events if you want a durable *seed* anchored to the incident (not a substitute for reading those logs yourself).
2. **If the task includes validating HTTP/OpenAPI behavior** — add **`context_references`** with **`clawql_search`** / **`clawql_execute`** hints (or extend the seed after step 1) so generations can drive real tool routes.
3. **`ouroboros_run_evolutionary_loop`** — Use a **small `maxGenerations`** first (e.g. 2–6); raise only if convergence is too weak.
4. **`ouroboros_get_lineage_status`** — Inspect `seed_id` for scores, execution blobs, and whether acceptance criteria passed per generation.
5. **Refine** constraints / acceptance criteria / hints and rerun when needed.
6. **`memory_ingest`** — Persist decisions, chart paths, and operator runbooks (no secrets). Link related vault titles via `wikilinks`.

## Hybrid with Kubernetes / Helm (common case)

When the user goal is **“fix the cluster”** (CrashLoop, `Pending`, `Insufficient memory`, chart bugs):

1. **Do not skip** steps 1–4 if the user attached this skill: still **create a seed** from the incident summary so **lineage exists** and acceptance criteria are explicit—even when the next step is mostly `kubectl`.
2. **Run infra investigation in parallel** (or immediately): `kubectl get pods`, `describe`, `logs`, Helm `values.yaml` / templates. The **first root cause** usually lives here.
3. **Use `ouroboros_run_evolutionary_loop`** to **converge on spec-level acceptance** (e.g. “helm template validates”, “documented health checks pass”) **only if** you can express checks via **execute hints** or human-verified criteria; do not expect the loop alone to discover a bad Helm `command:` block.
4. After code or chart changes, **persist** with **`memory_ingest`** (and optional `wikilinks` to related notes such as `[[Helm full Onyx stack Docker Desktop]]`).

## Guardrails

- Keep **acceptance criteria** concrete and testable.
- Separate **shipped behavior** from **roadmap assumptions**.
- **Never** put tokens, kubeconfig blobs, or `OPENSEARCH_ADMIN_PASSWORD`-style values into Seeds or `memory_ingest`.

## Further reading (repo)

- Route hints and sample `ouroboros_run_evolutionary_loop` JSON: `website/src/app/ouroboros/page.mdx`
- Skill overview: `docs/skills/ouroboros.md`
- ADR: `docs/adr/0001-ouroboros-workflow-engine.md`