alembic-create

name	alembic-create
description	Submit knowledge to Alembic. Covers single/batch MCP submission, V3 field requirements, quality validation, and lifecycle. Use when user says "submit knowledge / add to KB / create recipe" or agent needs to persist code patterns, rules, or facts.

Alembic Create — Knowledge Submission

Prerequisite: MCP tools return a unified JSON Envelope { success, errorCode?, message?, data?, meta }. Call alembic_health before operations to confirm service availability.

This Skill guides the Agent to submit code patterns, rules, and facts to the Alembic knowledge base. Submitted entries enter Candidates (pending status); users review and publish them via the Dashboard.

Related Skill: alembic-recipes (search existing knowledge).

---

Submission Paths

Path	Tool	Use Case
Single	alembic_submit_knowledge	Agent carefully constructs one complete entry
Batch	alembic_submit_knowledge (items array)	Cold-start dimension analysis, batch scans
Dashboard	Browser http://localhost:3000	User manual paste/file scan

Agent prefers MCP submission — no browser needed.

---

Single Submission — alembic_submit_knowledge

Submit one complete V3 knowledge entry at a time. Even if some fields fail validation, the entry is still stored; the response includes recipeReadyHints indicating missing fields.

V3 Required Fields (16)

Field	Type	Description
title	string	Knowledge title, concise and clear
description	string	One-line purpose description
trigger	string	Trigger keyword, e.g. @NetworkMonitor
language	string	Programming language, e.g. typescript, swift
kind	enum	rule (constraint) / pattern (reusable) / fact (project fact)
category	string	View/Service/Tool/Model/Network/Storage/UI/Utility
knowledgeType	string	Knowledge type identifier
doClause	string	✅ What to do (Channel A+B hard dependency)
dontClause	string	❌ What not to do
whenClause	string	When to apply (Channel B hard dependency)
coreCode	string	Core code snippet
headers	string[]	Complete import statement list
usageGuide	string	Usage guide (Markdown, see format below)
content	object	{ markdown: string, rationale: string } — at minimum provide markdown
reasoning	object	{ whyStandard: string, sources: string[], confidence: number }

Optional Fields

topicHint, complexity (beginner/intermediate/advanced), scope (universal/project-specific/target-specific), tags (string[]), constraints, relations, skipDuplicateCheck (default false)

usageGuide Format Requirements

Must use Markdown sections. Never write as a single long line.

### When to Use
- Scenario A
- Scenario B

### When Not to Use
- Exclusion scenario

### Steps
1. First step
2. Second step

### Key Points
- Note A
- Note B

Optional sections: Dependencies & Prerequisites, Error Handling, Performance & Resources, Security & Compliance, Common Misuse, Alternatives, Related Knowledge.

---

Batch Submission — alembic_submit_knowledge (items array)

Submit multiple entries at once. Each is validated independently; failures are rejected without blocking others.

Parameters

Field	Required	Type	Description
items	✅	object[]	Array of knowledge entries, each following the same field structure as single submission

Response

{
  "count": 3,
  "total": 5,
  "ids": ["id1", "id2", "id3"],
  "errors": ["item[2]: missing doClause"],
  "rejectedItems": [2, 4],
  "rejectedSummary": { "commonMissingFields": ["doClause", "reasoning"] }
}

Batch validation is stricter: single submission stores entries even with validation warnings (with hints), batch submission rejects entries that fail validation.

---

Submission Workflow

Standard Flow (Agent via MCP)

1. Analyze code → construct V3 fields
2. alembic_submit_knowledge → stored as pending
3. Check response:
   - Success → inform user "Submitted. Review in Dashboard Candidates."
   - Has rejectedItems → fill in missing fields per rejectedSummary.commonMissingFields, retry

One Entry Per Scenario

Splitting principle: different use cases, different API endpoints, different configurations → separate entries each. Never merge multiple patterns into one.

Batch Anti-Redundancy Rules (⚠️ MANDATORY)

Items in the array must NOT be cross-redundant:

• No highly overlapping doClause / coreCode / trigger entries within the same batch
• If two entries share 80%+ content, merge into one or split into primary + extends supplementary entries
• Primary entry contains complete core content; supplementary entry contains only the differences, referencing the primary trigger in _relations.extends
• The system only detects fusion between "candidates vs existing DB entries" — it does NOT check intra-batch redundancy — Agent must self-enforce

Example: Two routing knowledge entries (registration flow + dispatch supplement) should be structured as:

1. Primary: Complete route registration pattern (register + open + doc sync)
2. Supplementary: Only deepLink/Modal/Tab stack differences, _relations.extends → primary trigger

---

Post-Submission Management

Need	Tool
Check candidate status	alembic_knowledge(operation=list)
Review/publish	alembic_knowledge_lifecycle(operation=approve/publish/fast_track)
Search existing knowledge to avoid duplicates	alembic_search(mode=context, query=...)

---

Kind Routing & Pipeline Impact

kind	Purpose	Pipeline Output
rule	Coding conventions, constraints	→ Channel A (.mdc rule files)
pattern	Code patterns, usage	→ Channel B (.mdc pattern files + Snippet)
fact	Project facts, architecture decisions	→ Search/Guard context, no direct file output

doClause is a hard dependency for Channel A+B — missing this field means .mdc files cannot be generated at all.

---

Example: Submit One Entry

{
  "title": "Network Monitor — Connectivity Listener",
  "description": "Monitor network connectivity changes using NWPathMonitor",
  "trigger": "@NetworkMonitor",
  "language": "swift",
  "kind": "pattern",
  "category": "Network",
  "knowledgeType": "api-usage",
  "doClause": "Use NWPathMonitor to observe network status changes; dispatch UI updates to the main queue",
  "dontClause": "Do not use the deprecated Reachability library; do not update UI directly on background threads",
  "whenClause": "When the app needs real-time network connectivity awareness",
  "coreCode": "let monitor = NWPathMonitor()\nmonitor.pathUpdateHandler = { path in\n  DispatchQueue.main.async {\n    self.isConnected = path.status == .satisfied\n  }\n}\nmonitor.start(queue: DispatchQueue.global())",
  "headers": ["import Network"],
  "usageGuide": "### When to Use\n- App needs real-time network status\n- Initialize once at launch\n\n### Key Points\n- Access via singleton sharedMonitor\n- start() begins monitoring, cancel() stops\n- Callback runs on global queue; switch to main thread for UI updates",
  "content": {
    "markdown": "NWPathMonitor is the recommended network status monitoring API for iOS 12+, replacing deprecated Reachability.",
    "rationale": "Apple-recommended, thread-safe, supports cellular/WiFi/wired detection."
  },
  "reasoning": {
    "whyStandard": "Apple Developer Documentation recommended approach, replacing SCNetworkReachability",
    "sources": ["Apple Developer Documentation - NWPathMonitor"],
    "confidence": 0.95
  }
}