@dug-21/unimatrix 0.5.5

package/skills/knowledge-lookup/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: "knowledge-lookup"
+description: "Deterministic lookup of Unimatrix knowledge by exact filters. Use when you know what you want — a specific feature, category, entry ID, or status."
+---
+
+# Knowledge Lookup — Deterministic Query Against Unimatrix
+
+## What This Skill Does
+
+Retrieves Unimatrix entries by exact filters — topic, category, tags, status, or entry ID. Returns all matching entries without semantic ranking. Use when you know precisely what you're looking for.
+
+**Use this when you KNOW what you want** — a specific feature's ADRs, entries with a particular status, or a known entry by ID.
+
+---
+
+## How to Look Up
+
+Call the `mcp__unimatrix__context_lookup` MCP tool:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `topic` | No* | Exact feature ID match (e.g., `"nxs-001"`) |
+| `category` | No* | Exact category match (e.g., `"decision"`) |
+| `tags` | No* | All specified tags must match |
+| `status` | No | `"active"` (default), `"deprecated"`, `"proposed"` |
+| `id` | No* | Specific entry ID (returns exactly one entry) |
+| `limit` | No | Max results (default: 10) |
+| `format` | No | `"summary"` (default), `"markdown"` (full content), `"json"` |
+| `agent_id` | No | Your role name (e.g. `uni-architect`) |
+
+*At least one filter parameter is required (topic, category, tags, or id).
+
+### Examples
+
+**Get all ADRs for a specific feature:**
+```
+mcp__unimatrix__context_lookup(topic: "nxs-002", category: "decision")
+```
+
+**Get a specific entry by ID (full content):**
+```
+mcp__unimatrix__context_lookup(id: 42, format: "markdown")
+```
+
+**Find all deprecated decisions:**
+```
+mcp__unimatrix__context_lookup(category: "decision", status: "deprecated")
+```
+
+**Find entries tagged with a specific domain:**
+```
+mcp__unimatrix__context_lookup(category: "decision", tags: ["adr", "serialization"])
+```
+
+**Get all knowledge for a feature (any category):**
+```
+mcp__unimatrix__context_lookup(topic: "vnc-001")
+```
+
+---
+
+## Single Entry Retrieval
+
+If you already have an entry ID (from a prior search or lookup result), use `context_get` for direct retrieval:
+
+```
+mcp__unimatrix__context_get(id: 42, format: "markdown")
+```
+
+This is faster than a lookup with an ID filter and always returns full content.
+
+---
+
+## When to Use This vs /knowledge-search
+
+| Use `/knowledge-lookup` when | Use `/knowledge-search` when |
+|------------------------------|------------------------------|
+| You know the exact feature/category | Exploring a concept |
+| "Give me all ADRs for nxs-002" | "What do we know about X?" |
+| Retrieving a specific entry by ID | Finding related decisions |
+| Filtering by exact status or tags | Discovering unknown patterns |
+| Checking what exists before storing | Broad exploration |
+
+---
+
+## Common Workflows
+
+**Before writing a new ADR (architect):**
+```
+1. mcp__unimatrix__context_lookup(topic: "{feature-id}", category: "decision")
+   → See what ADRs already exist for this feature
+2. mcp__unimatrix__context_lookup(category: "decision", tags: ["adr", "{domain}"])
+   → See ADRs across features in the same domain
+```
+
+**Before implementing a component (developer):**
+```
+1. mcp__unimatrix__context_lookup(topic: "{feature-id}", category: "decision", format: "markdown")
+   → Read all architectural decisions for this feature
+```
+
+**Checking for deprecated knowledge:**
+```
+mcp__unimatrix__context_lookup(category: "decision", status: "deprecated", topic: "{feature-id}")
+→ See what decisions have been superseded
+```
+
+---
+
+## When You Find Stale or Wrong Knowledge
+
+Lookup may surface entries that are outdated or incorrect. Fix them:
+
+| Situation | Action |
+|-----------|--------|
+| Entry is **wrong** | `mcp__unimatrix__context_correct(original_id: {id}, content: "{corrected version}", reason: "{why}")` — supersedes with chain link |
+| Entry is **outdated** | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why}")` |
+| Entry is **suspicious** | `mcp__unimatrix__context_quarantine(id: {id}, reason: "{concern}")` — Admin only |
+
+Every agent shares responsibility for knowledge quality. Don't leave wrong entries for the next agent to trip over.

