@dug-21/unimatrix 0.6.2 → 0.7.0

package/skills/retro/SKILL.md

@@ -1,296 +0,0 @@
----
-name: "retro"
-description: "Post-merge retrospective — extracts patterns, procedures, and lessons from shipped features into Unimatrix. Use after a feature PR is merged."
----
-
-# Retro — Post-Merge Knowledge Extraction
-
-## What This Skill Does
-
-Analyzes a shipped feature and extracts reusable knowledge — patterns, procedures, and lessons — into Unimatrix. This is how the project learns.
-
----
-
-## Inputs
-
-From the invoker:
-- Feature ID (e.g., `col-011`)
-- PR number (merged)
-- GH Issue number
-
----
-
-## Phase 1: Data Gathering & Retrospective Analysis
-
-Gather all evidence about the shipped feature:
-
-1. **Run retrospective analysis** (if observation data exists):
-   ```
-   mcp__unimatrix__context_cycle_review(feature_cycle: "{feature-id}")
-   ```
-   This returns structured data: metrics, hotspots, baseline comparisons, narratives, and recommendations.
-
-2. **Analyze the retrospective data** — extract actionable findings:
-
-   a. **Hotspots by severity** — Classify each hotspot:
-      - `Warning` hotspots → potential lessons or procedure gaps
-      - `Info` hotspots → note trends, may not need action
-      - Key hotspot types to watch:
-        - `orphaned_calls` → tool invocations with no terminal event — check context overflow or parallel call management
-        - `sleep_workarounds` → agents using sleep instead of run_in_background
-        - `cold_restart` → context loss after gaps, agents re-reading files
-        - `coordinator_respawns` → SM lifetime/handoff issues
-        - `post_completion_work` → significant work after task marked done (scope issue?)
-        - `lifespan` → agent running too long (context overflow risk)
-        - `mutation_spread` → touching too many files (coupling/scope creep?)
-        - `file_breadth` / `reread_rate` → agents inefficiently navigating codebase
-
-   b. **Baseline outliers** — Any metric with `status: "Outlier"` deserves attention:
-      - Is it a positive shift (e.g., higher `parallel_call_rate`)? Note as trend.
-      - Is it a problem (e.g., high `post_completion_work`)? Extract lesson.
-      - Is it a `NewSignal`? First time this metric has a non-zero value — note for future tracking.
-
-   c. **Recommendations** — The retrospective returns specific actionable recommendations.
-      Each one maps to either a procedure update or a lesson learned.
-
-   d. **Narratives** — Temporal clustering of events. Look for:
-      - Burst patterns (many events in short window → agent struggling)
-      - Sequence patterns (repeated cycles → inefficient workflow)
-      - Top files (which files caused the most friction)
-
-3. **Read feature artifacts**:
-   - `product/features/{id}/architecture/ARCHITECTURE.md`
-   - `product/features/{id}/pseudocode/OVERVIEW.md`
-   - `product/features/{id}/testing/RISK-COVERAGE-REPORT.md`
-   - `product/features/{id}/reports/gate-3a-report.md`
-   - `product/features/{id}/reports/gate-3b-report.md`
-   - `product/features/{id}/reports/gate-3c-report.md`
-
-4. **Check for rework signals**: Did any gate fail before passing? Read the gate report for what went wrong.
-
-5. **Review the git log** for this feature's branch:
-   ```bash
-   git log main..HEAD --oneline
-   ```
-   Look for rework commits (`fix(gate):`) — these indicate where the process struggled.
-
----
-
-## Phase 1b: Stewardship Quality Review
-
-Before extracting new patterns, review the quality of entries agents stored during this feature cycle.
-
-1. **Query entries stored during the feature**:
-   ```
-   mcp__unimatrix__context_search(
-     query: "{feature-id}",
-     k: 20
-   )
-   ```
-   Also search by feature_cycle tag if available. Use content/title matching as fallback — not all agents tag consistently.
-
-2. **Assess each entry against its category template**:
-   - **Patterns**: Has what/why/scope structure? Is "why" substantive (not "it works")?
-   - **Lessons**: Has what-happened/root-cause/takeaway? Is takeaway actionable?
-   - **Procedures**: Has numbered steps? Are steps specific (not generic)?
-
-3. **Curate**:
-   - **Low-quality entries** (missing structure, no substantive "why", API docs disguised as patterns): deprecate via `context_deprecate` with reason.
-   - **High-quality entries** confirmed by successful delivery: note for the architect to validate during pattern extraction.
-   - **Miscategorized entries** (lesson stored as pattern, or vice versa): note for correction.
-
-4. **Report** the stewardship review results before proceeding to Phase 2:
-   ```
-   Stewardship Quality Review:
-   - Entries found: {N}
-   - Quality: {N} good, {N} deprecated (low quality), {N} flagged for recategorization
-   - Details: {list each entry with assessment}
-   ```
-
----
-
-## Phase 2: Pattern & Procedure Extraction (MUST be a subagent)
-
-**Before spawning the architect**, prepare a structured retrospective briefing from Phase 1. This replaces the vague "paste summary" — give the architect concrete data to work with.
-
-Build the briefing:
-
-```
-RETROSPECTIVE BRIEFING for {feature-id}
-========================================
-
-Session stats: {session_count} sessions, {total_records} records, {total_tool_calls} tool calls, {total_duration_secs}s
-
-HOTSPOTS ({count} detected):
-{For each hotspot: "- [{severity}] {rule_name}: {claim} (measured: {measured}, threshold: {threshold})"}
-
-BASELINE OUTLIERS:
-{For each baseline entry with status "Outlier" or "NewSignal":
-  "- {metric_name}: {current_value} vs mean {mean} (stddev {stddev}) — {status}"}
-
-RECOMMENDATIONS FROM RETROSPECTIVE:
-{For each recommendation: "- [{hotspot_type}] {action} — {rationale}"}
-
-REWORK SIGNALS:
-{gate failures, rework commits from Phase 1 step 4-5}
-```
-
-Spawn `uni-architect` to review what was built and extract reusable knowledge:
-
-```
-Agent(uni-architect, "
-  Your agent ID: {feature-id}-retro-architect
-  Your Unimatrix agent_id: uni-architect
-  MODE: retrospective (not design)
-  Feature: {feature-id}
-
-  You are reviewing a SHIPPED feature to extract reusable knowledge.
-  You are NOT designing anything new.
-
-  Read these artifacts:
-  - product/features/{id}/architecture/ARCHITECTURE.md
-  - product/features/{id}/pseudocode/OVERVIEW.md (component structure)
-  - product/features/{id}/reports/gate-3a-report.md (design review)
-  - product/features/{id}/reports/gate-3b-report.md (code review)
-  - product/features/{id}/reports/gate-3c-report.md (risk validation)
-  - product/features/{id}/testing/RISK-COVERAGE-REPORT.md
-
-  {paste the RETROSPECTIVE BRIEFING from above}
-
-  YOUR TASKS:
-
-  1. PATTERN EXTRACTION — For each component implemented:
-     a. Use /query-patterns to find existing patterns for the affected crate(s)
-     b. If the component followed an existing pattern: verify it's still accurate.
-        If the pattern drifted, use /store-procedure or context_correct to update it.
-     c. If the component established a NEW reusable structure (used in 2+ features
-        or clearly generic): store it via context_store(category: 'pattern').
-     d. If the component was one-off: skip — don't store patterns for unique work.
-
-  2. PROCEDURE REVIEW — Check if any HOW-TO changed:
-     a. Did the build/test/integration process change?
-     b. Did schema migration steps change?
-     c. Was there a new technique that future developers need?
-     If yes: use /store-procedure (new) or context_correct (update existing).
-
-  3. ADR VALIDATION — For each ADR created during this feature:
-     a. Was the decision validated by successful implementation?
-     b. Did implementation reveal that an ADR was wrong or incomplete?
-        If so: flag for supersession (do NOT supersede without human approval).
-
-  4. LESSON EXTRACTION — Two sources:
-
-     A. From gate failures and rework:
-        a. What went wrong? (root cause, not symptoms)
-        b. Is the lesson generalizable beyond this feature?
-        c. If yes: use /store-lesson.
-
-     B. From retrospective hotspots and recommendations:
-        For each Warning-severity hotspot, ask:
-        - Is this a recurring problem (check baseline — is it consistently above threshold)?
-        - Can it be prevented by a procedure change or config update?
-        - If yes: store as lesson (/store-lesson) or procedure (/store-procedure).
-
-        For each recommendation from the retrospective:
-        - Check if a matching procedure already exists (/query-patterns).
-        - If not, and the recommendation is actionable: store as procedure.
-        - If it updates existing guidance: use context_correct.
-
-     C. From baseline outliers:
-        - Positive outliers (improvements): note what changed and why — may be a new pattern.
-        - Negative outliers (regressions): root-cause and store as lesson if generalizable.
-
-  Return:
-  1. Patterns: [new entries with IDs, updated entries with IDs, skipped with reason]
-  2. Procedures: [new/updated with IDs]
-  3. ADR status: [validated ADRs, flagged-for-supersession ADRs with reason]
-  4. Lessons: [new entries with IDs]
-  5. Retrospective findings: [hotspot-derived lessons, recommendation actions taken, outlier notes]")
-```
-
----
-
-## Phase 3: ADR Supersession (if flagged)
-
-If the architect flagged any ADRs for supersession:
-
-1. Present each flagged ADR to the human:
-   ```
-   ADR #{entry-id}: "{title}"
-   Architect's finding: {why it should be superseded}
-   Proposed replacement: {what the new decision should be}
-
-   Approve supersession?
-   ```
-
-2. If human approves: spawn architect to perform the supersession via `/store-adr`.
-3. If human disagrees: note as "ADR validated with caveat".
-
----
-
-## Phase 4: Worktree Cleanup
-
-Worker agents spawned with `isolation: "worktree"` create directories under `.claude/worktrees/`. Each contains a full `target/` build directory (~1-2GB). Clean up after merge.
-
-```bash
-# List worktrees to find stale agent-created ones
-git worktree list
-
-# Remove each stale worktree (safe — feature is merged)
-git worktree remove .claude/worktrees/{agent-id}/ 2>/dev/null
-
-# Prune stale entries
-git worktree prune
-```
-
-If a worktree has uncommitted changes, warn the human — do NOT force-remove.
-
----
-
-## Phase 5: Summary & Outcome
-
-Collect all knowledge base changes from Phases 2-3.
-
-Use `/record-outcome` with:
-- Feature: `{feature-id}`
-- Type: `retro`
-- Phase: `retro`
-- Result: `pass`
-- Content: `Retrospective complete. {N} patterns, {N} procedures, {N} lessons extracted. {N} ADRs validated. Hotspots: {count} ({warning_count} warnings). Outliers: {list outlier metric names}.`
-
-**Return format:**
-```
-RETROSPECTIVE COMPLETE — Knowledge base updated.
-
-Feature: {feature-id}
-PR: #{pr-number} (merged)
-
-Retrospective summary:
-- Sessions: {session_count}, Tool calls: {total_tool_calls}, Duration: {duration}
-- Hotspots: {count} ({warning_count} warnings, {info_count} info)
-- Baseline outliers: {list metric names and status}
-
-Knowledge extracted:
-- Patterns: {count} new, {count} updated
-- Procedures: {count} new, {count} updated
-- Lessons learned: {count} new ({count} from hotspots, {count} from gate failures)
-- ADRs validated: {count}
-- ADRs superseded: {count}
-
-Details:
-{list each entry with Unimatrix ID, title, and whether new or updated}
-```
-
----
-
-## When to Go Lightweight
-
-Not every feature needs a full retro:
-
-| Situation | Action |
-|---|---|
-| Zero gate failures, no rework, zero hotspots | Skip lesson extraction. Focus on patterns/procedures only. |
-| Minor enhancement (1-2 components) | Check for pattern drift only, skip procedure review. |
-| New infrastructure introduced | Full retro — high likelihood of new patterns and procedures. |
-| Multiple SCOPE FAILs or heavy rework | Full retro — prioritize lesson extraction. |
-| Many Warning hotspots or baseline outliers | Full retro — prioritize hotspot-driven lessons and procedure updates. |

