@soleri/forge 5.4.0 → 5.6.0

package/src/skills/retrospective.md

@@ -0,0 +1,205 @@
+---
+name: retrospective
+description: Use when the user asks "what did I learn this week", "sprint retro", "retrospective", "learning report", "what went well", "what could improve", "weekly summary", "monthly report", or wants to reflect on recent work and extract actionable insights from accumulated data.
+---
+
+# Retrospective — Learning Report From Real Data
+
+Generate a retrospective from actual session data, vault captures, plan outcomes, and brain intelligence. Not opinions — data-driven reflection on what happened, what worked, what didn't, and what to do differently.
+
+## When to Use
+
+- End of sprint / week / month
+- "What did I learn this week?"
+- "Sprint retrospective"
+- "What went well? What didn't?"
+- After completing a major feature or milestone
+
+## The Magic: Data-Driven Reflection
+
+### Step 1: Gather the Data
+
+**Brain stats — the big picture:**
+
+```
+YOUR_AGENT_core op:brain_stats
+```
+
+**Recent brain stats — compare velocity:**
+
+```
+YOUR_AGENT_core op:brain_stats
+  params: { since: "<start of period>" }
+```
+
+**Pattern strengths — what's proven:**
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+**Recent vault captures — what was learned:**
+
+```
+YOUR_AGENT_core op:vault_recent
+```
+
+**Memory topics — where knowledge clusters:**
+
+```
+YOUR_AGENT_core op:memory_topics
+```
+
+**Memory stats — volume and health:**
+
+```
+YOUR_AGENT_core op:memory_stats
+```
+
+**Plan stats — execution track record:**
+
+```
+YOUR_AGENT_core op:plan_stats
+```
+
+**Loop history — iterative workflow outcomes:**
+
+```
+YOUR_AGENT_core op:loop_history
+```
+
+**Search insights — what people looked for but didn't find:**
+
+```
+YOUR_AGENT_core op:admin_search_insights
+```
+
+**Vault analytics — knowledge quality:**
+
+```
+YOUR_AGENT_core op:admin_vault_analytics
+```
+
+### Step 2: Analyze Patterns
+
+**Stale knowledge needing refresh:**
+
+```
+YOUR_AGENT_core op:vault_age_report
+```
+
+**Duplicates that crept in:**
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+**Contradictions in the knowledge base:**
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+**Curator health audit — overall quality:**
+
+```
+YOUR_AGENT_core op:curator_health_audit
+```
+
+### Step 3: Present the Retrospective
+
+```
+## Retrospective: [Period]
+
+### By the Numbers
+| Metric | This Period | Previous | Trend |
+|--------|-----------|----------|-------|
+| Patterns captured | X | Y | ↑/↓ |
+| Anti-patterns logged | X | Y | ↑/↓ |
+| Plans completed | X | Y | ↑/↓ |
+| Brain strength (avg) | X | Y | ↑/↓ |
+| Vault entries total | X | — | — |
+| Search misses | X | Y | ↑/↓ |
+
+### What Went Well
+[Patterns with high brain strength, completed plans, growing domains]
+
+### What Didn't Go Well
+[Recurring anti-patterns, failed plans, search misses = knowledge gaps]
+
+### Strongest Patterns
+[Top 5 patterns by brain strength — these are your superpowers]
+
+### Recurring Anti-Patterns
+[Top 3 anti-patterns that keep appearing — these need systemic fixes]
+
+### Knowledge Gaps
+[Domains with low coverage, frequent search misses, stale entries]
+
+### Vault Health
+- Quality score: X/100
+- Duplicates found: N
+- Contradictions found: N
+- Stale entries (>30 days): N
+
+### Recommendations
+1. [Action item based on data]
+2. [Action item based on data]
+3. [Action item based on data]
+```
+
+### Step 4: Capture the Retrospective
+
+Save the retrospective itself as knowledge:
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "Retrospective — [period]",
+    description: "<key findings and action items>",
+    type: "workflow",
+    category: "meta",
+    tags: ["retrospective", "<period>"]
+  }
+```
+
+### Step 5: Clean Up (Optional)
+
+If the retrospective revealed quality issues, offer to fix them:
+
+**Consolidate vault (deduplicate, normalize, groom):**
+
+```
+YOUR_AGENT_core op:curator_consolidate
+```
+
+**Rebuild brain intelligence with fresh data:**
+
+```
+YOUR_AGENT_core op:brain_build_intelligence
+```
+
+## The Magic
+
+This feels like magic because the user says "sprint retro" and gets a data-driven report they didn't have to compile. It's not AI making up observations — it's actual metrics from their vault, brain, plans, and memory. The recommendations come from real gaps, not generic advice.
+
+## Agent Tools Reference
+
+| Op                          | When to Use                 |
+| --------------------------- | --------------------------- |
+| `brain_stats`               | Big picture metrics         |
+| `brain_strengths`           | Proven patterns             |
+| `vault_recent`              | What was captured recently  |
+| `memory_topics`             | Knowledge clusters          |
+| `memory_stats`              | Memory volume and health    |
+| `plan_stats`                | Plan completion rates       |
+| `loop_history`              | Iterative workflow outcomes |
+| `admin_search_insights`     | Search miss analysis        |
+| `admin_vault_analytics`     | Knowledge quality metrics   |
+| `vault_age_report`          | Stale entries               |
+| `curator_detect_duplicates` | Duplicate detection         |
+| `curator_contradictions`    | Knowledge conflicts         |
+| `curator_health_audit`      | Overall vault quality       |
+| `capture_knowledge`         | Persist the retrospective   |
+| `curator_consolidate`       | Post-retro cleanup          |
+| `brain_build_intelligence`  | Rebuild intelligence        |

package/src/skills/second-opinion.md

@@ -0,0 +1,149 @@
+---
+name: second-opinion
+description: Use when the user asks "should I", "what do you think about", "which approach", "compare options", "what would you recommend", "pros and cons", "trade-offs", or faces any technical decision and wants an informed recommendation backed by vault knowledge, brain patterns, and web research.
+---
+
+# Second Opinion — Decision Support From All Sources
+
+Before making any technical decision, get an informed recommendation that synthesizes vault knowledge, brain patterns, cross-project experience, and web research. Never decide in a vacuum.
+
+## When to Use
+
+- "Should I use Redis or Memcached?"
+- "What's the best way to handle auth?"
+- "Which testing framework?"
+- "Microservices or monolith?"
+- Any fork-in-the-road technical decision
+
+## The Magic: Multi-Source Decision Intelligence
+
+### Step 1: Understand the Decision
+
+Classify the intent to understand what kind of decision this is:
+
+```
+YOUR_AGENT_core op:route_intent
+  params: { prompt: "<user's question>" }
+```
+
+### Step 2: Search All Knowledge Sources (in order)
+
+**Vault — has this been decided before?**
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<the decision or options being considered>" }
+```
+
+Look specifically for:
+
+- Previous decisions on this topic (type: "decision")
+- Patterns that favor one approach
+- Anti-patterns that warn against an approach
+
+**Brain — what's proven to work?**
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+```
+YOUR_AGENT_core op:brain_recommend
+  params: { projectName: "<current project>" }
+```
+
+**Cross-project — what did other projects choose?**
+
+```
+YOUR_AGENT_core op:memory_cross_project_search
+  params: { query: "<the decision topic>", crossProject: true }
+```
+
+**Memory — any relevant context from past sessions?**
+
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "<decision topic>" }
+```
+
+**Web — what does the broader community say?**
+Search the web for:
+
+- Comparison articles (X vs Y for [use case])
+- Benchmarks and performance data
+- Community consensus on best practices
+- Known limitations and gotchas
+
+### Step 3: Synthesize and Present
+
+Format the recommendation as a decision brief:
+
+```
+## Decision: [Question]
+
+### What the Vault Says
+[Existing decisions, patterns, and anti-patterns from vault]
+
+### What the Brain Recommends
+[Proven patterns, cross-project insights]
+
+### What the Web Says
+[Community consensus, benchmarks, comparison data]
+
+### Options Analysis
+
+| Criteria | Option A | Option B | Option C |
+|----------|----------|----------|----------|
+| [criteria 1] | ... | ... | ... |
+| [criteria 2] | ... | ... | ... |
+| Vault support | [existing patterns?] | [existing patterns?] | — |
+| Brain confidence | [strength score] | [strength score] | — |
+
+### Recommendation
+[Clear recommendation with reasoning]
+
+### Risks
+[What could go wrong with the recommended approach]
+```
+
+### Step 4: Capture the Decision
+
+Once the user decides, capture it to the vault for future reference:
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<decision title>",
+    description: "<chosen option, rationale, rejected alternatives and why>",
+    type: "decision",
+    category: "<relevant domain>",
+    tags: ["<option-a>", "<option-b>", "decision", "<domain>"]
+  }
+```
+
+This is critical — the next person who faces the same decision will find it in the vault.
+
+## The Magic
+
+This feels like magic because the user asks "should I use X?" and instead of a generic AI opinion, they get:
+
+1. What their own project decided before (vault)
+2. What's proven to work across projects (brain)
+3. What other linked projects chose (cross-project)
+4. What the broader community recommends (web)
+5. A synthesized recommendation with trade-offs
+6. The decision captured for the next person who asks
+
+It's like having a senior architect who remembers every decision ever made.
+
+## Agent Tools Reference
+
+| Op                            | When to Use                          |
+| ----------------------------- | ------------------------------------ |
+| `route_intent`                | Classify the decision type           |
+| `search_intelligent`          | Find previous decisions and patterns |
+| `brain_strengths`             | Proven approaches                    |
+| `brain_recommend`             | Project-specific recommendations     |
+| `memory_cross_project_search` | What other projects decided          |
+| `memory_search`               | Session context for this decision    |
+| `capture_knowledge`           | Persist the final decision           |