package/skills/knowledge-search/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: "knowledge-search"
+description: "Semantic search across Unimatrix knowledge. Use when exploring a topic, looking for related decisions, patterns, or conventions."
+---
+
+# Knowledge Search — Semantic Query Against Unimatrix
+
+## What This Skill Does
+
+Searches Unimatrix for knowledge entries using natural language. Returns results ranked by semantic similarity. Use when you need to explore what's known about a concept, find related decisions, or discover relevant patterns.
+
+**Use this when you DON'T know exactly what you're looking for** — you have a concept or question, not a specific entry.
+
+---
+
+## How to Search
+
+Call the `mcp__unimatrix__context_search` MCP tool:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `query` | Yes | Natural language search query |
+| `category` | No | Filter to a specific category |
+| `topic` | No | Filter to a specific feature ID |
+| `tags` | No | Filter by tags (all must match) |
+| `k` | No | Max results (default: 5) |
+| `format` | No | `"summary"` (default), `"markdown"` (full content), `"json"` |
+| `agent_id` | No | Your role name (e.g. `uni-architect`) |
+
+### Examples
+
+**Find ADRs about error handling across all features:**
+```
+mcp__unimatrix__context_search(query: "error handling strategy", category: "decision")
+```
+
+**Find anything related to MCP transport:**
+```
+mcp__unimatrix__context_search(query: "MCP transport stdio protocol")
+```
+
+**Find conventions about testing in a specific feature:**
+```
+mcp__unimatrix__context_search(query: "test patterns integration", topic: "nxs-001")
+```
+
+**Get full content instead of summaries:**
+```
+mcp__unimatrix__context_search(query: "serialization approach", format: "markdown")
+```
+
+---
+
+## Available Categories
+
+| Category | Contains |
+|----------|----------|
+| `decision` | Architectural Decision Records (ADRs) |
+| `convention` | Coding and process conventions |
+| `pattern` | Reusable implementation patterns |
+| `procedure` | Step-by-step processes |
+| `outcome` | Results and outcomes |
+| `lesson-learned` | Retrospectives and process learnings |
+| `reference` | General reference material |
+| `duties` | Role duties for context briefing |
+
+Omit `category` to search across all categories.
+
+---
+
+## Interpreting Results
+
+**Summary format** (default): Returns title, topic, category, tags, and a brief content preview for each match. Use this for scanning and triage.
+
+**Markdown format**: Returns full content for each match. Use this when you need the complete text of matching entries.
+
+**JSON format**: Returns structured data. Use for programmatic processing.
+
+---
+
+## When to Use This vs /knowledge-lookup
+
+| Use `/knowledge-search` when | Use `/knowledge-lookup` when |
+|------------------------------|------------------------------|
+| Exploring a concept | You know the exact feature/category |
+| "What do we know about X?" | "Give me all ADRs for nxs-002" |
+| Finding related decisions | Retrieving a specific entry by ID |
+| Discovering patterns you didn't know existed | Filtering by exact status or tags |
+
+---
+
+## Getting Full Content
+
+Search returns summaries by default. To read the full content of a specific result:
+
+1. Note the entry ID from search results
+2. Call `mcp__unimatrix__context_get(id: {entry_id}, format: "markdown")` for the full text
+
+Or pass `format: "markdown"` directly to search if you want full content for all results.
+
+---
+
+## When You Find Stale or Wrong Knowledge
+
+Search may surface entries that are outdated or incorrect. Don't ignore them — fix the knowledge base:
+
+| Situation | Action |
+|-----------|--------|
+| Entry is **wrong** — contains incorrect information | `mcp__unimatrix__context_correct(original_id: {id}, content: "{corrected version}", reason: "{why}")` — supersedes with chain link |
+| Entry is **outdated** — no longer relevant | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why it no longer applies}")` |
+| Entry is **suspicious** — may be poisoned or invalid | `mcp__unimatrix__context_quarantine(id: {id}, reason: "{concern}")` — Admin only |
+
+Correcting knowledge is as important as storing it. Every agent shares responsibility for knowledge quality.