package/skills/review-pr/SKILL.md

@@ -1,128 +0,0 @@
----
-name: "review-pr"
-description: "PR security review and merge readiness check. Use after delivery or bugfix opens a PR, or standalone when human wants to review a PR."
----
-
-# Review PR — Security Review + Merge Readiness
-
-## What This Skill Does
-
-Verifies gate results, spawns a fresh-context security reviewer, and assesses merge readiness. Works as:
-- **Auto-invoked** by `uni-scrum-master` at the end of delivery/bugfix protocols
-- **Standalone** when human invokes `/review-pr {pr-number}` directly
-
----
-
-## Inputs
-
-From the invoker (SM or human):
-- PR number or URL
-- Feature ID (if available)
-- GH Issue number (if available)
-
-If invoked standalone with just a PR number, extract feature ID and GH Issue from the PR body.
-
----
-
-## Step 1: Verify Gate Results
-
-Read the feature directory for gate reports:
-
-- `product/features/{id}/reports/gate-3a-report.md` — exists and shows PASS
-- `product/features/{id}/reports/gate-3b-report.md` — exists and shows PASS
-- `product/features/{id}/reports/gate-3c-report.md` — exists and shows PASS
-- `product/features/{id}/testing/RISK-COVERAGE-REPORT.md` — exists
-
-For bugfix PRs, check for the single gate report instead.
-
-If any gate report is missing or shows FAIL, **stop and report** — delivery is incomplete.
-
----
-
-## Step 2: Security Review (Fresh Context — MUST be a subagent)
-
-Spawn `uni-security-reviewer` as a subagent for fresh-context review:
-
-```
-Agent(uni-security-reviewer, "
-  Your agent ID: {feature-id}-security-reviewer
-  Your Unimatrix agent_id: uni-security-reviewer
-  SECURITY REVIEW — Fresh context. Read the PR diff cold.
-
-  PR: #{pr-number} on branch {branch-name}
-  Feature: {feature-id}
-  GH Issue: #{issue-number}
-
-  Read these with fresh eyes:
-  - git diff main...HEAD (the full change set)
-  - product/features/{id}/architecture/ARCHITECTURE.md (if exists)
-  - product/features/{id}/RISK-TEST-STRATEGY.md (if exists)
-
-  Assess:
-  - OWASP concerns: injection, access control, deserialization, input validation
-  - Blast radius: worst case if code has a subtle bug
-  - Regression risk: could this break existing functionality
-  - Dependency safety: new dependencies, known vulnerabilities
-  - Secrets: no hardcoded credentials, tokens, or keys
-
-  Comment findings on the PR via gh CLI.
-  If any finding is blocking: use gh pr review --request-changes.
-
-  Return: risk level (low/medium/high/critical), findings summary,
-  blocking findings (yes/no + details).")
-```
-
----
-
-## Step 3: Merge Readiness Assessment
-
-After security review returns, check all criteria:
-
-- [ ] All delivery gates passed (from gate reports)
-- [ ] Security review completed — no blocking findings
-- [ ] PR description references GH Issue
-- [ ] No merge conflicts with main
-
-If all pass → `Merge readiness: READY`
-If any blocking item → `Merge readiness: BLOCKED` with specific items listed
-
----
-
-## Step 4: Report
-
-Post security review result to GH Issue:
-```
-## Security Review — {PASS|BLOCKED}
-- Summary: {risk level} — {findings summary}
-- Merge readiness: {READY|BLOCKED}
-- Issues: [blocking items if any]
-```
-
-**Return format** (to SM or human):
-```
-PR REVIEW COMPLETE
-
-PR: {URL}
-Feature: {feature-id}
-
-Security Review: {risk level} — {summary}
-Blocking findings: {yes/no + details}
-Merge readiness: {READY | BLOCKED}
-
-If BLOCKED:
-- Blocking items: [list]
-- Recommended action: [fix items or discuss]
-
-Human action required: Approve and merge, or address blocking items.
-```
-
----
-
-## Step 5: Record Outcome
-
-Use `/record-outcome` with:
-- Feature: `{feature-id}`
-- Type: `feature` (or `bugfix`)
-- Phase: `review`
-- Result: `pass` (or `blocked`)
-- Content: `PR review complete. Security: {risk level}. Merge readiness: {READY|BLOCKED}.`

