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/source-snapshot.mjs

View on GitHub
// source-snapshot.mjs - the per-source snapshot that fact locators read.
//
// writeSnapshot writes <sourcesDir>/<S-id>/ with raw.bin (the fetched or captured bytes, absent
// only for converted-only sources), meta.json (sha256 of the pinned body, text_source, charset),
// text.txt (the locator text of source-view.mjs: the visible text nodes of a page, the decoded
// bytes of a document, or a declared/converted extraction), source.html for pages (decoded, a
// reading aid), sentences.jsonl (sid S<n>:s<k>, indexed over text.txt) and acronyms.json; a page
// also gets conversion.json, the conversion probe's record of the numbers its text.txt altered.
// Plain Node ESM, node: builtins and sibling imports only.

import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
import { join } from "node:path"

import { sha256Of } from "./cli-support.mjs"
import { probeConversion } from "./conversion-probe.mjs"
import { writeFidelityRecord } from "./fidelity-records.mjs"
import { extractHtml } from "./html-text-map.mjs"
import { splitSentences } from "./sentence-split.mjs"
import { buildView } from "./source-view.mjs"

const SOURCE_ID = /^S[1-9]\d*$/
const EXTRACTOR = /^(?:tool:source-snapshot@1|model|extractor:[\w.@+-]+)$/
const KINDS = new Set(["page", "command", "document", "converted-only"])
const PROVENANCE = new Set(["primary", "secondary", "unknown"])
const ACRONYM_AFTER = /\(([A-Z]{2,6})\)/g
const ACRONYM_BEFORE = /(?<![\p{L}\p{N}])([A-Z]{2,6})\s?\(([A-Z][^()\n]{2,79})\)/gu
const NAME_WORD = /^[A-Z][\p{L}\p{N}-]*$/u
const CONNECTOR = new Set(["of", "and", "for", "the", "in", "on", "to", "&"])
const MARKUP = /^\s*</

/**
 * Block lines of a page: { root, text, blocks: [{ node, start, end }], starts, ends } where text
 * joins the visible block texts with "\n" (html-text-map.mjs). fact-locate reads cells through `node`.
 */
export function snapshotBlocks(html) {
  return extractHtml(html)
}

/** text.txt form of an html page. */
export function snapshotFromHtml(html) {
  return extractHtml(html).text
}

/** Sentence index rows { sid: "S<n>:s<k>", start, end, text }; a form feed (page break) always ends a sentence. */
export function indexSentences(text, sourceId) {
  return splitSentences(text.replace(/\f/g, "\n")).map((row) => ({
    sid: `${sourceId}:${row.sid}`,
    start: row.start,
    end: row.end,
    text: text.slice(row.start, row.end),
  }))
}

const sentenceIdAt = (sentences, offset) =>
  sentences.find((row) => row.start <= offset && offset < row.end)?.sid ?? null

/** "High Bandwidth Memory (HBM)": the capitalized words before the parenthesis, at most one per letter. */
function nameBefore(text, at, letters) {
  const prefix = text.slice(Math.max(0, at - 160), at)
  if (!/\S[ \t]?$/.test(prefix)) return null
  const words = [...prefix.matchAll(/\S+/g)]
  const picked = []
  let content = 0
  for (let k = words.length - 1; k >= 0 && content < letters; k--) {
    const word = words[k][0]
    if (NAME_WORD.test(word)) content++
    else if (!CONNECTOR.has(word) || picked.length === 0) break
    picked.unshift(words[k])
  }
  while (picked.length > 0 && CONNECTOR.has(picked[0][0])) picked.shift()
  if (picked.length === 0) return null
  const start = at - prefix.length + picked[0].index
  const end = at - prefix.length + picked[picked.length - 1].index + picked[picked.length - 1][0].length
  return { start, expansion: text.slice(start, end) }
}

/** Every `Full Name (ACR)` and `ACR (Full Name)` in the text, ordered by position. */
export function findAcronyms(text, sentences) {
  const entries = []
  for (const match of text.matchAll(ACRONYM_AFTER)) {
    const name = nameBefore(text, match.index, match[1].length)
    if (!name || name.expansion === match[1]) continue
    entries.push({ acronym: match[1], expansion: name.expansion, span: [name.start, match.index + match[0].length] })
  }
  for (const match of text.matchAll(ACRONYM_BEFORE)) {
    const expansion = match[2].trim()
    if (!/\s/.test(expansion) || expansion === expansion.toUpperCase()) continue
    entries.push({ acronym: match[1], expansion, span: [match.index, match.index + match[0].length] })
  }
  return entries
    .sort((a, b) => a.span[0] - b.span[0])
    .map((entry) => ({
      acronym: entry.acronym,
      expansion: entry.expansion,
      sentence_id: sentenceIdAt(sentences, entry.span[0]),
      span: entry.span,
    }))
}

function snapshotText(input) {
  if (Array.isArray(input.pages)) return input.pages.join("\f")
  if (typeof input.text === "string") return input.text
  throw new TypeError("writeSnapshot needs raw, html, text, or pages")
}

