@nt-ai-lab/opencode-skillz 0.2.7 → 0.2.8

package/AGENTS.md

@@ -11,6 +11,7 @@ Purpose: package OpenCode workflow assets as a plugin.
 ## Conventions
 
 - Keep command files process-oriented (not tone-oriented).
+- Remove all personality from commands and skill content when creating them.
 - Put voice and persona behavior in agent prompts.
 - Treat reusable skill content as command templates in `commands/`.
 - Commands should be manually invoked by default.

package/commands/confidence-honesty.md

@@ -0,0 +1,245 @@
+---
+description: "Force honest confidence assessment before claiming conclusions. Triggers on 'root cause identified', 'problem identified', 'complete clarity'. Express confidence as percentage, explain what's stopping 100%, validate assumptions before presenting."
+---
+
+# Confidence Honesty
+
+## The Problem
+
+Detailed, well-structured analyses can *look* thorough, then get presented with phrases like "complete clarity" or "root cause identified." Users reasonably trust that confidence. They act on it, communicate it to stakeholders, and make decisions.
+
+Then new evidence appears and invalidates the entire hypothesis.
+
+**The harm:**
+- User trusted a conclusion that was actually ~40% confident
+- Time wasted on wrong direction
+- Stakeholders were misinformed
+- Trust in the analysis erodes
+
+**Why this happens:** Explanation quality gets conflated with evidence quality. A thorough, well-reasoned analysis feels like certainty—but reasoning without verified evidence is just speculation with extra steps.
+
+## The Solution
+
+Force explicit confidence assessment before claiming conclusions:
+1. Express confidence as a percentage (not vague certainty)
+2. Show the math: what evidence adds confidence, what gaps subtract it
+3. Mandatory "Why not 100%?" for anything below 95%
+4. Self-validate: if more evidence can be gathered directly, do it before presenting
+
+## Critical Rules
+
+🚨 **EXPRESS CONFIDENCE AS A PERCENTAGE.** Every conclusion needs a specific confidence level, not vague certainty.
+
+🚨 **EXPLAIN WHAT'S STOPPING 100%.** For any confidence below 95%, you MUST explain the gaps. Non-negotiable.
+
+🚨 **VALIDATE BEFORE PRESENTING.** If more evidence can be gathered directly, DO IT. Do not present unvalidated hypotheses.
+
+## When This Triggers
+
+Auto-invoke when about to claim:
+- "root cause is", "the problem is", "root cause identified"
+- "complete clarity", "definitely", "certainly", "clearly the issue"
+- Any conclusive claim during investigation
+
+## Confidence Levels
+
+| Range | Icon | Meaning |
+|-------|------|---------|
+| 0-30% | 🔴 | Speculation - needs significant validation |
+| 31-60% | 🟡 | Plausible - evidence exists but gaps remain |
+| 61-85% | 🟠 | Likely - strong evidence, minor gaps |
+| 86-94% | 🟢 | High confidence - validated, minor uncertainty |
+| 95-100% | 💯 | Confirmed - fully validated |
+
+**Calibration:**
+- **20%**: One possibility among several
+- **40%**: Evidence points this direction but key assumptions unverified
+- **60%**: Evidence supports this, alternatives not ruled out
+- **80%**: Strong evidence, assumptions verified, alternatives less likely
+- **95%**: Validated with direct evidence, alternatives ruled out
+- **100%**: Mathematical/logical certainty only
+
+## Pre-Conclusion Checkpoint
+
+**Before claiming ANY conclusion, complete this:**
+
+### 1. Evidence Inventory
+- What hard evidence supports this?
+- Direct evidence (code/logs that prove it)?
+- Circumstantial evidence (patterns consistent)?
+- What's the strongest piece of evidence?
+
+### 2. Falsifiability Check
+- What would INVALIDATE this theory?
+- What data would prove me wrong?
+- Has that data been checked?
+- If no: WHY NOT?
+
+### 3. Assumption Audit
+- What is being assumed WITHOUT verification?
+- List each assumption explicitly
+- Mark: [VERIFIED] or [ASSUMED]
+
+### 4. Alternative Possibilities
+- What else could explain these symptoms?
+- List at least 2 alternatives
+- Why is my conclusion more likely?
+
+### 5. Validation Opportunities
+- Can the actual data be fetched/checked?
+- Can the codebase be searched for confirming/denying evidence?
+- Should the user be asked for confirming data?
+
+## Confidence Scoring
+
+**Start at 50% (neutral) and adjust:**
+
+| Factor | Adjustment |
+|--------|------------|
+| Direct evidence (code/logs proving it) | +15-25% |
+| Verified assumptions (checked, not assumed) | +10-15% |
+| Alternatives ruled out with evidence | +10-15% |
+| Falsifiability check completed | +5-10% |
+| Unverified critical assumptions | -15-25% |
+| Plausible alternatives not ruled out | -10-15% |
+| No falsifiability check | -10% |
+| Circumstantial evidence only | -10% |
+
+**Example calculation:**
+```
+Starting: 50%
++ Code analysis shows the pattern: +15%
++ Error logs match signature: +10%
+- CRITICAL: Assumed config unchanged (NOT VERIFIED): -25%
+- Alternative not ruled out: -10%
+
+Final: 40% 🟡
+```
+
+## Response Format
+
+```
+[Icon] [X%] Confidence: [One sentence finding]
+
+Evidence:
+- [+X%] [Evidence 1]
+- [+X%] [Evidence 2]
+
+Why not 100%:
+- [-X%] [What's stopping full confidence]
+
+To increase confidence: [What would raise % - can be checked directly or needs user input]
+```
+
+## Examples
+
+### 🔴 25% - Low confidence
+```
+🔴 25% Confidence: Database connection pool may be exhausted
+
+Evidence:
+- [+15%] Error pattern matches connection timeout
+- [+10%] Load spike occurred around failure time
+
+Why not 100%:
+- [-25%] Haven't verified actual pool metrics
+- [-15%] Haven't ruled out: network issues, DNS problems
+- [-35%] This is mostly pattern matching, not direct evidence
+
+To increase confidence: Connection pool metrics from the time of failure are needed.
+```
+
+### 🟠 75% - Moderate-high confidence
+```
+🟠 75% Confidence: API request failing due to missing required field
+
+Evidence:
+- [+20%] Error message explicitly mentions "field required"
+- [+15%] Code path analysis shows validation happens here
+- [+10%] Field was recently added to validation rules
+
+Why not 100%:
+- [-10%] Haven't verified the actual request payload
+- [-15%] Could be a different field than suspected
+
+To increase confidence: Check the actual request payload from the failing call.
+```
+
+### 💯 98% - Near certain
+```
+💯 98% Confidence: Root cause is misconfigured environment variable
+
+Evidence:
+- [+25%] Environment variable is set to wrong value (verified)
+- [+20%] Code directly uses this variable for the failing operation
+- [+15%] Error message matches expected failure mode
+- [+10%] Fixing the variable in staging resolved the issue
+
+Why not 100%: Haven't deployed fix to production yet to confirm.
+```
+
+## Anti-Patterns
+
+### ❌ Premature Certainty
+
+**What happens:**
+```
+Analysis: "Complete clarity on the root cause"
+Assistant: [200 lines of detailed report]
+User: [provides data that contradicts analysis]
+Assistant: "This changes everything..."
+```
+
+**What should happen:**
+```
+🟡 40% Confidence: The issue appears to be X
+
+Evidence:
+- [+15%] Code path analysis suggests this pattern
+
+Why not 100%:
+- [-25%] CRITICAL: Haven't verified actual system state
+- [-15%] Alternative not ruled out
+
+To increase confidence: Provide [specific data], or check it directly if available.
+```
+
+### ❌ Confidence in Explanation Quality
+
+Building a detailed report ≠ having valid evidence.
+
+Thoroughness of presentation has zero correlation with correctness.
+
+**Violation sign:** "Complete clarity" based on reasoning, not evidence.
+
+### ❌ Skipping Falsifiability
+
+If the question "what would prove this wrong?" cannot be answered, the theory is not understood well enough.
+
+## Self-Validation Rule
+
+**Do not return to the user with questions that can be answered directly.**
+
+Before presenting, ask:
+```
+Can more evidence be gathered directly?
+├─ Search codebase for confirming/denying data?
+├─ Fetch a file that validates an assumption?
+├─ Spawn an agent to investigate further?
+└─ Check actual state vs assumed state?
+
+If YES → DO IT. Then reassess confidence.
+If NO → Present with honest confidence + what is needed from the user.
+```
+
+**Critical:** If confidence is below 80% and more evidence can be gathered directly → DO IT.
+
+## Summary
+
+🚨 **Confidence is a percentage, not a feeling.**
+
+🚨 **Below 95%? Explain what's stopping 100%.**
+
+🚨 **Can validate yourself? Do it before presenting.**
+
+The goal: Never claim "complete clarity" with 40% confidence and unverified assumptions.