package/skills/store-adr/SKILL.md

@@ -1,142 +0,0 @@
----
-name: "store-adr"
-description: "Store an architectural decision record in Unimatrix. ADRs live in Unimatrix only — no ADR files. Use after each design decision."
----
-
-# Store ADR — Architectural Decisions in Unimatrix
-
-## What This Skill Does
-
-Stores an architectural decision record in Unimatrix as the **sole authoritative store**. ADRs are NOT written as files — Unimatrix provides search, supersession chains, and cross-feature discovery that files cannot.
-
-**Use this AFTER each design decision.** The architect is the sole ADR authority.
-
----
-
-## How to Store a New ADR
-
-### Step 1: Search for prior ADRs in the same domain (MANDATORY)
-
-```
-mcp__unimatrix__context_search(query: "{decision domain}", category: "decision", k: 5)
-```
-
-Check if any existing ADR covers the same concern. If so, you may need to supersede it (see "How to Supersede" below).
-
-### Step 2: Store the ADR
-
-```
-mcp__unimatrix__context_store(
-  title: "ADR-NNN: {decision title}",
-  content: "## Context\n{why this decision is needed}\n\n## Decision\n{what we decided}\n\n## Consequences\n{what follows from this decision}",
-  topic: "{feature-id}",
-  category: "decision",
-  tags: ["adr", "{phase-prefix}", "{domain-tags}"],
-  source: "architect",
-  feature_cycle: "{feature-id}",
-  agent_id: "{your role name, e.g. uni-architect}"
-)
-```
-
-### Step 3: Record the entry ID
-
-Note the Unimatrix entry ID returned. Pass it to the coordinator — downstream agents and the synthesizer need ADR entry IDs to reference decisions.
-
-### Step 4: Reference in ARCHITECTURE.md
-
-In your ARCHITECTURE.md, reference ADRs by Unimatrix entry ID:
-
-```markdown
-## Decisions
-| ADR | Title | Unimatrix ID |
-|-----|-------|--------------|
-| ADR-001 | Use rmcp 0.16 with stdio | #77 |
-| ADR-002 | Additive confidence model | #85 |
-```
-
----
-
-## How to Supersede an Existing ADR
-
-When a new decision replaces a prior one:
-
-### Step 1: Find the old ADR
-
-```
-mcp__unimatrix__context_search(query: "{domain of old decision}", category: "decision")
-```
-
-Note the old entry's ID.
-
-### Step 2: Use context_correct to supersede
-
-```
-mcp__unimatrix__context_correct(
-  original_id: {old entry ID},
-  content: "## Context\n{why the old decision is being replaced}\n\n## Decision\n{new decision}\n\n## Consequences\n{what changes}",
-  title: "ADR-NNN: {new decision title}",
-  reason: "Superseded by {feature-id}: {short explanation}"
-)
-```
-
-This automatically:
-- Deprecates the old entry
-- Creates a new entry with supersession chain
-- Preserves the old decision for historical reference
-
----
-
-## ADR Content Guidelines
-
-**Keep ADRs to 300-800 characters.** They capture the decision, not the implementation.
-
-```
-## Context
-The briefing tool returns duties, conventions, and semantic matches.
-Duties duplicate what's already in agent definition files, consuming
-~200 tokens for zero new information.
-
-## Decision
-Remove duties from Unimatrix categories and context_briefing responses.
-Agent defs are the sole authority for role responsibilities.
-
-## Consequences
-- Briefing returns 2 sections (conventions + relevant context) instead of 3
-- ~200 tokens freed per briefing call for more useful content
-- 28 existing duty entries deprecated
-- uni-init bootstrap no longer extracts duties
-```
-
-NOT a full design document. NOT implementation details. Just: why, what, and so-what.
-
----
-
-## Tagging Conventions
-
-| Tag Type | Examples |
-|----------|----------|
-| Always | `adr` |
-| Phase prefix | `nexus`, `vinculum`, `collective`, `cortical`, `alcove` |
-| Domain | `storage`, `serialization`, `mcp`, `embedding`, `security`, `confidence` |
-| Cross-cutting | `error-handling`, `async`, `thread-safety`, `api-design` |
-
----
-
-## Self-Verification
-
-After storing:
-- Confirm entry ID returned
-- If **near-duplicate warning**: review existing entry — you may need to supersede rather than create
-- Record entry ID in your agent report and ARCHITECTURE.md decisions table
-
----
-
-## What NOT to Store as ADRs
-
-| Don't Store | Why |
-|-------------|-----|
-| Draft decisions under discussion | Store only finalized decisions |
-| Implementation details (how) | ADRs capture the why — code captures the how |
-| Decisions by other agents | Architect is the sole ADR authority |
-| Coding conventions | Use `convention` category instead |
-| Step-by-step procedures | Use `/store-procedure` instead |