package/src/skills/systematic-debugging.md

@@ -0,0 +1,241 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+<!-- Adapted from superpowers (MIT License) -->
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+## Phase 0: Search Before Investigating
+
+**BEFORE touching any code**, search for existing solutions. Follow this order:
+
+### Vault First
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<description of the bug or error message>" }
+```
+
+If the vault has a matching anti-pattern or previous fix, it likely contains the root cause and solution — apply it directly. This can save hours of investigation.
+
+Also check brain strengths for relevant debugging patterns:
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+Check memory for similar bugs across sessions:
+
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "<error or symptom>" }
+```
+
+### Web Search Second
+
+If the vault has nothing, search the web before investigating from scratch:
+
+- **Paste the exact error message** — someone likely hit this before
+- **Check GitHub issues** on relevant libraries
+- **Check Stack Overflow** for the error + framework/library combination
+- **Check official docs** — is this a known limitation or misconfiguration?
+
+A 30-second search that finds "this is a known issue in v3.2, upgrade to v3.3" saves hours of root cause investigation.
+
+### Then Investigate
+
+Only if vault and web search produce no answer, proceed to Phase 1.
+
+## Start a Debug Loop
+
+For complex bugs, start a validation loop to track investigation iterations:
+
+```
+YOUR_AGENT_core op:loop_start
+  params: { prompt: "Debug: <bug description>", mode: "custom" }
+```
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. Read Error Messages Carefully
+2. Reproduce Consistently
+3. Check Recent Changes
+4. Gather Evidence in Multi-Component Systems (add diagnostic instrumentation at each component boundary)
+5. Trace Data Flow backward through call stack
+
+Track each investigation step:
+
+```
+YOUR_AGENT_core op:loop_iterate
+```
+
+### Phase 2: Pattern Analysis
+
+1. Find Working Examples
+2. Compare Against References (read completely, don't skim)
+3. Identify Differences
+4. Understand Dependencies
+
+Search vault for working patterns to compare against:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<working feature similar to broken one>" }
+```
+
+### Phase 3: Hypothesis and Testing
+
+1. Form Single Hypothesis ("I think X is the root cause because Y")
+2. Test Minimally (one variable at a time)
+3. Verify Before Continuing
+4. When You Don't Know — say so, ask for help
+
+### Phase 4: Implementation
+
+1. Create Failing Test Case (use test-driven-development skill)
+2. Implement Single Fix (root cause only, one change at a time)
+3. Verify Fix
+4. If Fix Doesn't Work: count attempts. If < 3, return to Phase 1. If >= 3, STOP and question architecture.
+5. If 3+ Fixes Failed: Question Architecture — discuss with human partner before attempting more fixes.
+
+## Phase 5: Capture the Learning
+
+Complete the debug loop:
+
+```
+YOUR_AGENT_core op:loop_complete
+```
+
+**MANDATORY after every resolved bug.** A fix without a capture is an incomplete fix.
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<short bug description>",
+    description: "<root cause, solution, and what made it hard to find>",
+    type: "anti-pattern",
+    category: "<relevant domain>",
+    tags: ["<relevant>", "<tags>"]
+  }
+```
+
+For quick captures when the fix is straightforward:
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: {
+    title: "<bug description>",
+    description: "<root cause and fix>"
+  }
+```
+
+Capture a session summary:
+
+```
+YOUR_AGENT_core op:session_capture
+  params: { summary: "<bug, root cause, fix, files modified>" }
+```
+
+This is what makes the agent smarter over time. Next time someone hits a similar bug, Phase 0 vault search will surface your solution immediately.
+
+## Red Flags - STOP and Follow Process
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- Proposing solutions before tracing data flow
+- "One more fix attempt" (when already tried 2+)
+- Each fix reveals new problem in different place
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+## Common Rationalizations
+
+| Excuse                                       | Reality                                                                 |
+| -------------------------------------------- | ----------------------------------------------------------------------- |
+| "Issue is simple, don't need process"        | Simple issues have root causes too.                                     |
+| "Emergency, no time for process"             | Systematic is FASTER than guess-and-check thrashing.                    |
+| "Just try this first, then investigate"      | First fix sets the pattern. Do it right from the start.                 |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it.                       |
+| "Multiple fixes at once saves time"          | Can't isolate what worked. Causes new bugs.                             |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely.              |
+| "I see the problem, let me fix it"           | Seeing symptoms ≠ understanding root cause.                             |
+| "One more fix attempt" (after 2+ failures)   | 3+ failures = architectural problem. Question pattern, don't fix again. |
+| "Skip the vault, I know this one"            | The vault may know it better. 30 seconds to check saves hours.          |
+
+## Quick Reference
+
+| Phase                 | Key Activities                   | Agent Tools                                              |
+| --------------------- | -------------------------------- | -------------------------------------------------------- |
+| **0. Search First**   | Vault search, web search, memory | `search_intelligent`, `brain_strengths`, `memory_search` |
+| **1. Root Cause**     | Read errors, reproduce, trace    | `loop_iterate`                                           |
+| **2. Pattern**        | Find working examples, compare   | `search_intelligent`                                     |
+| **3. Hypothesis**     | Form theory, test minimally      | `loop_iterate`                                           |
+| **4. Implementation** | Create test, fix, verify         | `loop_iterate`                                           |
+| **5. Capture**        | Persist root cause, close loop   | `capture_knowledge`, `loop_complete`, `session_capture`  |
+
+## Agent Tools Reference
+
+| Op                   | When to Use                              |
+| -------------------- | ---------------------------------------- |
+| `search_intelligent` | Search vault for known bugs and patterns |
+| `brain_strengths`    | Check proven debugging patterns          |
+| `memory_search`      | Search across session memories           |
+| `loop_start`         | Begin iterative debug cycle              |
+| `loop_iterate`       | Track each investigation/fix attempt     |
+| `loop_complete`      | Finish debug cycle                       |
+| `capture_knowledge`  | Full anti-pattern capture                |
+| `capture_quick`      | Fast capture for simple fixes            |
+| `session_capture`    | Persist session context                  |
+
+**Related skills:**
+
+- test-driven-development
+- verification-before-completion
+- fix-and-learn (combines debugging + capture in one workflow)