Skip to content

code-yeongyu/oh-my-openagent / packages/shared-skills/skills/ulw-research

ulw-research

Unverified

Runs maximum-saturation research with a cooperating team, claim-graph gating, and a cited, QA'd deliverable. Use when the user explicitly asks for research or a deep investigation, including any 'ulw' research wording.

FileKindSize
AGENTS.mdmarkdown9.2 KB
ATTRIBUTION.mdmarkdown2.4 KB
SKILL.mdskill md42.2 KB
references/deliverable-phase.mdmarkdown49.1 KB
references/fact-ledger-grammar.mdmarkdown6.8 KB
references/fact-ledger.mdmarkdown24.4 KB
references/fidelity-claim-kinds.mdmarkdown5.2 KB
references/markdown-blocks.mdmarkdown721 B
references/report-gates.mdmarkdown32.0 KB
references/report-visualization.mdmarkdown15.4 KB
references/research-collection.mdmarkdown26.8 KB
references/research-delivery.mdmarkdown14.3 KB
references/unit-rules.mdmarkdown16.3 KB
scripts/claim-kinds.mjsscript11.2 KB
scripts/claim-kinds.test.tsscript13.5 KB
scripts/claim-prefix.test.tsscript4.9 KB
scripts/claims-index.mjsscript5.3 KB
scripts/claims-index.test.tsscript5.7 KB
scripts/cli-support.mjsscript4.1 KB
scripts/cli-support.test.tsscript4.3 KB
scripts/contracts-validation.test.tsscript3.3 KB
scripts/contracts.mjsscript26.1 KB
scripts/contracts.test.tsscript7.9 KB
scripts/conversion-altered.test.tsscript11.0 KB
scripts/conversion-originals.test.tsscript22.7 KB
scripts/conversion-probe-classes.test.tsscript45.2 KB
scripts/conversion-probe.mjsscript13.5 KB
scripts/conversion-probe.test.tsscript11.6 KB
scripts/copy-returns-fidelity-policy.test.tsscript10.4 KB
scripts/copy-returns-polish.test.tsscript12.1 KB
scripts/copy-returns.test.tsscript10.6 KB
scripts/css-hiding.mjsscript9.1 KB
scripts/css-lite.mjsscript7.6 KB
scripts/css-lite.test.tsscript6.4 KB
scripts/delivery-barrier-meaning.test.tsscript12.3 KB
scripts/delivery-barrier.test.tsscript11.4 KB
scripts/design-spec.mjsscript7.2 KB
scripts/design-spec.test.tsscript6.7 KB
scripts/entities.mjsscript2.5 KB
scripts/entry-guard.mjsscript794 B
scripts/fact-commands-fill.mjsscript6.6 KB
scripts/fact-commands-meaning.mjsscript12.6 KB
scripts/fact-commands-polish.mjsscript10.3 KB
scripts/fact-commands-verify.mjsscript12.6 KB
scripts/fact-commands.mjsscript13.8 KB
scripts/fact-derive-2.test.tsscript7.2 KB
scripts/fact-derive.mjsscript4.9 KB
scripts/fact-derive.test.tsscript10.8 KB
scripts/fact-expr.mjsscript4.5 KB
scripts/fact-fill.mjsscript11.7 KB
scripts/fact-fill.test.tsscript10.7 KB
scripts/fact-ledger-grammar.test.tsscript11.8 KB
scripts/fact-ledger-kinds.mjsscript16.5 KB
scripts/fact-ledger-kinds.test.tsscript9.3 KB
scripts/fact-ledger-legacy.test.tsscript8.9 KB
scripts/fact-ledger-schema.mjsscript11.9 KB
scripts/fact-ledger-schema.test.tsscript1.5 KB
scripts/fact-ledger.mjsscript5.5 KB
scripts/fact-ledger.test.tsscript9.7 KB
scripts/fact-locate.mjsscript12.1 KB
scripts/fact-locate.test.tsscript7.2 KB
scripts/fact-pairs.mjsscript8.3 KB
scripts/fact-pairs.test.tsscript6.6 KB
scripts/fact-recompute.mjsscript4.8 KB
scripts/fact-unit-dimensions-2.test.tsscript8.4 KB
scripts/fact-unit-dimensions.test.tsscript11.9 KB
scripts/fact-unit-rules.test.tsscript8.9 KB
scripts/fidelity-binding.mjsscript6.7 KB
scripts/fidelity-binding.test.tsscript4.0 KB
scripts/fidelity-brief.mjsscript6.4 KB
scripts/fidelity-brief.test.tsscript7.8 KB
scripts/fidelity-claims.mjsscript5.1 KB
scripts/fidelity-csv.mjsscript1.1 KB
scripts/fidelity-lexicon.mjsscript8.1 KB
scripts/fidelity-lexicon.test.tsscript6.0 KB
scripts/fidelity-originals.mjsscript9.9 KB
scripts/fidelity-policy.mjsscript10.1 KB
scripts/fidelity-records.mjsscript13.4 KB
scripts/fidelity-snapshot-readability.mjsscript2.2 KB
scripts/fidelity-sources.mjsscript4.3 KB
scripts/fidelity-state.mjsscript2.1 KB
scripts/fidelity-state.test.tsscript1.7 KB
scripts/fidelity-trace.mjsscript6.1 KB
scripts/fidelity-trace.test.tsscript3.3 KB
scripts/fidelity-value-unit.mjsscript13.3 KB
scripts/fidelity-values.mjsscript16.1 KB
scripts/fidelity-values.test.tsscript15.8 KB
scripts/format-extract-css.mjsscript5.1 KB
scripts/format-extract.mjsscript10.3 KB
scripts/format-extract.test.tsscript11.2 KB
scripts/gates-context.test.tsscript2.6 KB
scripts/gates-fidelity.mjsscript6.3 KB
scripts/gates-fidelity.test.tsscript3.3 KB
scripts/gates-figures.mjsscript9.9 KB
scripts/gates-layout.mjsscript6.6 KB
scripts/gates-layout.test.tsscript12.4 KB
scripts/gates-static-headings.test.tsscript961 B
scripts/gates-static.mjsscript8.1 KB
scripts/gates-static.test.tsscript14.9 KB
scripts/gates-structure.mjsscript4.7 KB
scripts/gates-text.mjsscript7.2 KB
scripts/glossary-vocabulary.test.tsscript1.7 KB
scripts/html-foreign-object.mjsscript2.8 KB
scripts/html-lite.mjsscript9.7 KB
scripts/html-lite.test.tsscript7.9 KB
scripts/html-markup.mjsscript7.0 KB
scripts/html-text-map.mjsscript4.8 KB
scripts/html-text-map.test.tsscript15.2 KB
scripts/layout-probe.mjsscript4.6 KB
scripts/layout-probe.test.tsscript4.2 KB
scripts/lexicon.mjsscript2.6 KB
scripts/lexicon.test.tsscript3.2 KB
scripts/markdown-closers.mjsscript4.9 KB
scripts/md-lite-boundaries.test.tsscript2.2 KB
scripts/md-lite.mjsscript7.8 KB
scripts/md-lite.test.tsscript10.3 KB
scripts/meaning-check.mjsscript9.7 KB
scripts/meaning-check.test.tsscript12.0 KB
scripts/number-grammar.mjsscript2.1 KB
scripts/number-grammar.test.tsscript1.8 KB
scripts/numerals.mjsscript12.0 KB
scripts/numerals.test.tsscript6.1 KB
scripts/outcome-start.mjsscript3.8 KB
scripts/outcome-start.test.tsscript5.0 KB
scripts/outcome.mjsscript10.5 KB
scripts/outcome.test.tsscript12.8 KB
scripts/page-source-locator.test.tsscript11.7 KB
scripts/particles-ko.mjsscript4.8 KB
scripts/particles-ko.test.tsscript4.3 KB
scripts/placeholder.mjsscript9.3 KB
scripts/placeholder.test.tsscript3.8 KB
scripts/polish-apply.mjsscript6.8 KB
scripts/polish-apply.test.tsscript19.7 KB
scripts/polish-diff.mjsscript1.7 KB
scripts/polish-diff.test.tsscript10.1 KB
scripts/polish-markup.test.tsscript14.0 KB
scripts/polish-partial.test.tsscript2.5 KB
scripts/polish-project.mjsscript5.8 KB
scripts/polish-rules.mjsscript9.8 KB
scripts/rational.mjsscript5.2 KB
scripts/rational.test.tsscript1.9 KB
scripts/raw-decode.mjsscript4.5 KB
scripts/raw-locator.mjsscript2.4 KB
scripts/raw-snapshot.test.tsscript7.3 KB
scripts/references-fences.test.tsscript1.2 KB
scripts/repair-tracker.mjsscript7.5 KB
scripts/repair-tracker.test.tsscript10.8 KB
scripts/report-tools-2.test.tsscript16.1 KB
scripts/report-tools-3.test.tsscript9.3 KB
scripts/report-tools-4.test.tsscript10.1 KB
scripts/report-tools-5.test.tsscript14.6 KB
scripts/report-tools-commands.mjsscript12.9 KB
scripts/report-tools.mjsscript2.6 KB
scripts/report-tools.test.tsscript12.1 KB
scripts/sentence-split.mjsscript3.0 KB
scripts/sentence-split.test.tsscript4.5 KB
scripts/snapshot-readability.test.tsscript7.0 KB
scripts/source-commands.mjsscript12.4 KB
scripts/source-integrity.test.tsscript18.1 KB
scripts/source-refresh.mjsscript5.2 KB
scripts/source-snapshot.mjsscript9.9 KB
scripts/source-snapshot.test.tsscript6.3 KB
scripts/source-view.mjsscript5.0 KB
scripts/sources-citation.mjsscript12.1 KB
scripts/sources-citation.test.tsscript14.8 KB
scripts/tests/contracts-support.tsscript3.5 KB
scripts/tests/delivery-barrier-session.tsscript3.3 KB
scripts/tests/derive-clock.tsscript341 B
scripts/tests/fact-derive-support.tsscript1.9 KB
scripts/tests/fact-unit-dimensions-support.tsscript1.5 KB
scripts/tests/fact-unit-rules-support.tsscript16.8 KB
scripts/tests/fidelity-values-support.tsscript1.6 KB
scripts/tests/fixtures/assets/figure-1.svgother141 B
scripts/tests/fixtures/bad-report.htmlother2.1 KB
scripts/tests/fixtures/boxes.jsonconfig3.2 KB
scripts/tests/fixtures/conversion-probe.htmlother485 B
scripts/tests/fixtures/design-spec.mdmarkdown458 B
scripts/tests/fixtures/fidelity-brief-locked.mdmarkdown571 B
scripts/tests/fixtures/fidelity-brief-pending.mdmarkdown574 B
scripts/tests/fixtures/fidelity/assets/share.csvother40 B
scripts/tests/fixtures/fidelity/claim-graph.mdmarkdown449 B
scripts/tests/fixtures/fidelity/gen-legacy-dev.mjsscript5.0 KB
scripts/tests/fixtures/fidelity/ledger-basic.jsonconfig5.1 KB
scripts/tests/fixtures/fidelity/ledger-legacy-dev.jsonconfig18.3 KB
scripts/tests/fixtures/fidelity/ledger-verify.jsonconfig9.1 KB
scripts/tests/fixtures/fidelity/polish-edits.jsonconfig303 B
scripts/tests/fixtures/fidelity/report-bad.htmlother821 B
scripts/tests/fixtures/fidelity/report-good.htmlother2.4 KB
scripts/tests/fixtures/fidelity/sources/S4.htmlother680 B
scripts/tests/fixtures/fidelity/sources/S4/acronyms.jsonconfig36 B
scripts/tests/fixtures/fidelity/sources/S4/meta.jsonconfig256 B
scripts/tests/fixtures/fidelity/sources/S4/sentences.jsonlother623 B
scripts/tests/fixtures/fidelity/sources/S4/text.txtmarkdown300 B
scripts/tests/fixtures/fidelity/sources/S5/acronyms.jsonconfig3 B
scripts/tests/fixtures/fidelity/sources/S5/meta.jsonconfig235 B
scripts/tests/fixtures/fidelity/sources/S5/sentences.jsonlother53 B
scripts/tests/fixtures/fidelity/sources/S5/text.txtmarkdown10 B
scripts/tests/fixtures/fidelity/sources/S9.txtmarkdown128 B
scripts/tests/fixtures/good-report.htmlother2.7 KB
scripts/tests/fixtures/reference-report.htmlother2.5 KB