package/skills/query-patterns/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: "query-patterns"
+description: "Query Unimatrix for component patterns, procedures, and conventions before designing or implementing. Use BEFORE writing pseudocode or code."
+---
+
+# Query Patterns — Find How Things Are Done Here
+
+## What This Skill Does
+
+Searches Unimatrix for established patterns, procedures, and conventions relevant to the work you're about to do. Returns actionable guidance on how similar work was done before.
+
+**Use BEFORE designing or implementing** — not after.
+
+---
+
+## When to Use
+
+| Situation | Query approach |
+|-----------|---------------|
+| Designing a new MCP tool | Search for component patterns in `unimatrix-server` |
+| Adding a new table to redb | Search for procedures in `unimatrix-store` |
+| Writing integration tests | Search for testing conventions |
+| Implementing any component | Search for patterns in the affected crate |
+
+---
+
+## How to Query
+
+### Step 1: Search by crate/area
+
+```
+mcp__unimatrix__context_search(
+  query: "{what you're building — e.g., 'MCP tool handler'}",
+  category: "pattern",
+  k: 5
+)
+```
+
+### Step 2: Also check conventions for the area
+
+```
+mcp__unimatrix__context_search(
+  query: "{area — e.g., 'server tool pipeline'}",
+  category: "convention",
+  k: 5
+)
+```
+
+### Step 3: Check for procedures (step-by-step techniques)
+
+```
+mcp__unimatrix__context_search(
+  query: "{task — e.g., 'adding a new MCP tool'}",
+  category: "procedure",
+  k: 3
+)
+```
+
+### Step 4: Check for relevant ADRs
+
+```
+mcp__unimatrix__context_lookup(
+  topic: "{feature-id}",
+  category: "decision"
+)
+```
+
+---
+
+## Interpreting Results
+
+**Patterns** tell you the reusable structure. Follow them unless your component has a good reason to deviate. If you deviate, note why in your pseudocode or code comments.
+
+**Procedures** tell you the steps. Follow them in order. If a step is wrong or missing, note it — the retrospective will update the procedure.
+
+**Conventions** tell you the rules. Follow them always. No deviations.
+
+**ADRs** tell you what was decided and why. Respect the decision. If it seems wrong for your case, flag it to the coordinator — don't silently override.
+
+---
+
+## If Nothing Is Found
+
+No results means either:
+1. This is genuinely new work with no prior patterns — proceed with your best design
+2. Patterns exist but aren't stored yet — check the codebase directly for similar code
+
+In either case, your work may establish a NEW pattern that the retrospective will extract.
+
+---
+
+## When You Find Stale or Wrong Knowledge
+
+Query results may include entries that are outdated or incorrect. Fix them before they mislead the next agent:
+
+| Situation | Action |
+|-----------|--------|
+| Pattern/procedure is **wrong** | `mcp__unimatrix__context_correct(original_id: {id}, content: "{corrected version}", reason: "{why}")` |
+| Pattern/procedure is **outdated** | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why}")` |
+| Convention no longer applies | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why}")` |
+
+If you correct or deprecate an entry during your session, mention it in your return to the coordinator so it can be noted in the outcome.
+
+---
+
+## What NOT to Do
+
+- Do NOT store patterns during this query phase — that's the retrospective's job
+- Do NOT ignore results because "my approach is better" — patterns represent accumulated project wisdom
+- Do NOT query for workflow choreography — that's in your coordinator, not Unimatrix

package/skills/record-outcome/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: "record-outcome"
+description: "Record a feature or bugfix outcome in Unimatrix. Use at the end of every session (design, delivery, bugfix, retrospective)."
+---
+
+# Record Outcome — Session Completion Record
+
+## What This Skill Does
+
+Stores a structured outcome record in Unimatrix. Outcomes enable the retrospective pipeline to analyze what shipped, how it went, and detect cross-feature patterns.
+
+**Use at the END of every session** — design, delivery, bugfix, or retrospective.
+
+---
+
+## How to Record
+
+Call `mcp__unimatrix__context_store` with these parameters:
+
+| Parameter | Value |
+|-----------|-------|
+| `category` | `"outcome"` |
+| `topic` | `"{feature-id}"` (e.g., `"col-011"`) |
+| `feature_cycle` | `"{feature-id}"` |
+| `tags` | Structured tags (see below) |
+| `content` | What happened — artifacts, results, key facts |
+| `agent_id` | Your role name (e.g. `uni-architect`) |
+
+### Required Tags
+
+Tags use `key:value` format. Include ALL applicable:
+
+| Tag | Values | Required |
+|-----|--------|----------|
+| `type:{x}` | `feature`, `bugfix`, `incident`, `process`, `session` | Yes |
+| `phase:{x}` | `research`, `design`, `implementation`, `testing`, `validation` | Yes |
+| `result:{x}` | `pass`, `fail`, `rework`, `skip` | Yes |
+| `gate:{x}` | `3a`, `3b`, `3c` | Only for delivery (last gate passed) |
+
+### Examples
+
+**Design session complete:**
+```
+mcp__unimatrix__context_store(
+  category: "outcome",
+  topic: "col-011",
+  feature_cycle: "col-011",
+  tags: ["type:feature", "phase:design", "result:pass"],
+  content: "Session 1 complete. 9 artifacts produced. GH Issue #65.
+    ADR entries: #250, #251. 3 scope risks identified (SR-01 through SR-03)."
+)
+```
+
+**Implementation session complete:**
+```
+mcp__unimatrix__context_store(
+  category: "outcome",
+  topic: "col-011",
+  feature_cycle: "col-011",
+  tags: ["type:feature", "phase:implementation", "result:pass", "gate:3c"],
+  content: "Session 2 complete. All 3 gates passed. PR #70.
+    12 unit tests, 4 integration tests added. No rework needed."
+)
+```
+
+**Bugfix complete:**
+```
+mcp__unimatrix__context_store(
+  category: "outcome",
+  topic: "col-011",
+  feature_cycle: "col-011",
+  tags: ["type:bugfix", "phase:implementation", "result:pass"],
+  content: "Bug fix shipped. Root cause: off-by-one in confidence calculation.
+    PR #72. 2 tests added. No rework."
+)
+```
+
+---
+
+## Content Guidelines
+
+Keep content to 100-300 characters. Include:
+- What shipped (artifact count, PR number)
+- Key metrics (test count, gate results, rework count)
+- Notable facts (ADR IDs, risk count, scope changes)
+
+Do NOT include full artifact lists or file paths — those are in the feature directory.
+
+---
+
+## Self-Verification
+
+After calling `context_store`, verify:
+- Response confirms entry stored (returns entry ID)
+- Tags follow the `key:value` format exactly
+- `feature_cycle` matches the feature ID