package/skills/store-lesson/SKILL.md

@@ -1,109 +0,0 @@
----
-name: "store-lesson"
-description: "Store a lesson learned from a failure, gate rejection, or unexpected issue. Use after bugfixes and gate failures to prevent recurrence."
----
-
-# Store Lesson — Failure Knowledge
-
-## What This Skill Does
-
-Stores a lesson learned in Unimatrix. Lessons capture what went wrong, why, and the takeaway. They surface in future briefings and searches to prevent the same failure from recurring.
-
-**Use after:** gate failures, bug diagnoses, unexpected issues, rework cycles.
-
----
-
-## How to Store
-
-### Step 1: Check for existing lessons in the same area
-
-```
-mcp__unimatrix__context_search(
-  query: "{what went wrong}",
-  category: "lesson-learned",
-  k: 3
-)
-```
-
-If a matching lesson already exists, go to Step 2b (supersede) instead of creating a duplicate.
-
-### Step 2a: Store NEW lesson (no prior exists)
-
-```
-mcp__unimatrix__context_store(
-  title: "{concise description of what went wrong}",
-  content: "{structured lesson content}",
-  topic: "{feature-id or crate}",
-  category: "lesson-learned",
-  tags: ["{domain}", "{failure-type}"],
-  agent_id: "{your role name, e.g. uni-architect}"
-)
-```
-
-### Step 2b: Supersede EXISTING lesson (prior exists but is incomplete or outdated)
-
-```
-mcp__unimatrix__context_correct(
-  original_id: {old entry ID},
-  content: "{updated lesson with new evidence or broader scope}",
-  reason: "Updated: {what new evidence or context was added}"
-)
-```
-
-This deprecates the old lesson and creates a corrected version with a supersession chain. Future searches return the latest version.
-
-### When to deprecate without replacing
-
-If a lesson is simply wrong or no longer applies (e.g., the underlying code was redesigned):
-
-```
-mcp__unimatrix__context_deprecate(id: {entry ID}, reason: "{why it no longer applies}")
-```
-
----
-
-## Content Format
-
-Structure as: **What happened -> Root cause -> Takeaway** (200-500 chars):
-
-```
-Gate 3b rejected: confidence calculation used f32 intermediate values
-despite f64 pipeline decision (ADR-003). Root cause: rust-dev didn't
-read ADR before implementing. Takeaway: MANDATORY ADR read step in
-rust-dev pseudocode consumption is not optional — validator should
-check ADR compliance explicitly.
-```
-
-NOT a full incident report. NOT a narrative. Just the facts that prevent recurrence.
-
----
-
-## Tagging Conventions
-
-| Tag type | Examples |
-|----------|----------|
-| Failure type | `gate-failure`, `bug`, `rework`, `regression`, `scope-fail` |
-| Gate | `gate-3a`, `gate-3b`, `gate-3c` |
-| Domain | `confidence`, `storage`, `mcp`, `testing` |
-| Severity | `minor`, `major`, `critical` |
-
----
-
-## Who Stores Lessons
-
-| Agent | When |
-|-------|------|
-| uni-bug-investigator | After diagnosing root cause — store the generalizable pattern |
-| uni-validator | After gate failure — store what the gate caught and why |
-| Coordinator | After rework cycle — store what caused the rework |
-| Retrospective agents | After analyzing session data — store systemic issues |
-
----
-
-## What Makes a Good Lesson
-
-**Generalizable** — applies beyond this one incident. "Off-by-one in loop" is not a lesson. "Boundary conditions at table scan limits not covered by unit tests" is.
-
-**Actionable** — the takeaway prevents recurrence. "Be more careful" is not actionable. "Add boundary condition tests for every table scan method" is.
-
-**Concise** — 200-500 chars. If it needs more, it's probably a procedure or a pattern, not a lesson.