scripts/outcome.mjs

View on GitHub
// outcome.mjs - the per-run outcome manifest (`outcome.json`) and the closing briefing. Manifest functions are pure (they return a new manifest).
// The briefing reads only the manifest, the sources-ledger text, and an injected `now`. node: builtins only.
import * as nodeFs from "node:fs"
import { basename, dirname, join } from "node:path"

import {
  DELIVERABLE_FORMATS,
  DELIVERABLE_STATUSES,
  GATE_NAMES,
  GATE_STATUSES,
  LANES,
  MANIFEST_CODES,
  normalizeManifest,
  SCHEMA_VERSION,
  validateOutcomeManifest,
} from "./contracts.mjs"
import { runStart } from "./outcome-start.mjs"

export const MANIFEST_FILENAME = "outcome.json"
const MISSING = MANIFEST_CODES[0]
const SOURCE_LINE = /^\[(S|Source )\d+\]/
const URL_PATTERN = /https?:\/\/[^\s)<>\]"'`]+/g
const DRAFT_MARKER = "STATUS: draft"
const DRAFT_SCAN_LINES = 5
const REASON_REQUIRED = new Set(["blocked_capability", "skipped", "failed"])

export class OutcomeError extends Error {
  /** @param {string} code @param {string} message @param {readonly string[]} [allowed] */
  constructor(code, message, allowed) {
    super(message)
    this.name = "OutcomeError"
    this.code = code
    if (allowed) this.allowed = [...allowed]
  }
}

