@kl-c/matrixos 0.3.40 → 0.3.42

package/dist/skills/interview-me/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: interview-me
+description: Extracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists.
+source: addyosmani/agent-skills (MIT)
+---
+
+# Interview Me
+
+## Overview
+
+What people ask for and what they actually want are different things. They ask for "a dashboard" because that's what one asks for, not because a dashboard solves their problem. They say "make it faster" without a number to hit.
+
+The cheapest moment to find this gap is before any plan, spec, or code exists. Once you've started building, switching costs are real, and the user will rationalize the wrong thing into a "good enough" thing. The misfit gets locked in.
+
+This skill closes the gap before it costs anything. The other Define-phase skills assume you already know roughly what you want: `idea-refine` generates variations from an idea, `spec-driven-development` writes the requirements down, `doubt-driven-development` stress-tests a plan after you've drafted one. Interview-me is the part before all of those, where you ask one question at a time, with your best guess attached, until you can predict what the user is going to say before they say it.
+
+## When to Use
+
+Apply this skill when:
+
+- The ask is missing at least one of: **who** the user is, **why** they want it, what **success** looks like, what the binding **constraint** is
+- The request is conventional rather than specific ("build me X", "make it faster") and you can't unpack the convention without guessing
+- You're tempted to start with assumptions you haven't surfaced
+- The user hasn't said which value they're optimizing for when two reasonable ones are in tension (simplicity vs. flexibility, cost vs. speed)
+- The user explicitly invokes: "interview me", "grill me", "before we start, are we sure?", "stress-test my thinking"
+
+**When NOT to use:**
+
+- The ask is unambiguous and self-contained ("rename this variable", "fix this typo")
+- The user has explicitly asked for speed over verification
+- Pure information requests ("how does X work?", "what does this code do?")
+- Mechanical operations (renames, formats, file moves)
+- You already have ≥95% confidence; re-read the stop condition below before assuming you don't
+
+## Loading Constraints
+
+This skill needs a live, responsive user. **Do not invoke in non-interactive contexts** like CI pipelines, scheduled runs, `/loop`, or autonomous-loop. If you're in one of those and the ask is underspecified, flag that as a blocker for the user instead of guessing.
+
+## The Process
+
+### Step 1: Hypothesize, with a confidence number
+
+Before asking anything, write down your current best read of what the user wants in **one sentence**, plus an honest confidence number (0–100%):
+
+```
+HYPOTHESIS: You want a way to answer "how are we doing?" in standup, and "dashboard" was the convention that came to mind.
+CONFIDENCE: ~30% — missing: who it's for, what "metrics" means in context, and what success looks like
+```
+
+The number forces honesty. If you wrote down a high number but can't actually predict the user's reactions to the next three questions you'd ask, the number is wrong. Start at the confidence level you can defend.
+
+When confidence is below ~70%, append a brief reason on the same line — what's still unresolved or missing. This tells the user exactly what the interview needs to surface, and prevents the number from being a vague signal.
+
+### Step 2: Ask one question at a time, each with a guess attached
+
+Format:
+
+```
+Q: <one focused question>
+GUESS: <your hypothesis for the answer, with the reasoning that produced it>
+```
+
+Wait for the user to react before asking the next question.
+
+**Why one at a time, not a batch:**
+
+- The user can't react to your hypotheses if you bury them in a list
+- Batches encourage skim-reading and surface answers
+- The third question often depends on the answer to the first; asking them all at once locks in the wrong framing
+- The user's energy for thinking carefully is finite; spend it one question at a time
+
+**Why attach a guess:**
+
+- The user reacts faster to a wrong guess than they generate an answer from scratch
+- It commits you to a hypothesis you can be visibly wrong about, which keeps you honest
+- It surfaces *your* assumptions, which is what the interview is meant to expose
+
+The risk here is a polite user agreeing with your guess to be agreeable. Mitigate by being visibly willing to be wrong, and occasionally guess in a direction you expect the user to push back on.
+
+### Step 3: Listen for "want vs. should want"
+
+The most dangerous answers are the ones where the user says what a thoughtful answer *sounds like* rather than what they actually want. Watch for:
+
+- Answers that pattern-match best-practice talk ("I want it to be scalable", "clean architecture") without specifics
+- Answers that defer to convention ("the way most apps do it", "the standard approach")
+- Phrases like "I should probably…", "I think I'm supposed to…", "good engineering practice says…"
+- Buzzwords as goals — when "modern", "scalable", "robust" are the answer instead of a specific outcome
+
+When you hear these, the question to ask is:
+
+> *"If you didn't have to justify this to anyone, what would you actually want?"*
+
+That single question often does more work than the previous five.
+
+### Step 4: Restate intent in the user's own words
+
+When your confidence is high, write back what you now think the user wants. Keep it tight (5–8 lines), use their language where possible, and structure it so the user can confirm or correct line by line:
+
+```
+Here's what I now think you want:
+
+- Outcome:      <one line>
+- User:         <one line — who benefits>
+- Why now:      <one line — what changed>
+- Success:      <one line — how we know it worked>
+- Constraint:   <one line — the binding limit>
+- Out of scope: <one line — what we're explicitly not doing>
+
+Yes / no / refine?
+```
+
+Including "Out of scope" is non-negotiable. Half of misalignment is silent disagreement about what is *not* being built.
+
+### Step 5: Confirm — explicit yes, not "whatever you think"
+
+The gate is an explicit "yes." The following are **not** yes:
+
+- "Whatever you think is best." → The user is delegating, which means they don't have 95% confidence either. Re-ask with two concrete options framed as a choice.
+- "Sounds good." → Ambiguous. Ask: "Anything you'd refine?" Silence isn't confirmation.
+- "Sure, let's go." → Often a polite exit, not an endorsement. Same follow-up.
+- Silence followed by "okay let's start." → The user has given up on the interview, not converged. Stop and ask whether you've missed something.
+
+If they correct you, fold the correction in and restate. Loop until you get an explicit yes.
+
+### The 95% Confidence Stop
+
+You're done when you can answer yes to this:
+
+> *Can I predict the user's reaction to the next three questions I would ask?*
+
+If yes, you have shared understanding. Stop interviewing and produce the restate. If no, you're not done; ask the next question.
+
+This is a checkable test, not a vibe. It also has a floor: if you've gone several rounds and still can't predict, that's information about the ask, not a reason to keep grinding. Stop and tell the user: "I've asked X questions and I still can't predict your reactions. Something foundational is missing. Want to step back?"
+
+## Output
+
+The output of this skill is a **confirmed statement of intent**: the restate from Step 4, with an explicit yes from Step 5. That's the deliverable. Specs, plans, and task lists are downstream; they consume the intent this skill produces.
+
+If the user wants the intent to persist (a multi-session project, a handoff to another collaborator), offer to save it to `docs/intent/[topic].md`. Only save if they confirm.
+
+## Example
+
+A short before-and-after.
+
+**Without `interview-me`:**
+
+```
+User:  build me a dashboard for our metrics
+Agent: <starts proposing chart libraries and layouts>
+```
+
+The agent has assumed: who it's for, what metrics, what "for our team" means, what success looks like. None of these are stated. Every assumption is a place the user can later say "that's not what I meant."
+
+**With `interview-me`:**
+
+```
+User: build me a dashboard for our metrics
+
+Agent:
+HYPOTHESIS: You want a way to answer "how are we doing?" in standup, and "dashboard" came to mind because that's the conventional answer.
+CONFIDENCE: ~30% — missing: who it's for, what "metrics" are, and what success looks like
+
+Q:     When you say "how are we doing?", who's asking — you alone, the engineering team in standup, or up the chain (e.g., your manager, an exec, a board)?
+GUESS: engineering team in standup, because "we" usually scopes that way and standups are where this question gets asked. If it's for execs the metrics and the framing change a lot.
+
+User: It's actually for me. I keep losing track of which experiments are running and what their early signal looks like.
+
+Agent:
+Updated read: not a team dashboard at all. It's a personal experiment tracker. Confidence: ~60% — still missing: what "early signal" means and what done looks like.
+
+Q:     Is the gap that you don't know which experiments exist, or that you can't see their results in one place?
+GUESS: the second one. You have a list of experiments somewhere, but their results live in five different tools, and reconciling them by hand is what you're tired of.
+
+User: First one actually. I literally don't have a list. They're spread across different docs.
+
+Agent: <continues>
+```
+
+Two questions in, the agent has discovered the actual ask isn't "a dashboard." It's "a list." Different artifact, different scope, different work. The dashboard would have been wrong.
+
+## Interaction with Other Skills
+
+- **`idea-refine`**: downstream. If the confirmed intent is "I want X but I don't know how to scope it," hand off to `idea-refine` to generate variations against the now-explicit intent.
+- **`spec-driven-development`**: downstream. If the confirmed intent is concrete ("I want X for Y users with Z success criteria"), hand off to `spec-driven-development` to write it down.
+- **`planning-and-task-breakdown`**: two hops downstream of this skill (after the spec).
+- **`doubt-driven-development`**: opposite end of the timeline. Interview-me is pre-decision intent extraction; doubt-driven is post-decision artifact review. Both catch divergence, but at different moments.
+- **`source-driven-development`**: orthogonal. Interview-me clarifies what the user wants; SDD verifies framework facts. They don't compete.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The ask is clear enough" | If you can't write the user's desired outcome in one sentence right now, the ask isn't clear. Run Step 1 before deciding. |
+| "Asking too many questions wastes their time" | Time wasted by 4–6 targeted questions is small. Time wasted by building the wrong thing is enormous, and the user is the one bearing that cost. |
+| "I'll figure it out as I build" | Switching costs after code exists are 10x what they are now. Discovery during implementation is rework. |
+| "They said 'whatever you think,' so I should just decide" | "Whatever you think" is delegation, not decision. Re-ask with two concrete options as a choice. |
+| "I should give them several options to pick from" | Options work when the user knows what they want and is choosing between trade-offs. They don't know what they want yet. Listing options widens the search; asking narrows it. |
+| "If I attach my guess, I'm leading them" | Leading is the point. Reacting is faster than generating from scratch. The risk is sycophancy, not leading; mitigate by being visibly willing to be wrong. |
+| "We've talked enough, I get it" | Test it: can you predict their reaction to the next three questions? If not, you don't get it yet. |
+| "The user said yes, we're done" | If the yes followed a vague restate or an open-ended "sounds good," the yes is hollow. Restate concretely and re-confirm. |
+
+## Red Flags
+
+- Three or more questions in a single message: that's batching, not interviewing
+- A question without your hypothesis attached: that's surveying, not committing
+- Accepting "whatever you think is best" as a terminal answer
+- Producing a spec, plan, or task list before the user has explicitly confirmed your restate
+- Questions framed as "what would be best practice?" instead of "what do you actually want?"
+- The user gives a sophistication-signaling answer ("scalable", "clean", "modern") and you accept it without probing whether it's what they actually want
+- Three or more rounds without your confidence visibly rising: you're asking the wrong questions, step back and reframe
+- A confidence number below ~70% with no reason attached: the user can't help close the gap if they don't know what's missing
+- Saving the intent doc before the user has confirmed (the doc itself implies a yes the user didn't give)
+- Skipping the "Out of scope" line in the restate (silent disagreement about non-goals is half of misalignment)
+
+## Verification
+
+After applying interview-me:
+
+- [ ] An explicit hypothesis with a confidence number was stated in the first turn
+- [ ] Every confidence number below ~70% was accompanied by a one-line reason (what's still unresolved or missing)
+- [ ] Questions were asked one at a time, each with the agent's guess attached
+- [ ] At least one "what would you actually want if you didn't have to justify it?" probe ran when the user gave a sophistication-signaling or convention-signaling answer
+- [ ] A concrete restate (Outcome / User / Why now / Success / Constraint / Out of scope) was written back to the user
+- [ ] The user confirmed the restate with an explicit yes (not "whatever you think," not "sounds good," not silence)
+- [ ] At the stop point, the agent could predict reactions to the next three questions it would ask
+- [ ] Any handoff to a downstream skill (`idea-refine`, `spec-driven-development`) was framed in terms of the confirmed intent, not the original underspecified ask
+
+---
+*Source: addyosmani/agent-skills (MIT). Ported into MaTrixOS shared-skills bundle.*

package/dist/skills/observability-and-instrumentation/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: observability-and-instrumentation
+description: Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data.
+source: addyosmani/agent-skills (MIT)
+---
+
+# Observability and Instrumentation
+
+## Overview
+
+Code you can't observe is code you can't operate. Observability is the ability to answer "what is the system doing and why?" from the outside, using the telemetry the code emits. Instrumentation is not a post-launch add-on — it's written alongside the feature, the same way tests are. If a feature ships without telemetry, the first user-reported bug becomes archaeology instead of a query.
+
+## When to Use
+
+- Building any feature that will run in production
+- Adding a new service, endpoint, background job, or external integration
+- A production incident took too long to diagnose ("we couldn't tell what happened")
+- Setting up or reviewing alerting rules
+- Reviewing a PR that adds I/O, retries, queues, or cross-service calls
+
+**NOT for:**
+- Diagnosing a failure happening right now — use the `debugging-and-error-recovery` skill (observability is what makes that skill fast next time)
+- Profiling and optimizing measured slowness — use the `performance-optimization` skill
+- Launch-day monitoring checklists and rollback triggers — see the `shipping-and-launch` skill; this skill covers the instrumentation that feeds them
+
+## Process
+
+### 1. Define "working" before instrumenting
+
+Telemetry without a question is noise. Before adding any instrumentation, write down 2–4 questions an on-call engineer will ask about this feature:
+
+```
+FEATURE: checkout payment retry
+QUESTIONS ON-CALL WILL ASK:
+1. What fraction of payments succeed on first attempt vs after retry?
+2. When a payment fails permanently, why? (provider error? timeout? validation?)
+3. Is the payment provider slower than usual?
+→ Every signal below must help answer one of these.
+```
+
+If you can't name the questions, you're not ready to instrument — you'll log everything and learn nothing.
+
+### 2. Pick the right signal for each question
+
+| Signal | Answers | Cost profile | Example |
+|---|---|---|---|
+| **Structured log** | "What happened in this specific case?" | Per-event; grows with traffic | `payment_failed` with provider error code |
+| **Metric** | "How often / how fast, in aggregate?" | Fixed per series; cheap to query | p99 latency of provider calls |
+| **Trace** | "Where did time go across services?" | Per-request; usually sampled | One slow checkout, broken down by hop |
+
+Rule of thumb: metrics tell you **that** something is wrong, traces tell you **where**, logs tell you **why**.
+
+### 3. Structured logging
+
+Log events, not prose. Every log line is a JSON object with a stable event name and machine-readable fields:
+
+```typescript
+// BAD: string interpolation — unqueryable, inconsistent
+logger.info(`Payment ${id} failed for user ${userId} after ${n} retries`);
+
+// GOOD: stable event name + structured fields
+logger.warn({
+  event: 'payment_failed',
+  paymentId: id,
+  provider: 'stripe',
+  errorCode: err.code,
+  attempt: n,
+}, 'payment failed');
+```
+
+**Log levels — use them consistently:**
+
+| Level | Meaning | On-call action |
+|---|---|---|
+| `error` | Invariant broken; someone may need to act | Investigate |
+| `warn` | Degraded but handled (retry succeeded, fallback used) | Watch for trends |
+| `info` | Significant business event (order placed, job finished) | None |
+| `debug` | Diagnostic detail | Off in production by default |
+
+**Correlation IDs are mandatory.** Generate (or accept) a request ID at the system boundary and attach it to every log line, span, and outbound call. Without it, you cannot reconstruct a single request from interleaved logs:
+
+```typescript
+// Express: child logger per request, ID propagated downstream
+app.use((req, res, next) => {
+  req.id = req.headers['x-request-id'] ?? crypto.randomUUID();
+  req.log = logger.child({ requestId: req.id });
+  res.setHeader('x-request-id', req.id);
+  next();
+});
+```
+
+**Never log secrets, tokens, passwords, or full PII.** This is a hard rule from the `security-and-hardening` skill — telemetry pipelines are a classic data-leak path. Allowlist fields; don't log whole request bodies.
+
+### 4. Metrics
+
+For request-driven services, instrument **RED** on every endpoint and every external dependency: **R**ate (requests/sec), **E**rrors (failure rate), **D**uration (latency histogram, not average). For resources (queues, pools, hosts), use **USE**: **U**tilization, **S**aturation, **E**rrors.
+
+As with tracing, the vendor-neutral path is the OpenTelemetry metrics API (same SDK and context as step 5). The example below uses Prometheus' `prom-client` — one common backend choice, not the only one; the RED/USE and cardinality rules are identical either way.
+
+```typescript
+import { Histogram } from 'prom-client';
+
+const httpDuration = new Histogram({
+  name: 'http_request_duration_seconds',
+  help: 'HTTP request duration',
+  labelNames: ['method', 'route', 'status_class'],  // '2xx', not '200'
+  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+});
+```
+
+**Cardinality is the failure mode.** Every unique label combination is a separate time series. Labels must come from small, fixed sets (route template, status class, provider name). Never use user IDs, raw URLs, error messages, or other unbounded values as labels — that belongs in logs and traces.
+
+```
+OK as label:    route="/api/tasks/:id"   status_class="5xx"   provider="stripe"
+NEVER a label:  user_id, email, request_id, full URL, error message text
+```
+
+Track averages never, percentiles always: an average hides the 1% of users having a terrible time. Use histograms and read p50/p95/p99.
+
+### 5. Distributed tracing
+
+Use OpenTelemetry — it's the vendor-neutral standard, and auto-instrumentation covers HTTP, gRPC, and common DB clients with near-zero code:
+
+```typescript
+// tracing.ts — must be imported before anything else
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+const sdk = new NodeSDK({
+  serviceName: 'checkout-service',
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+sdk.start();
+```
+
+Add manual spans only around meaningful internal units of work (e.g., `applyDiscounts`, `chargeProvider`) and attach the attributes on-call will filter by. Propagate context across every async boundary — HTTP headers, queue message metadata — or the trace dies at the gap. Sample head-based at a low rate by default; keep 100% of errors if your backend supports tail sampling.
+
+### 6. Alerting
+
+Alert on **symptoms users feel**, not on causes:
+
+```
+SYMPTOM (page-worthy):           CAUSE (dashboard, not a page):
+error rate > 1% for 5 min        CPU at 85%
+p99 latency > 2s                 one pod restarted
+queue age > 10 min               disk at 70%
+```
+
+Cause-based alerts fire when nothing is wrong and miss failures you didn't predict. Symptom-based alerts fire exactly when users are hurt, regardless of the cause.
+
+Rules for every alert you create:
+
+1. **It must be actionable.** If the response is "ignore it, it self-heals", delete the alert.
+2. **It links to a runbook** — even three lines: what it means, first query to run, escalation path.
+3. **It has a threshold and duration** justified by the SLO or by historical data, not by a guess.
+4. Use two severities only: **page** (user-facing, act now) and **ticket** (degradation, act this week). A third tier becomes noise that trains people to ignore everything.
+
+### 7. Verify the telemetry itself
+
+Instrumentation is code; it can be wrong. Before calling the work done, trigger the paths and look at the actual output:
+
+- Force an error in staging → find it in the logs by `requestId`, confirm fields are structured (not `[object Object]`)
+- Send test traffic → confirm metric series appear with the expected labels and sane values
+- Follow one request across services in the tracing UI → no broken spans
+- Fire each new alert once (lower the threshold temporarily) → confirm it reaches the right channel and the runbook link works
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll add logging after it works" | "After" becomes "after the first incident", which is the most expensive moment to discover you're blind. Instrument as you build. |
+| "More logs = more observability" | Unstructured noise makes incidents slower, not faster. Three queryable events beat three hundred prose lines. |
+| "console.log is fine for now" | Unstructured output can't be filtered, correlated, or alerted on. The structured logger costs five extra minutes once. |
+| "We can just look at the dashboards when something breaks" | Dashboards built without defined questions show you everything except the answer. Start from on-call questions. |
+| "Alert on everything important, we'll tune later" | A noisy pager trains people to ignore it. The tuning never happens; the missed real page does. |
+| "User ID as a metric label makes debugging easier" | It also makes your metrics backend fall over. High-cardinality lookups belong in logs and traces. |
+| "Tracing is overkill for our two services" | Two services already means cross-service latency questions logs can't answer. Auto-instrumentation makes the cost trivial. |
+
+## Red Flags
+
+- A feature PR with retries, queues, or external calls and zero new telemetry
+- Log lines built by string interpolation instead of structured fields
+- No correlation/request ID — each log line is an orphan
+- Metrics labeled with user IDs, raw URLs, or error message text (cardinality bomb)
+- Latency tracked as an average with no percentiles
+- Alerts that fire daily and get acknowledged without action
+- Alerts on causes (CPU, memory) paging humans while user-facing error rate is unmonitored
+- Secrets, tokens, or full request bodies appearing in logs
+- "It works on my machine" as the only evidence a production feature is healthy
+
+## Verification
+
+After instrumenting a feature, confirm:
+
+- [ ] The on-call questions for this feature are written down, and each signal maps to one
+- [ ] All log output is structured (JSON), with stable event names and a correlation ID on every line
+- [ ] No secrets, tokens, or unredacted PII in any log line (spot-check actual output)
+- [ ] RED metrics exist for every new endpoint and every external dependency, with bounded label sets
+- [ ] Latency is a histogram; p95/p99 are queryable
+- [ ] A single request can be followed end-to-end in the tracing UI without broken spans
+- [ ] Every new alert is symptom-based, has a runbook link, and was test-fired once
+- [ ] An induced failure in staging was located via telemetry alone, without reading the source
+
+For the at-a-glance version of this list, including the pre-launch instrumentation gate, see `references/observability-checklist.md`.
+
+---
+*Source: addyosmani/agent-skills (MIT). Ported into MaTrixOS shared-skills bundle.*