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/format-extract.mjs

View on GitHub
// format-extract.mjs - read a pointed-at HTML or Markdown document and return the facts a
// design-spec.md draft needs (render with design-spec.renderDesignSpec). Nothing is guessed:
// a value the document does not state is left out, and the renderer writes `TODO: ask`.
//
// Static input only. fetchHtml downloads exactly the given URL with plain fetch; external
// stylesheets are never followed (each is recorded as a note). A page that renders its
// content client-side is the orchestrator's job: render it with the browser skill, save the
// HTML, and pass the saved file. PDF input is rejected with UnsupportedFormatError.
// Plain Node ESM, node: builtins and siblings only.

import { readFileSync } from "node:fs"
import { extname } from "node:path"

import { cssFacts } from "./format-extract-css.mjs"
import { parseHtml, proseText } from "./html-lite.mjs"

export const UNSUPPORTED_MESSAGE = "unsupported: point at the HTML or Markdown source"
export const FETCH_TIMEOUT_MS = 15_000

const S_MARKER = /\[S\d+\]/
const SOURCE_ANCHOR = /\[(?:\uCD9C\uCC98|source(?:\s*\d+)?)\]/i
const LINEAGE_TOKEN = /\b(?:MEASURED|ASSUMED|DERIVED)\b/
const MD_FOOTNOTE = /\[\^[^\]\s]+\]/
const HEADING_NUMBER = /^(\d{1,3}(?:\.\d{1,3})*)\.?(?=\s|$)/
const FENCE = /^\s{0,3}(`{3,}|~{3,})/
const MD_HEADING = /^(#{1,6})\s+(.*?)\s*#*\s*$/
/**
 * @typedef {{ hex: string, count: number, roles: string[] }} ExtractColor
 * @typedef {{
 *   origin: string | undefined, bytes: number,
 *   tokens: { light: Map<string, string>, dark: Map<string, string> },
 *   fonts: { body?: string, heading?: string, mono?: string }, colors: ExtractColor[], breakpoints: number[],
 *   headingNumbering: "double-digit" | "decimal" | "none" | "unknown",
 *   citationStyle: "bracket-S" | "bracket-source" | "footnote" | "unknown",
 *   lineageMode: "inline" | "section" | "unknown", figureContainers: string[],
 *   skeleton: { level: number, text: string }[],
 *   measure: { fontSize?: string, lineHeight?: string, maxWidth?: string }, notes: string[],
 * }} Extract
 */

const HTML_EXTENSIONS = new Set([".html", ".htm", ".xhtml"])
const MD_EXTENSIONS = new Set([".md", ".markdown"])

export class UnsupportedFormatError extends Error {
  constructor(detail) {
    super(UNSUPPORTED_MESSAGE)
    this.name = "UnsupportedFormatError"
    this.code = "unsupported"
    this.detail = detail
  }
}

function rejectPdf(source, origin) {
  if (/\.pdf$/i.test(String(origin ?? ""))) throw new UnsupportedFormatError(`pdf origin: ${origin}`)
  if (String(source).trimStart().startsWith("%PDF-")) throw new UnsupportedFormatError("pdf bytes")
}

/** @returns {Extract} */
function baseExtract(source, origin) {
  return {
    origin,
    bytes: Buffer.byteLength(String(source), "utf8"),
    tokens: { light: new Map(), dark: new Map() },
    fonts: {},
    colors: [],
    breakpoints: [],
    headingNumbering: "unknown",
    citationStyle: "unknown",
    lineageMode: "unknown",
    figureContainers: [],
    skeleton: [],
    measure: {},
    notes: [],
  }
}

/** h2 numbers ("01", "1.2", or null) -> double-digit when every numbered h2 uses two digits. */
function classifyNumbering(numbers) {
  if (!numbers.length) return "unknown"
  const numbered = numbers.filter(Boolean)
  if (numbered.length * 2 < numbers.length) return "none"
  return numbered.every((number) => /^\d{2}$/.test(number)) ? "double-digit" : "decimal"
}

function headingNumber(text) {
  return HEADING_NUMBER.exec(text)?.[1] ?? null
}

function citationFacts(text, hasFootnotes, hasLineageAttribute) {
  const style = S_MARKER.test(text)
    ? "bracket-S"
    : SOURCE_ANCHOR.test(text)
      ? "bracket-source"
      : hasFootnotes
        ? "footnote"
        : "unknown"
  let lineage = "unknown"
  if (hasLineageAttribute || LINEAGE_TOKEN.test(text) || S_MARKER.test(text)) lineage = "inline"
  else if (SOURCE_ANCHOR.test(text)) lineage = "section"
  return { style, lineage }
}

function walk(node, visit) {
  for (const child of node.children) {
    visit(child)
    walk(child, visit)
  }
}

function classesOf(node) {
  return String(node.attrs.class ?? "")
    .split(/\s+/)
    .filter(Boolean)
}

/** Previous element sibling whose whole text is a heading number (a `.sec-no` style eyebrow). */
function eyebrowNumber(heading) {
  const siblings = heading.parent.children.filter((child) => child.tag !== "#text" || child.text.trim())
  const previous = siblings[siblings.indexOf(heading) - 1]
  if (!previous || previous.tag === "#text" || /^h[1-6]$/.test(previous.tag)) return null
  const text = proseText(previous)
  return HEADING_NUMBER.test(text) && headingNumber(text) === text.replace(/\.$/, "") ? headingNumber(text) : null
}

/** Nearest `<figure>` or fig/chart-classed ancestor of an img or svg. */
function figureContainer(node) {
  for (let cur = node.parent; cur && cur.tag !== "body"; cur = cur.parent) {
    const classes = classesOf(cur)
    if (cur.tag === "figure" || classes.some((name) => /fig|chart/i.test(name))) return cur
  }
  return null
}

function rankByCount(names) {
  const counts = new Map()
  for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1)
  return [...counts].sort((a, b) => b[1] - a[1]).map(([name]) => name)
}

/** @returns {Extract} throws UnsupportedFormatError on PDF input. */
export function extractFromHtml(source, { origin } = {}) {
  rejectPdf(source, origin)
  const extract = baseExtract(source, origin)
  const root = parseHtml(source)
  const styles = []
  const headings = []
  const containers = []
  let hasFootnotes = false
  let hasLineageAttribute = false
  let scripts = 0
  walk(root, (node) => {
    if (node.tag === "style") styles.push(node.raw ?? "")
    else if (node.tag === "script") scripts++
    else if (node.tag === "link" && /(?:^|\s)stylesheet(?:\s|$)/i.test(node.attrs.rel ?? "")) {
      extract.notes.push(`skipped external stylesheet: ${node.attrs.href ?? "(no href)"}`)
    } else if (/^h[1-6]$/.test(node.tag)) headings.push(node)
    else if (node.tag === "img" || node.tag === "svg") {
      const container = figureContainer(node)
      if (container) containers.push(...classesOf(container))
    } else if (
      node.tag === "sup" &&
      node.children.some((child) => child.tag === "a" && /^#/.test(child.attrs.href ?? ""))
    )
      hasFootnotes = true
    else if (node.attrs?.role === "doc-noteref") hasFootnotes = true
    if (node.attrs && Object.hasOwn(node.attrs, "data-lineage")) hasLineageAttribute = true
  })
  const css = styles.join("\n")
  for (const match of css.matchAll(/@import\s+(?:url\()?\s*["']?([^"')\s;]+)/gi))
    extract.notes.push(`skipped @import: ${match[1]}`)
  if (styles.length > 1) extract.notes.push(`${styles.length} <style> blocks concatenated`)
  if (css.trim()) Object.assign(extract, cssFacts(css))
  if (!extract.fonts.heading && extract.fonts.body)
    extract.notes.push("no heading font-family rule; headings inherit the body stack")

  const body =
    root.children.find((child) => child.tag === "html")?.children.find((child) => child.tag === "body") ??
    root.children.find((child) => child.tag === "body") ??
    root
  const text = proseText(body)
  if (scripts && text.length < 200) {
    extract.notes.push(
      `little static text with ${scripts} <script> tags: if the page renders client-side, render it with the browser skill and pass the saved HTML`,
    )
  }
  const citation = citationFacts(text, hasFootnotes, hasLineageAttribute)
  extract.citationStyle = citation.style
  extract.lineageMode = citation.lineage
  const h2 = headings.filter((node) => node.tag === "h2")
  extract.headingNumbering = classifyNumbering(h2.map((node) => headingNumber(proseText(node)) ?? eyebrowNumber(node)))
  extract.skeleton = headings
    .filter((node) => node.tag === "h1" || node.tag === "h2")
    .map((node) => ({ level: Number(node.tag[1]), text: proseText(node) }))
  extract.figureContainers = rankByCount(containers)
  return extract
}

/** Markdown carries structure only: skeleton, heading numbering, citation style. @returns {Extract} */
export function extractFromMarkdown(source, { origin } = {}) {
  rejectPdf(source, origin)
  const extract = baseExtract(source, origin)
  const prose = []
  let fence = null
  for (const line of String(source).split(/\r?\n/)) {
    const fenceMatch = FENCE.exec(line)
    if (fence) {
      if (
        fenceMatch &&
        fenceMatch[1][0] === fence[0] &&
        fenceMatch[1].length >= fence.length &&
        line.trim() === fenceMatch[1]
      )
        fence = null
      continue
    }
    if (fenceMatch) {
      fence = fenceMatch[1]
      continue
    }
    prose.push(line.replace(/`[^`]*`/g, ""))
    const heading = MD_HEADING.exec(line)
    if (heading && heading[1].length <= 2) extract.skeleton.push({ level: heading[1].length, text: heading[2] })
  }
  const text = prose.join("\n")
  extract.citationStyle = citationFacts(text, MD_FOOTNOTE.test(text), false).style
  extract.headingNumbering = classifyNumbering(
    extract.skeleton.filter((entry) => entry.level === 2).map((entry) => headingNumber(entry.text)),
  )
  extract.notes.push(
    "markdown source: tokens, fonts, colors, breakpoints, figures, and measure are not carried by Markdown",
  )
  return extract
}