function assertOneOf(code, label, value, allowed) {
  if (!allowed.includes(value)) {
    throw new OutcomeError(code, `unknown ${label} ${JSON.stringify(value)}; allowed: ${allowed.join(", ")}`, allowed)
  }
}

const clone = (manifest) => structuredClone(manifest)
const isMissing = (error) => error?.code === "ENOENT" || error?.code === "ENOTDIR"
function stamp(now) {
  return (now ?? new Date()).toISOString()
}
/** The run clock outcome init records (outcome-start.mjs owns the contract). */
export function parseSessionStart(sessionDir, { startedAt, now } = {}) {
  const fail = (message) => {
    throw new OutcomeError("invalid_session_dir", message)
  }
  return runStart({
    sessionDir,
    startedAt,
    now,
    validManifest: (data) => validateOutcomeManifest(normalizeManifest(data)).ok,
    fail,
  })
}

/** @param {{ sessionDir: string, promised: string[], lane: string|null, interview?: object|null, now?: Date, startedAt?: string }} input */
export function initManifest({ sessionDir, promised, lane, interview = null, now, startedAt: recorded }) {
  const startedAt = parseSessionStart(sessionDir, { startedAt: recorded, now }).toISOString()
  if (lane !== null && lane !== undefined) assertOneOf("unknown_lane", "lane", lane, LANES)
  const formats = [...new Set(promised)]
  for (const format of formats) assertOneOf("unknown_format", "deliverable format", format, DELIVERABLE_FORMATS)
  const updatedAt = stamp(now)
  return {
    schemaVersion: SCHEMA_VERSION,
    sessionDir,
    startedAt,
    finishedAt: null,
    elapsedMinutes: null,
    lane: lane ?? null,
    interview,
    deliverables: formats.map((format) => ({ format, status: "pending", promised: true, updatedAt })),
    renders: [],
    gates: Object.fromEntries(GATE_NAMES.map((gate) => [gate, "not_run"])),
    residualDefects: [],
    repair: null,
    sources: null,
  }
}