package/commands/investigate.md

@@ -0,0 +1,153 @@
+---
+description: Investigate technical problems systematically with evidence-first methods and explicit confidence reporting
+compose_after: confidence-honesty
+---
+
+Apply this command to:
+$ARGUMENTS
+
+# Technical Investigator
+
+Investigate technical problems systematically. Do not guess—gather evidence until the problem is understood.
+
+### Core Principles
+
+**Solve the right problem.** Before investigating, be crystal clear about the problem being solved. Restate it. Verify understanding. A thorough answer to the wrong question is worthless. Keep asking: "Has the requested problem actually been solved?"
+
+**Observability is the answer.** When system behavior is unclear, add instrumentation. Logs, metrics, traces, and debug output make the invisible visible. If guessing is still happening, observability is insufficient.
+
+**Thoroughness over speed.** Do not rush to conclusions. Build a detailed picture of the problem—every component, every interaction, every timeline. Shallow investigation leads to wrong answers and repeated work.
+
+**Evidence, not assumptions.** Every conclusion needs supporting evidence. Show the work. If no supporting data exists, the investigation is incomplete.
+
+**Do the work.** Investigation is labor. Run the queries, read the logs, trace the requests, add the instrumentation. There are no shortcuts to understanding.
+
+**Starting an investigation:**
+- Define the problem precisely—what's expected vs what's happening
+- Gather existing data before forming hypotheses
+- Build a timeline of events with specific timestamps
+- Identify unknowns (gaps in observability)
+
+**When investigation hits a wall:**
+- Add more observability—logs, metrics, debug output
+- Don't guess—instrument and measure
+- State what instrumentation is needed to understand the unknown
+- Never present unproven claims as facts
+
+**Before concluding:**
+- Ask: "Has the original problem actually been solved?"
+- Verify your answer addresses what was asked
+- Don't settle for partial answers or adjacent solutions
+- If the problem is not fully solved, say so and continue
+
+**Forming conclusions:**
+- Hypotheses must be testable
+- Show the evidence chain
+- Distinguish correlation from causation
+- Verify fixes actually work—don't assume
+
+## Core Investigation Methodologies
+
+### 1. Scientific Method (Hypothesis-Driven)
+
+**The Process:**
+1. **Observe**: Gather data, identify patterns, note anomalies
+2. **Hypothesize**: Form testable explanations for the observed evidence
+3. **Experiment**: Design specific tests to validate/invalidate hypotheses
+4. **Evaluate**: Analyze results, adjust hypotheses, iterate
+
+**Key Principles:**
+- Make assumptions explicit—never leave reasoning implicit
+- Create falsifiable hypotheses that can be tested with specific experiments
+- Follow the "10-minute rule": If ad-hoc inspection hasn't found the issue in 10 minutes, switch to systematic investigation
+- Document your reasoning chain so others can follow your logic
+
+### 2. Google SRE Practices
+
+**Incident Response:**
+- Mitigation first, understanding second (when systems are down)
+- Declare incidents early—don't wait for certainty
+- Maintain working records in real-time during investigation
+- Use persistent communication channels as investigation logs
+
+**Observability:**
+- Monitor the "Four Golden Signals": Latency, Traffic, Errors, Saturation
+- Leverage three pillars: Metrics (trends), Logs (sequences), Traces (components)
+- Accept that future problems cannot be predicted—build systems to investigate the unknown
+- Focus on high-cardinality data for distributed systems
+
+### 3. Root Cause Analysis
+
+**Techniques:**
+- **5 Whys**: Ask "why" iteratively to uncover root causes (typically 5 levels deep)
+- **Timeline Analysis**: Build detailed timelines with specific events and timestamps
+- **Fault Tree Analysis**: Visual hierarchical breakdown of failure scenarios
+- **Correlation vs Causation**: Distinguish between things that happen together vs things that cause each other
+
+**Principles:**
+- Symptoms are not causes—keep digging
+- Root causes often involve multiple contributing factors
+- Document evidence that supports your causal chain
+- Verify root cause fixes actually prevent recurrence
+
+### 4. Performance Analysis (USE Method)
+
+Apply Brendan Gregg's systematic bottleneck identification:
+
+**USE Method:**
+- **Utilization**: How busy is the resource (% time doing work)?
+- **Saturation**: How much work is queued/waiting?
+- **Errors**: Count of error events
+
+**Application:**
+- Apply to all resources: CPU, memory, disk, network, database connections, etc.
+- Systematic investigation prevents missing bottlenecks
+- Collect baseline measurements to compare against
+- Focus on resources with high utilization AND high saturation
+
+## Investigation Workflow
+
+### Phase 1: Problem Definition
+- Define the problem statement clearly and specifically
+- Identify what changed (if known)
+- Establish baseline/expected behavior
+- Determine impact and urgency
+
+### Phase 2: Data Gathering
+- Collect metrics: trends, patterns, anomalies
+- Review logs: event sequences, errors, warnings
+- Analyze traces: component interactions, latency distribution
+- Query databases: aggregate data, identify outliers
+- Check monitoring dashboards: Four Golden Signals
+
+### Phase 3: Hypothesis Formation
+- Based on data, form 2-4 testable hypotheses
+- Make assumptions explicit
+- Rank hypotheses by likelihood and test cost
+- Document expected outcomes for each hypothesis
+
+### Phase 4: Experimentation
+- Design specific tests to validate/invalidate hypotheses
+- Run experiments systematically (one variable at a time when possible)
+- Document results meticulously
+- Adjust hypotheses based on findings
+
+### Phase 5: Documentation
+- Build comprehensive timelines
+- Document evidence chain
+- Record reasoning and decision points
+- Create actionable findings
+
+### Investigation Documentation
+
+**Real-Time Records:**
+- Document during the investigation, not after
+- Record hypotheses and reasoning
+- Note dead ends—they prevent others from repeating them
+- Build detailed timelines with timestamps
+
+**Sharing Findings:**
+- Present evidence clearly
+- Show your reasoning chain
+- Be direct about confidence levels
+- Admit uncertainty when appropriate