/** Dispatch on the file extension: .html/.htm/.xhtml, .md/.markdown; anything else (PDF included) is unsupported. @returns {Extract} */
export function extractFromPath(filePath) {
  const extension = extname(filePath).toLowerCase()
  if (HTML_EXTENSIONS.has(extension)) return extractFromHtml(readFileSync(filePath, "utf8"), { origin: filePath })
  if (MD_EXTENSIONS.has(extension)) return extractFromMarkdown(readFileSync(filePath, "utf8"), { origin: filePath })
  throw new UnsupportedFormatError(`extension ${extension || "(none)"}: ${filePath}`)
}

/** GET exactly `url` (plain fetch, 15 s timeout, no browser) and return the body text. */
export async function fetchHtml(url) {
  if (/\.pdf$/i.test(new URL(url).pathname)) throw new UnsupportedFormatError(`pdf url: ${url}`)
  const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
  const type = response.headers.get("content-type") ?? ""
  if (!response.ok || /pdf/i.test(type)) {
    await response.body?.cancel()
    if (!response.ok) throw new Error(`fetch failed: HTTP ${response.status} for ${url}`)
    throw new UnsupportedFormatError(`pdf response: ${url}`)
  }
  const text = await response.text()
  if (text.trimStart().startsWith("%PDF-")) throw new UnsupportedFormatError(`pdf bytes: ${url}`)
  return text
}
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