/** Set one format's row, keeping other rows. New formats have promised=false.
 * @param {{ path?: string, reason?: string, pages?: number, bytes?: number, now?: Date }} [detail]
 */
export function setDeliverable(manifest, format, status, detail = {}) {
  assertOneOf("unknown_format", "deliverable format", format, DELIVERABLE_FORMATS)
  assertOneOf("unknown_status", "deliverable status", status, DELIVERABLE_STATUSES)
  const next = clone(manifest)
  const index = next.deliverables.findIndex((row) => row.format === format)
  const row = {
    format,
    status,
    promised: index >= 0 ? next.deliverables[index].promised : false,
    updatedAt: stamp(detail.now),
  }
  for (const key of ["path", "reason", "pages", "bytes", "verifiedBy", "renderedFrom"]) {
    if (detail[key] !== undefined) row[key] = detail[key]
  }
  if (index >= 0) next.deliverables[index] = row
  else next.deliverables.push(row)
  return next
}

export function setGate(manifest, gate, status, detail = {}) {
  assertOneOf("unknown_gate", "gate", gate, GATE_NAMES)
  assertOneOf("unknown_gate_status", "gate status", status, GATE_STATUSES)
  if (gate === "fidelity" && status === "not_run" && (typeof detail.reason !== "string" || !detail.reason.trim()))
    throw new OutcomeError("gate_reason_required", "fidelity not_run requires a non-empty --reason")
  const next = clone(manifest)
  next.gates[gate] = status
  next.gateHistory = [
    ...(next.gateHistory ?? []),
    { gate, status, ...(detail.reason !== undefined ? { reason: detail.reason.trim() } : {}), at: stamp(detail.now) },
  ]
  return next
}

