alembic-create

name	alembic-create
description	Submit new Alembic knowledge candidates from Codex. Covers `alembic_submit_knowledge`, required V3 fields, batch rules, and review boundaries.

Alembic Create

Use this skill when the user asks to add knowledge, create a Recipe, save a convention, or when implementation reveals a reusable pattern worth preserving.

Submitted entries become candidates. Users review and publish them later through the Dashboard or an explicit admin workflow.

Tool

Use alembic_submit_knowledge.

For one item:

{
  "items": [
    {
      "title": "Network Client Retry Policy",
      "description": "Use the shared retry helper for idempotent API requests",
      "trigger": "@network-client-retry",
      "language": "typescript",
      "kind": "pattern",
      "category": "Network",
      "knowledgeType": "api-usage",
      "doClause": "Use the shared retry helper for idempotent GET requests",
      "dontClause": "Do not hand-roll retry loops in feature modules",
      "whenClause": "When adding an idempotent API request",
      "coreCode": "await retryRequest(() => client.get(path), { attempts: 3 })",
      "headers": ["import { retryRequest } from '@/network/retry'"],
      "usageGuide": "### When to Use\n- Idempotent GET requests\n\n### When Not to Use\n- Non-idempotent writes\n\n### Steps\n1. Wrap the request in retryRequest.\n2. Keep feature-specific error handling outside the helper.\n\n### Key Points\n- Keep retries centralized.\n- Avoid duplicate timers.",
      "content": {
        "markdown": "The project centralizes retry behavior in retryRequest.",
        "rationale": "Central retry policy keeps feature modules consistent."
      },
      "reasoning": {
        "whyStandard": "Multiple network modules use the same helper.",
        "sources": ["src/network/retry.ts", "src/features/example.ts"],
        "confidence": 0.82
      }
    }
  ]
}

Required V3 Fields

Every candidate should include:

title, description, trigger, language, kind, category, knowledgeType, doClause, dontClause, whenClause, coreCode, headers, usageGuide, content, and reasoning.

Use kind carefully:

kind	Use
rule	A constraint Guard should enforce
pattern	A reusable implementation approach
fact	Architecture or project structure knowledge

Quality Rules

• Create one entry per scenario. Do not merge unrelated patterns.
• Search existing knowledge first to avoid duplicates.
• Include concrete source file paths in reasoning.sources.
• Include complete imports in headers.
• Write usageGuide as structured Markdown sections, not a single paragraph.
• If confidence is low, submit a narrower candidate or ask the user before saving it.

Batch Rules

When passing multiple items, make sure the items are not redundant with each other. If two entries share most of their doClause, coreCode, or trigger intent, merge them or make one a small extension of the other through relations.

Batch submission is stricter than a single entry. If the response reports rejected items, fill the missing fields and retry only the rejected entries.

Boundaries

Do not publish or deprecate Recipes from the default Codex plugin tier. Candidate submission is allowed; lifecycle changes belong to the Dashboard or admin mode.