create-yss-spec 2.2.9 → 3.0.0

package/template/.codex/skills/product-design/skills/research/assets/evidence-template.yaml

@@ -0,0 +1,65 @@
+{
+  "schema_version": 1,
+  "mode": "evidence-audited",
+  "scope": {
+    "product": "<product>",
+    "audience": "<audience>",
+    "time_horizon": "<time horizon>",
+    "research_questions": ["<question>"],
+    "inclusion_criteria": ["<criterion>"],
+    "exclusion_criteria": ["<criterion>"]
+  },
+  "search_log": [
+    {
+      "id": "search-001",
+      "channel": "<channel or corpus>",
+      "query_or_corpus": "<query or inspected material>",
+      "searched_at": "YYYY-MM-DD",
+      "result": "results-found"
+    },
+    {
+      "id": "search-002",
+      "channel": "<channel searched for disconfirming evidence>",
+      "query_or_corpus": "<counter-signal query>",
+      "searched_at": "YYYY-MM-DD",
+      "result": "none-found"
+    }
+  ],
+  "evidence_items": [
+    {
+      "id": "evidence-001",
+      "visibility": "public",
+      "source_level": "primary",
+      "source_class": "<issue, forum, review, metric, docs, interview, support>",
+      "source_ref": "<URL or internal reference>",
+      "locator": "<section, issue comment, timestamp, or other precise locator>",
+      "stance": "support",
+      "observed_at": "YYYY-MM-DD",
+      "evidence_date": "YYYY-MM-DD",
+      "observation": "<what the source directly shows>",
+      "freshness": "current",
+      "limitations": []
+    }
+  ],
+  "claims": [
+    {
+      "id": "claim-001",
+      "problem_id": "problem-001",
+      "claim_kind": "problem-exists",
+      "statement": "<decision-bearing claim>",
+      "severity": "high",
+      "frequency_signal": "anecdotal",
+      "confidence": "medium",
+      "evidence_refs": ["evidence-001"],
+      "counter_signal_refs": ["search-002"],
+      "audit_status": "supported",
+      "disposition": "publish"
+    }
+  ],
+  "source_gaps": [],
+  "audit_summary": {
+    "status": "complete",
+    "audited_claim_ids": ["claim-001"],
+    "notes": []
+  }
+}

package/template/.codex/skills/product-design/skills/research/assets/research-brief-template.md

@@ -0,0 +1,33 @@
+# <Product> UX Research Brief
+
+## Research Scope
+
+- Mode: `evidence-audited`
+- Audience:
+- Time horizon:
+- Scope:
+- Access limitations:
+
+## Executive Read
+
+Summarize the product story in 5–7 sentences.
+
+## Ranked UX Problems
+
+For each problem, cover the user goal, surface, breakage, evidence, severity, frequency signal, confidence, recommended move, and its key claim IDs (`claim-*`).
+
+## Source Map
+
+Explain what was searched, what each source class contributed, exclusions, failed access, and weak-signal areas.
+
+## Opportunity Map
+
+### Fix This Week
+
+### Fix This Quarter
+
+### Needs Deeper Research
+
+## Evidence Limitations
+
+State coverage gaps, conflicting evidence, counter-signals, and conclusions that were narrowed or withheld.

package/template/.codex/skills/product-design/skills/research/references/evidence-audited.md