/** Which source-view text source the input makes, with the bytes it pins. */
function bodiesOf(input) {
  if (input.kind === "converted-only")
    return { mode: "converted", raw: null, textBody: Buffer.from(snapshotText(input)) }
  if (input.declared === true)
    return { mode: "declared", raw: Buffer.from(input.raw), textBody: Buffer.from(snapshotText(input)) }
  if (input.raw === undefined && typeof input.html === "string")
    return { mode: "html", raw: Buffer.from(input.html), textBody: null }
  if (input.raw === undefined) return { mode: "decoded", raw: Buffer.from(snapshotText(input)), textBody: null }
  const raw = Buffer.from(input.raw)
  if (
    input.markup === true ||
    typeof input.html === "string" ||
    input.kind === "page" ||
    MARKUP.test(
      raw
        .subarray(0, 1024)
        .toString("latin1")
        .replace(/^\u00ef\u00bb\u00bf/, ""),
    )
  )
    return { mode: "html", raw, textBody: null }
  if (input.text !== undefined || input.pages !== undefined)
    return { mode: "declared", raw, textBody: Buffer.from(snapshotText(input)) }
  return { mode: "decoded", raw, textBody: null }
}

function checkInput(sourceId, input) {
  if (!SOURCE_ID.test(String(sourceId))) throw new TypeError(`source id must be S<n>, got ${sourceId}`)
  if (!EXTRACTOR.test(String(input.extractor)))
    throw new TypeError(`extractor must be tool:source-snapshot@1, model, or extractor:<name>, got ${input.extractor}`)
  if (typeof (input.url ?? input.path) !== "string") throw new TypeError("writeSnapshot needs a url or a path")
  if (input.kind !== undefined && !KINDS.has(input.kind))
    throw new TypeError(`kind must be page, command, document, or converted-only, got ${input.kind}`)
  if (input.provenance !== undefined && !PROVENANCE.has(input.provenance))
    throw new TypeError(`provenance must be primary, secondary, or unknown, got ${input.provenance}`)
  if (
    input.observed_at !== undefined &&
    (typeof input.observed_at !== "string" || Number.isNaN(new Date(input.observed_at).getTime()))
  )
    throw new TypeError(`observed_at must be an ISO timestamp, got ${input.observed_at}`)
}

function pinnedHash(dir) {
  const metaPath = join(dir, "meta.json")
  return existsSync(metaPath) ? JSON.parse(readFileSync(metaPath, "utf8")).sha256 : null
}

/**
 * Write <sourcesDir>/<sourceId>/ for one source; returns { dir, sha256, altered } over the pinned body,
 * where altered lists the numbers the page conversion altered (null when no page conversion ran).
 * input: { url | path, raw?, markup?, html?, text? | pages?, charset?, extractor, observed_at?, revision?,
 * kind?, provenance? } (see bodiesOf). Re-writing the same bytes is a no-op; different bytes over
 * an existing snapshot throw snapshot_exists, because ledger rows pin the old hash, unless
 * options.replace (`source refresh`, which re-anchors those rows, or `source snapshot --replace`, which
 * has checked that no active row pins it) is set; a replacement drops the old capture's command.json.
 */
export function writeSnapshot(sourcesDir, sourceId, input, options = {}) {
  checkInput(sourceId, input)
  const { mode, raw, textBody } = bodiesOf(input)
  const view = buildView(mode, { raw, textBody, charset: input.charset ?? null })
  const sha256 = sha256Of(raw ?? textBody)
  const dir = join(sourcesDir, sourceId)
  const pinned = pinnedHash(dir)
  if (pinned !== null && pinned !== sha256) {
    if (options.replace !== true) throw new Error(`snapshot_exists: ${sourceId} already holds different snapshot bytes`)
    rmSync(join(dir, "command.json"), { force: true })
  }
  mkdirSync(dir, { recursive: true })
  if (raw) writeFileSync(join(dir, "raw.bin"), raw)
  else rmSync(join(dir, "raw.bin"), { force: true })
  writeFileSync(join(dir, "text.txt"), textBody ?? view.text)
  if (view.html !== null) writeFileSync(join(dir, "source.html"), view.html)
  else rmSync(join(dir, "source.html"), { force: true })
  const meta = {
    source_id: sourceId,
    url: input.url ?? input.path,
    observed_at: input.observed_at ?? new Date().toISOString(),
    sha256,
    extractor: input.extractor,
    revision: input.revision ?? null,
    kind: input.kind ?? (input.url !== undefined || mode === "html" ? "page" : "document"),
    provenance: input.provenance ?? "unknown",
    text_source: mode,
    ...(raw ? { charset: view.encoding } : {}),
    ...(mode === "declared" ? { text_sha256: sha256Of(textBody) } : {}),
  }
  writeFileSync(join(dir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`)
  let altered = null
  if (mode === "html") {
    const { altered: changed, ...counts } = probeConversion(view.html, view.text, { attributes: false })
    altered = changed
    writeFidelityRecord(
      join(dir, "conversion.json"),
      "source_conversion",
      {
        artifact_sha256: sha256Of(view.html),
        report: join(dir, "source.html"),
        defects: [],
        conversion_altered_numbers: changed,
        ...counts,
      },
      new Date(meta.observed_at),
    )
  } else rmSync(join(dir, "conversion.json"), { force: true })
  const sentences = indexSentences(view.text, sourceId)
  writeFileSync(join(dir, "sentences.jsonl"), sentences.map((row) => `${JSON.stringify(row)}\n`).join(""))
  const acronyms = {
    schemaVersion: 1,
    source_id: sourceId,
    snapshot_sha256: sha256,
    entries: findAcronyms(view.text, sentences),
  }
  writeFileSync(join(dir, "acronyms.json"), `${JSON.stringify(acronyms, null, 2)}\n`)
  return { dir, sha256, altered }
}
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