export function addRender(manifest, path, page) {
  if (typeof path !== "string" || path.length === 0)
    throw new OutcomeError("invalid_render", "render path must be a non-empty string")
  if (!Number.isInteger(page) || page < 1)
    throw new OutcomeError("invalid_render", `render page must be an integer >= 1, got ${page}`)
  const next = clone(manifest)
  if (!next.renders.some((render) => render.path === path && render.page === page)) next.renders.push({ path, page })
  return next
}

function fileSize(fs, path) {
  try {
    const stat = fs.statSync(path)
    return stat.isFile() ? stat.size : null
  } catch (error) {
    if (isMissing(error)) return null
    throw error
  }
}

/**
 * @param {object} manifest
 * @param {{ statSync: typeof nodeFs.statSync }} [fs]
 * @returns {{ ok: boolean, problems: { code: string, format: string, message: string, path?: string }[] }}
 */
export function verifyManifest(manifest, fs = nodeFs) {
  const problems = []
  for (const row of manifest.deliverables) {
    const problem = (message, path) =>
      problems.push({ code: MISSING, format: row.format, message, ...(path ? { path } : {}) })
    if (row.status === "pending") problem(`${row.format} is still pending`)
    else if (row.status === "delivered") {
      if (!row.path) problem(`${row.format} is delivered without a path`)
      else {
        const size = fileSize(fs, row.path)
        if (size === null) problem(`${row.format} delivered file is missing: ${row.path}`, row.path)
        else if (size === 0) problem(`${row.format} delivered file is empty: ${row.path}`, row.path)
      }
    } else if (REASON_REQUIRED.has(row.status) && !row.reason)
      problem(`${row.format} is ${row.status} without a reason`)
  }
  return { ok: problems.length === 0, problems }
}

/** Missing/empty = none; draft marker or pending manifest = partial; else complete.
 * @returns {"none"|"partial"|"complete"}
 */
export function deliverableState(deliverablePath, manifestOrNull) {
  let text
  try {
    text = nodeFs.readFileSync(deliverablePath, "utf8")
  } catch (error) {
    if (isMissing(error)) return "none"
    throw error
  }
  if (text.trim() === "") return "none"
  if (text.split(/\r?\n/, DRAFT_SCAN_LINES).some((line) => line.includes(DRAFT_MARKER))) return "partial"
  const sibling = join(dirname(deliverablePath), MANIFEST_FILENAME)
  const manifest = manifestOrNull ?? (nodeFs.existsSync(sibling) ? readManifest(sibling) : null)
  if (manifest && manifest.deliverables.some((row) => row.status === "pending")) return "partial"
  return "complete"
}