@@ -0,0 +1,80 @@
+# Evidence-Audited UX Research
+
+Use this protocol only when the caller explicitly selects `evidence-audited` mode. The goal is an auditable UX brief, not an academic literature review.
+
+## 1. Search plan
+
+Before searching, declare:
+
+- product, audience, time horizon, geography or platform boundaries, and research questions;
+- source classes likely to carry direct user or product evidence;
+- inclusion and exclusion criteria;
+- known access limits, including unavailable internal sources.
+
+Search user-provided and saved material first. Apply the same inclusion and exclusion criteria to supplied and externally discovered material. Search externally to fill gaps, check recency, and seek disconfirming evidence. Record unsuccessful searches and access failures; they bound the conclusion.
+
+## 2. Search Log
+
+Record every material search with its channel, query or inspected corpus, execution date, scope, and result. A zero-result search is still a result. Do not claim that a channel was searched when only an aggregator snippet was inspected.
+
+## 3. Evidence Ledger
+
+Create one evidence item per independently locatable observation. Each item records:
+
+- a stable ID;
+- public or internal visibility, source class, and source level (`primary`, `direct-experience`, `near-primary`, `secondary`, or `lead-only`);
+- source URL or internal reference plus a precise locator;
+- observation date and publication/event date when available;
+- whether the item supports or counters the mapped claim;
+- the observed evidence, without interpretation;
+- freshness and access limitations.
+
+Keep inference in claims, not in evidence observations. Short quotations may support location and meaning, but respect source quotation limits.
+
+## 4. Key-claim audit
+
+Audit the decision-bearing claims for each ranked problem rather than every sentence:
+
+1. the problem exists;
+2. the asserted impact;
+3. the frequency characterization;
+4. the evidence basis for the recommended product move.
+
+For every high-severity problem, audit all four claim kinds. For lower-severity problems, audit at least one `primary` supporting item and one counter-signal. `lead-only` items may guide discovery but cannot support a claim. When no counter-signal is found, reference a Search Log entry whose result is `none-found`; absence of a found counter-signal is not proof that none exists.
+
+Use these audit outcomes:
+
+- `supported`: cited evidence directly supports the claim as worded;
+- `partially-supported`: evidence supports a narrower or qualified claim;
+- `unsupported`: evidence does not support the claim;
+- `not-audited`: allowed only before the audit is complete.
+
+Every evidence reference must resolve to a ledger item. The audit checks support, not merely citation existence.
+
+## 5. Frequency and confidence
+
+Describe frequency as one of:
+
+- `measured`: backed by a relevant dataset or metric;
+- `repeated-independent`: repeated across independent sources, without a population-rate claim;
+- `anecdotal`: one or a small number of reports;
+- `unknown`: the available evidence cannot characterize frequency.
+
+Rank confidence from source directness, independence, recency, access quality, and counter-signals. Do not raise confidence merely because several posts repeat the same upstream report.
+
+## 6. Failure and downgrade policy
+
+- Ordinary access gaps or conflicting evidence do not block the brief. Surface the gap and lower confidence.
+- A partially supported claim must be narrowed and use disposition `qualify`.
+- An unsupported key claim, fabricated or mismatched citation, or unverified source identity must not be presented as certain. Use disposition `needs-deeper-research`.
+- A persisted package fails when its structure is invalid, references do not resolve, lower-severity problems lack primary support, a high-severity claim was not audited, or the report claims completion while an audit remains `not-audited`.
+
+## 7. Persistence
+
+Persist only on explicit request. Use adjacent `<slug>-research-brief.md` and `<slug>-evidence.yaml` files. The evidence file uses JSON syntax, which is valid YAML 1.2, so the bundled validator can parse it without an external YAML dependency.
+
+The Markdown brief must mention every key-claim ID and contain the headings required by the template. The evidence file remains the source of truth for search execution, claim-to-evidence mapping, audit state, gaps, and counter-signals.
+
+## Design provenance
+
+This protocol adapts two engineering patterns from [Academic Research Skills](https://github.com/Imbad0202/academic-research-skills): its Material Passport-style provenance chain and claim-to-reference alignment audit. The UX workflow deliberately omits academic writing, publication, agent-team, and cross-model review machinery.

package/template/.codex/skills/product-design/skills/research/scripts/validate-research-package.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const SOURCE_LEVELS = ["primary", "direct-experience", "near-primary", "secondary", "lead-only"];
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function requireString(value, label) {
+  if (typeof value !== "string" || !value.trim()) fail(`${label} must be a non-empty string`);
+}
+
+function requireArray(value, label, { nonEmpty = false } = {}) {
+  if (!Array.isArray(value) || (nonEmpty && value.length === 0)) fail(`${label} must be ${nonEmpty ? "a non-empty" : "an"} array`);
+}
+
+function uniqueIds(items, label) {
+  const ids = new Set();
+  items.forEach((item, index) => {
+    requireString(item?.id, `${label}[${index}].id`);
+    if (ids.has(item.id)) fail(`${label} contains duplicate id: ${item.id}`);
+    ids.add(item.id);
+  });
+  return ids;
+}
+
+function requireChoice(value, choices, label) {
+  if (!choices.includes(value)) fail(`${label} must be one of: ${choices.join(", ")}`);
+}
+
+function parseEvidence(file) {
+  let value;
+  try {
+    value = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    fail(`${path.basename(file)} must use JSON-compatible YAML 1.2 syntax: ${error.message}`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("evidence root must be an object");
+  return value;
+}
+
+function validate(briefFile, evidenceFile) {
+  if (!briefFile || !evidenceFile) fail("usage: validate-research-package.mjs <brief.md> <evidence.yaml>");
+  const briefPath = path.resolve(briefFile);
+  const evidencePath = path.resolve(evidenceFile);
+  if (path.dirname(briefPath) !== path.dirname(evidencePath)) fail("brief and evidence files must be adjacent");
+  if (!briefPath.endsWith("-research-brief.md") || !evidencePath.endsWith("-evidence.yaml")) fail("expected <slug>-research-brief.md and <slug>-evidence.yaml");
+  const briefSlug = path.basename(briefPath, "-research-brief.md");
+  const evidenceSlug = path.basename(evidencePath, "-evidence.yaml");
+  if (!briefSlug || briefSlug !== evidenceSlug) fail("brief and evidence files must use the same non-empty slug");
+
+  const brief = readFileSync(briefPath, "utf8");
+  const headings = ["Research Scope", "Executive Read", "Ranked UX Problems", "Source Map", "Opportunity Map", "Evidence Limitations"];
+  headings.forEach((heading) => {
+    if (!brief.includes(`## ${heading}`)) fail(`brief is missing heading: ## ${heading}`);
+  });
+
+  const evidence = parseEvidence(evidencePath);
+  if (evidence.schema_version !== 1) fail("schema_version must be 1");
+  if (evidence.mode !== "evidence-audited") fail("mode must be evidence-audited");
+  ["product", "audience", "time_horizon"].forEach((field) => requireString(evidence.scope?.[field], `scope.${field}`));
+  ["research_questions", "inclusion_criteria", "exclusion_criteria"].forEach((field) => requireArray(evidence.scope?.[field], `scope.${field}`, { nonEmpty: true }));
+
+  requireArray(evidence.search_log, "search_log", { nonEmpty: true });
+  const searchIds = uniqueIds(evidence.search_log, "search_log");
+  const searchesById = new Map(evidence.search_log.map((entry) => [entry.id, entry]));
+  evidence.search_log.forEach((entry, index) => {
+    ["channel", "query_or_corpus", "searched_at"].forEach((field) => requireString(entry[field], `search_log[${index}].${field}`));
+    requireChoice(entry.result, ["results-found", "none-found", "access-failed", "excluded"], `search_log[${index}].result`);
+  });
+
+  requireArray(evidence.evidence_items, "evidence_items", { nonEmpty: true });
+  const evidenceIds = uniqueIds(evidence.evidence_items, "evidence_items");
+  const evidenceById = new Map(evidence.evidence_items.map((item) => [item.id, item]));
+  evidence.evidence_items.forEach((item, index) => {
+    requireChoice(item.source_level, SOURCE_LEVELS, `evidence_items[${index}].source_level`);
+    requireChoice(item.visibility, ["public", "internal"], `evidence_items[${index}].visibility`);
+    requireChoice(item.stance, ["support", "counter"], `evidence_items[${index}].stance`);
+    ["source_class", "source_ref", "locator", "observed_at", "observation", "freshness"].forEach((field) => requireString(item[field], `evidence_items[${index}].${field}`));
+    requireArray(item.limitations, `evidence_items[${index}].limitations`);
+  });
+
+  requireArray(evidence.claims, "claims", { nonEmpty: true });
+  const claimIds = uniqueIds(evidence.claims, "claims");
+  const highKinds = new Map();
+  const lowerSeverityPrimary = new Map();
+  evidence.claims.forEach((claim, index) => {
+    ["problem_id", "statement"].forEach((field) => requireString(claim[field], `claims[${index}].${field}`));
+    requireChoice(claim.claim_kind, ["problem-exists", "impact", "frequency", "recommended-move"], `claims[${index}].claim_kind`);
+    requireChoice(claim.severity, ["low", "medium", "high", "critical"], `claims[${index}].severity`);
+    requireChoice(claim.frequency_signal, ["measured", "repeated-independent", "anecdotal", "unknown"], `claims[${index}].frequency_signal`);
+    requireChoice(claim.confidence, ["low", "medium", "high"], `claims[${index}].confidence`);
+    requireChoice(claim.audit_status, ["supported", "partially-supported", "unsupported", "not-audited"], `claims[${index}].audit_status`);
+    requireChoice(claim.disposition, ["publish", "qualify", "needs-deeper-research"], `claims[${index}].disposition`);
+    requireArray(claim.evidence_refs, `claims[${index}].evidence_refs`, { nonEmpty: true });
+    requireArray(claim.counter_signal_refs, `claims[${index}].counter_signal_refs`, { nonEmpty: true });
+    const supporting = claim.evidence_refs.map((ref) => {
+      if (!evidenceIds.has(ref)) fail(`${claim.id} has unresolved evidence ref: ${ref}`);
+      const item = evidenceById.get(ref);
+      if (item.stance !== "support") fail(`${claim.id} support ref is not marked support: ${ref}`);
+      if (item.source_level === "lead-only") fail(`${claim.id} uses lead-only evidence as support: ${ref}`);
+      return item;
+    });
+    claim.counter_signal_refs.forEach((ref) => {
+      if (!evidenceIds.has(ref) && !searchIds.has(ref)) fail(`${claim.id} has unresolved counter-signal ref: ${ref}`);
+      if (evidenceIds.has(ref) && evidenceById.get(ref).stance !== "counter") fail(`${claim.id} counter-signal evidence is not marked counter: ${ref}`);
+      if (searchIds.has(ref) && searchesById.get(ref).result !== "none-found") fail(`${claim.id} counter-signal search must have result none-found: ${ref}`);
+    });
+    if (claim.audit_status === "unsupported" && claim.disposition !== "needs-deeper-research") fail(`${claim.id} is unsupported and must use needs-deeper-research`);
+    if (claim.audit_status === "partially-supported" && claim.disposition !== "qualify") fail(`${claim.id} is partially supported and must use qualify`);
+    if (["high", "critical"].includes(claim.severity)) {
+      const kinds = highKinds.get(claim.problem_id) ?? new Set();
+      kinds.add(claim.claim_kind);
+      highKinds.set(claim.problem_id, kinds);
+    } else {
+      lowerSeverityPrimary.set(claim.problem_id, (lowerSeverityPrimary.get(claim.problem_id) ?? false) || supporting.some((item) => item.source_level === "primary"));
+    }
+    if (!brief.includes(claim.id)) fail(`brief does not reference key claim: ${claim.id}`);
+  });
+
+  const requiredHighKinds = ["problem-exists", "impact", "frequency", "recommended-move"];
+  highKinds.forEach((kinds, problemId) => {
+    const missing = requiredHighKinds.filter((kind) => !kinds.has(kind));
+    if (missing.length) fail(`${problemId} is high severity but is missing audited claim kinds: ${missing.join(", ")}`);
+  });
+  lowerSeverityPrimary.forEach((hasPrimary, problemId) => {
+    if (!hasPrimary) fail(`${problemId} is lower severity but has no primary supporting evidence`);
+  });
+
+  requireArray(evidence.source_gaps, "source_gaps");
+  if (evidence.audit_summary?.status !== "complete") fail("audit_summary.status must be complete");
+  requireArray(evidence.audit_summary.audited_claim_ids, "audit_summary.audited_claim_ids", { nonEmpty: true });
+  const audited = new Set(evidence.audit_summary.audited_claim_ids);
+  audited.forEach((id) => { if (!claimIds.has(id)) fail(`audit_summary has unknown claim: ${id}`); });
+  claimIds.forEach((id) => { if (!audited.has(id)) fail(`audit_summary is missing claim: ${id}`); });
+  evidence.claims.forEach((claim) => { if (claim.audit_status === "not-audited") fail(`${claim.id} remains not-audited`); });
+  requireArray(evidence.audit_summary.notes, "audit_summary.notes");
+  return { claims: claimIds.size, evidence_items: evidenceIds.size, searches: searchIds.size };
+}
+
+try {
+  const result = validate(process.argv[2], process.argv[3]);
+  process.stdout.write(`research package valid (${result.claims} claims, ${result.evidence_items} evidence items, ${result.searches} searches)\n`);
+} catch (error) {
+  process.stderr.write(`research package invalid: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/.codex/skills/product-design/skills/research/tests/run-scenarios.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const validator = path.join(root, "scripts/validate-research-package.mjs");
+const template = JSON.parse(readFileSync(path.join(root, "assets/evidence-template.yaml"), "utf8"));
+const directory = mkdtempSync(path.join(tmpdir(), "product-design-research-"));
+const brief = path.join(directory, "sample-research-brief.md");
+const evidence = path.join(directory, "sample-evidence.yaml");
+const requiredHeadings = ["Research Scope", "Executive Read", "Ranked UX Problems", "Source Map", "Opportunity Map", "Evidence Limitations"];
+
+function run(payload, expectedStatus, expectedText) {
+  writeFileSync(brief, `${requiredHeadings.map((heading) => `## ${heading}`).join("\n\n")}\n\n${payload.claims.map((claim) => claim.id).join(" ")}\n`);
+  writeFileSync(evidence, `${JSON.stringify(payload, null, 2)}\n`);
+  const result = spawnSync(process.execPath, [validator, brief, evidence], { encoding: "utf8" });
+  if (result.status !== expectedStatus || !`${result.stdout}${result.stderr}`.includes(expectedText)) {
+    throw new Error(`expected status ${expectedStatus} containing ${expectedText}, got ${result.status}: ${result.stdout}${result.stderr}`);
+  }
+}
+
+try {
+  template.scope.product = "Example";
+  template.scope.audience = "Administrators";
+  template.scope.time_horizon = "Last 90 days";
+  template.scope.research_questions = ["Where does onboarding fail?"];
+  template.scope.inclusion_criteria = ["Direct experience in scope"];
+  template.scope.exclusion_criteria = ["Unverifiable reposts"];
+  template.search_log[0].channel = "GitHub Issues";
+  template.search_log[0].query_or_corpus = "onboarding failure";
+  template.search_log[0].searched_at = "2026-09-03";
+  template.search_log[1].channel = "GitHub Issues";
+  template.search_log[1].query_or_corpus = "onboarding completed successfully";
+  template.search_log[1].searched_at = "2026-09-03";
+  template.evidence_items[0].source_class = "issue";
+  template.evidence_items[0].source_ref = "https://example.com/issues/1";
+  template.evidence_items[0].locator = "comment-1";
+  template.evidence_items[0].observed_at = "2026-09-03";
+  template.evidence_items[0].evidence_date = "2026-09-01";
+  template.evidence_items[0].observation = "A user reports that setup stopped before completion.";
+  template.claims[0].severity = "medium";
+  template.claims[0].statement = "At least one user encountered an onboarding blocker.";
+  run(template, 0, "research package valid");
+
+  const unsupported = structuredClone(template);
+  unsupported.claims[0].audit_status = "unsupported";
+  unsupported.claims[0].disposition = "publish";
+  run(unsupported, 1, "must use needs-deeper-research");
+
+  const unresolved = structuredClone(template);
+  unresolved.claims[0].evidence_refs = ["evidence-missing"];
+  run(unresolved, 1, "unresolved evidence ref");
+
+  const falseCounter = structuredClone(template);
+  falseCounter.claims[0].counter_signal_refs = ["search-001"];
+  run(falseCounter, 1, "counter-signal search must have result none-found");
+
+  const incompleteHighSeverity = structuredClone(template);
+  incompleteHighSeverity.claims[0].severity = "high";
+  run(incompleteHighSeverity, 1, "high severity but is missing audited claim kinds");
+
+  const lowerSeverityWithoutPrimary = structuredClone(template);
+  lowerSeverityWithoutPrimary.evidence_items[0].source_level = "secondary";
+  run(lowerSeverityWithoutPrimary, 1, "lower severity but has no primary supporting evidence");
+
+  process.stdout.write("research package scenarios passed (6)\n");
+} finally {
+  rmSync(directory, { recursive: true, force: true });
+}

package/template/.codex/skills/wayfinder/SKILL.md

@@ -74,7 +74,7 @@ The answer isn't part of the body — it's recorded on resolution (see [Work thr
 
 Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/research` **subagent**. Use when knowledge outside the current working directory is required.
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/yss-research` **subagent** (`/research` is a deprecated alias). Use when knowledge outside the current working directory is required.
 - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
 - **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
 - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
@@ -112,7 +112,7 @@ User invokes with a loose idea.
 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
 4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket.
+5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/yss-research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. `/research` remains only as a deprecated compatibility alias.
 6. Stop — charting is one session's work; it hand-resolves nothing.
 
 ### Work through the map