package/index.js

@@ -40,10 +40,15 @@ function readMarkdownFiles(dirPath) {
     .sort((a, b) => a.localeCompare(b))
 }
 
+function normalizeCommandReference(value) {
+  if (!value || typeof value !== "string") return ""
+  return value.trim().replace(/_/g, "-")
+}
+
 function loadCommands() {
   const commandsDir = path.join(pluginRoot, "commands")
   const files = readMarkdownFiles(commandsDir)
-  const commands = {}
+  const rawCommands = {}
 
   for (const file of files) {
     const name = file.replace(/\.md$/, "")
@@ -51,9 +56,47 @@ function loadCommands() {
     const content = fs.readFileSync(fullPath, "utf8")
     const { meta, body } = extractFrontmatter(content)
 
+    rawCommands[name] = {
+      meta,
+      body: body.trim(),
+    }
+  }
+
+  const commands = {}
+
+  function buildComposedTemplate(name, stack = new Set()) {
+    const rawCommand = rawCommands[name]
+    if (!rawCommand) return ""
+    if (stack.has(name)) return rawCommand.body
+
+    stack.add(name)
+
+    let template = rawCommand.body
+    const composeAfterName = normalizeCommandReference(rawCommand.meta.compose_after)
+    const composedCommand = rawCommands[composeAfterName]
+
+    if (composeAfterName && composedCommand) {
+      const composedTemplate = buildComposedTemplate(composeAfterName, stack)
+      if (composedTemplate) {
+        template = [
+          template,
+          `In addition you must adhere to the following:\n\n${composedTemplate}`,
+        ]
+          .filter(Boolean)
+          .join("\n\n")
+      }
+    }
+
+    stack.delete(name)
+
+    return template.trim()
+  }
+
+  for (const [name, rawCommand] of Object.entries(rawCommands)) {
+    const { meta } = rawCommand
     const command = {
       description: meta.description || `Run /${name}`,
-      template: body.trim(),
+      template: buildComposedTemplate(name),
     }
 
     if (meta.agent) command.agent = meta.agent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nt-ai-lab/opencode-skillz",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Bundled OpenCode commands and agents",
   "type": "module",
   "main": "index.js",