/** Hostname without a leading `www.`; null for a string URL cannot parse (not a source host). */
function hostOf(url) {
  return URL.canParse(url) ? new URL(url).hostname.toLowerCase().replace(/^www\./, "") : null
}

function repairSummary(repair) {
  if (!repair) return null
  const attempts = Array.isArray(repair.attempts) ? repair.attempts.length : (repair.attempts ?? null)
  return {
    attempts,
    action: repair.decision?.action ?? repair.action ?? null,
    reason: repair.decision?.reason ?? repair.reason ?? null,
  }
}

/** The briefing numbers, from the manifest + ledger text + injected `now` only. */
export function briefingFacts(manifest, sourcesLedgerText, now) {
  const sourceLines = String(sourcesLedgerText ?? "")
    .split(/\r?\n/)
    .filter((line) => SOURCE_LINE.test(line))
  const hosts = new Set()
  for (const line of sourceLines) {
    for (const url of line.match(URL_PATTERN) ?? []) {
      const host = hostOf(url)
      if (host) hosts.add(host)
    }
  }
  const elapsedMs = now.getTime() - new Date(manifest.startedAt).getTime()
  return {
    sources: sourceLines.length,
    domains: hosts.size,
    hosts: [...hosts].sort(),
    minutes: Math.max(0, Math.round(elapsedMs / 60000)),
    deliverables: manifest.deliverables.map((row) => ({
      format: row.format,
      status: row.status,
      reason: row.reason ?? null,
      path: row.path ?? null,
    })),
    gates: { ...manifest.gates },
    residualDefects: manifest.residualDefects.length,
    repair: repairSummary(manifest.repair),
  }
}

/** The closing briefing block as plain text. */
export function buildBriefing(manifest, sourcesLedgerText, now) {
  const facts = briefingFacts(manifest, sourcesLedgerText, now)
  const repair = facts.repair
    ? `${facts.repair.attempts ?? "?"} attempt(s), last decision ${facts.repair.action ?? "?"} (${facts.repair.reason ?? "?"})`
    : "not run"
  return [
    "Closing briefing",
    `- Sources: ${facts.sources} from ${facts.domains} distinct domain(s), counted from the sources ledger.`,
    `- Elapsed: ${facts.minutes} minute(s) since ${manifest.startedAt}.`,
    "- Deliverables:",
    "  | format | status | detail |",
    "  |---|---|---|",
    ...facts.deliverables.map((row) => `  | ${row.format} | ${row.status} | ${row.reason ?? row.path ?? ""} |`),
    `- Gates: ${GATE_NAMES.map((gate) => `${gate} ${facts.gates[gate]}`).join(", ")}.`,
    `- Residual defects: ${facts.residualDefects}.`,
    `- Repair: ${repair}.`,
  ].join("\n")
}

function assertValid(manifest, where) {
  const { ok, errors } = validateOutcomeManifest(manifest)
  if (!ok) throw new OutcomeError("invalid_manifest", `${where}: ${errors.join("; ")}`)
}

export function readManifest(file) {
  let manifest
  try {
    manifest = normalizeManifest(JSON.parse(nodeFs.readFileSync(file, "utf8")))
  } catch (error) {
    if (error instanceof SyntaxError)
      throw new OutcomeError("invalid_manifest", `${file}: not valid JSON (${error.message})`)
    throw error
  }
  assertValid(manifest, file)
  return manifest
}

/** Validate, then write atomically (temp file in the same dir + rename). */
export function writeManifest(file, manifest) {
  assertValid(manifest, file)
  const temp = join(dirname(file), `.${basename(file)}.${process.pid}.${Date.now()}.tmp`)
  try {
    nodeFs.writeFileSync(temp, `${JSON.stringify(manifest, null, "\t")}\n`, "utf8")
    nodeFs.renameSync(temp, file)
  } catch (error) {
    nodeFs.rmSync(temp, { force: true })
    throw error
  }
  return file
}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall