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/fact-ledger.test.ts

View on GitHub
import { describe, expect, onTestFinished, test } from "bun:test"
import { mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs"
import { tmpdir } from "node:os"
import { join } from "node:path"

import {
  LEDGER_FILENAME,
  LEDGER_SCHEMA_VERSION,
  addRow,
  emptyLedger,
  nextId,
  readLedger,
  renderLedgerMarkdown,
  retractRow,
  supersedeRow,
  validateLedger,
  writeLedger,
} from "./fact-ledger.mjs"

const HASH = "a".repeat(64)

function tempDir(): string {
  const dir = mkdtempSync(join(tmpdir(), "ulw-ledger-"))
  onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
  return dir
}

function measured(label: string, value = "320") {
  return {
    kind: "measured",
    value,
    unit: "m",
    raw: `${value} m`,
    quote: `The span is ${value} m.`,
    value_span: [12, 12 + value.length],
    source_id: "S1",
    locator: { artifact: "sources/S1/text.txt", line: 3, char_start: 40, char_end: 62 },
    snapshot_sha256: HASH,
    extracted_by: "fact add --find",
    observed_at: "2026-10-23T08:00:00Z",
    label,
  }
}

function quoteRow(label: string) {
  return { ...measured(label), kind: "quote", value: null, unit: null, value_span: null }
}

function ledgerWith(...rows: object[]) {
  const ledger = emptyLedger()
  for (const row of rows) addRow(ledger, row)
  return ledger
}

describe("validateLedger", () => {
  test("accepts a ledger built by addRow", () => {
    expect(validateLedger(ledgerWith(measured("span"), quoteRow("claim")))).toEqual([])
  })

  test("rejects a row missing label", () => {
    const ledger = ledgerWith(measured("span"))
    delete (ledger.rows[0] as Record<string, unknown>).label
    expect(validateLedger(ledger).some((e: string) => e.includes("label"))).toBe(true)
  })

  test("rejects a duplicate label", () => {
    const ledger = ledgerWith(measured("span"))
    ledger.rows.push({ ...ledger.rows[0], fact_id: "F2" })
    expect(validateLedger(ledger).some((e: string) => e.includes("duplicate label"))).toBe(true)
  })

  test("rejects an assumed row without rationale", () => {
    const ledger = ledgerWith(measured("span"))
    ledger.rows[0].kind = "assumed"
    expect(validateLedger(ledger).some((e: string) => e.includes("rationale"))).toBe(true)
  })

  test("rejects a value row with a non-decimal value", () => {
    const ledger = ledgerWith(measured("span"))
    ledger.rows[0].value = "320m"
    expect(validateLedger(ledger).some((e: string) => e.includes("value"))).toBe(true)
  })

  test("rejects an exact with a non-string num", () => {
    const ledger = ledgerWith(measured("span"))
    ledger.rows[0].exact = { num: 1, den: "3" }
    expect(validateLedger(ledger).some((e: string) => e.includes("exact"))).toBe(true)
  })

  test("rejects operands and derived_from ids with no ledger row", () => {
    const ledger = ledgerWith(measured("span"))
    ledger.rows.push({
      ...ledger.rows[0],
      fact_id: "F2",
      kind: "derived",
      label: "ratio",
      operation: "ratio",
      operands: ["F9"],
      derived_from: ["F1", "Q7"],
    })
    const errors = validateLedger(ledger)
    expect(errors.some((e: string) => e.includes("operands") && e.includes("F9"))).toBe(true)
    expect(errors.some((e: string) => e.includes("derived_from") && e.includes("Q7"))).toBe(true)
    expect(errors.some((e: string) => e.includes("F1"))).toBe(false)
  })

  test("a bare row with only fact_id returns at least three errors", () => {
    expect(validateLedger({ rows: [{ fact_id: "F1" }] }).length).toBeGreaterThanOrEqual(3)
  })
})

describe("ids and status", () => {
  test("nextId sequences F1, F2 then Q1, and a derived row gets F3", () => {
    const ledger = emptyLedger()
    expect(addRow(ledger, measured("a")).fact_id).toBe("F1")
    expect(addRow(ledger, measured("b")).fact_id).toBe("F2")
    expect(addRow(ledger, quoteRow("c")).fact_id).toBe("Q1")
    expect(nextId(ledger, "derived")).toBe("F3")
    const derived = addRow(ledger, {
      kind: "derived",
      value: "0.333",
      unit: null,
      raw: "0.333",
      quote: "",
      extracted_by: "fact derive",
      observed_at: "2026-10-23T08:00:00Z",
      label: "ratio",
      operation: "ratio",
      operands: ["F1", "F2"],
      derived_from: ["F1", "F2"],
      exact: { num: "1", den: "3" },
      formula: "F1 / F2",
      render: "0.333",
      precision: { places: 3, sigfigs: 3 },
      compatibility: "checked",
    })
    expect(derived.fact_id).toBe("F3")
    expect(nextId(ledger, "quote")).toBe("Q2")
  })

  test("measured rows store exact from their decimal", () => {
    const ledger = ledgerWith(measured("span", "12.50"))
    expect(ledger.rows[0].exact).toEqual({ num: "25", den: "2" })
  })

  test("retractRow keeps the row with status retracted", () => {
    const ledger = ledgerWith(measured("a"), measured("b"))
    retractRow(ledger, "F1", "wrong page")
    expect(ledger.rows).toHaveLength(2)
    expect(ledger.rows[0].status).toBe("retracted")
    expect(ledger.events[0]).toMatchObject({ fact_id: "F1", to: "retracted", reason: "wrong page" })
    expect(validateLedger(ledger)).toEqual([])
    expect(() => retractRow(ledger, "F9", "x")).toThrow()
  })

  test("supersedeRow points at the replacement", () => {
    const ledger = ledgerWith(measured("a"), measured("b"))
    supersedeRow(ledger, "F1", "F2", "newer filing")
    expect(ledger.rows[0].status).toBe("superseded")
    expect(ledger.events[0]).toMatchObject({ fact_id: "F1", replacement: "F2" })
    expect(validateLedger(ledger)).toEqual([])
  })

  test("supersedeRow refuses a replacement that is not active", () => {
    const ledger = ledgerWith(measured("a"), measured("b"))
    retractRow(ledger, "F2", "wrong page")
    expect(() => supersedeRow(ledger, "F1", "F2", "newer filing")).toThrow(/F2 is retracted/)
    expect(ledger.rows[0].status).toBe("active")
    expect(ledger.events).toHaveLength(1)
  })

  test("supersedeRow without a replacement throws and points at retract", () => {
    const ledger = ledgerWith(measured("a"))
    expect(() => supersedeRow(ledger, "F1", null, "newer filing")).toThrow(
      /supersede F1 needs a replacement row; use retract/,
    )
    expect(ledger.rows[0].status).toBe("active")
    expect(ledger.events).toHaveLength(0)
  })
})

describe("read and write", () => {
  test("write then read round-trips byte-identically", () => {
    const dir = tempDir()
    const ledger = ledgerWith(measured("span"), quoteRow("claim"))
    writeLedger(dir, ledger)
    const first = readFileSync(join(dir, LEDGER_FILENAME), "utf8")
    const loaded = readLedger(dir)
    expect(loaded).toEqual(ledger)
    writeLedger(dir, loaded)
    expect(readFileSync(join(dir, LEDGER_FILENAME), "utf8")).toBe(first)
    expect(readdirSync(dir)).toEqual([LEDGER_FILENAME])
    expect(loaded.schemaVersion).toBe(LEDGER_SCHEMA_VERSION)
  })

  test("a derived row with an exact rational round-trips and validates", () => {
    const dir = tempDir()
    const ledger = ledgerWith(measured("a"), measured("b"))
    addRow(ledger, {
      kind: "derived",
      value: "0.333",
      raw: "0.333",
      quote: "",
      extracted_by: "fact derive",
      observed_at: "2026-10-23T08:00:00Z",
      label: "third",
      operation: "ratio",
      operands: ["F1", "F2"],
      derived_from: ["F1", "F2"],
      exact: { num: "1", den: "3" },
      formula: "F1 / F2",
      render: "0.333",
      precision: { places: 3, sigfigs: 3 },
      compatibility: "checked",
    })
    writeLedger(dir, ledger)
    const loaded = readLedger(dir)
    expect(loaded.rows[2].exact).toEqual({ num: "1", den: "3" })
    expect(loaded.rows[2].value).toBe("0.333")
    expect(validateLedger(loaded)).toEqual([])
  })

  test("readLedger of a missing file is an empty ledger; writeLedger refuses an invalid one", () => {
    const dir = tempDir()
    expect(readLedger(dir)).toEqual(emptyLedger())
    const ledger = ledgerWith(measured("a"))
    ledger.rows[0].value = "abc"
    expect(() => writeLedger(dir, ledger)).toThrow()
    expect(readdirSync(dir)).toEqual([])
  })

  test("renderLedgerMarkdown lists every row", () => {
    const text = renderLedgerMarkdown(ledgerWith(measured("span"), quoteRow("claim")))
    expect(text).toContain("| F1 | measured | span |")
    expect(text).toContain("| Q1 | quote | claim |")
  })
})

describe("validateLedger checks events against rows", () => {
  test("a retracted event that carries a replacement is an error", () => {
    const ledger = ledgerWith(measured("a"), measured("b"))
    retractRow(ledger, "F1", "wrong page")
    ledger.events[0].replacement = "F2"
    expect(validateLedger(ledger).some((e: string) => /F1 is retracted but names replacement F2/.test(e))).toBe(true)
  })

  test("the last event for a fact must match its row status", () => {
    const ledger = ledgerWith(measured("a"), measured("b"))
    retractRow(ledger, "F1", "wrong page")
    ledger.rows[0].status = "active"
    expect(
      validateLedger(ledger).some((e: string) =>
        /F1 has status active but its last event moves it to retracted/.test(e),
      ),
    ).toBe(true)
  })

  test("a non-active row with no event is an error", () => {
    const ledger = ledgerWith(measured("a"))
    ledger.rows[0].status = "superseded"
    expect(validateLedger(ledger).some((e: string) => /F1 is superseded but has no status event/.test(e))).toBe(true)
  })

  test("an event with an invalid from or to status is an error naming the fact", () => {
    const ledger = ledgerWith(measured("a"))
    retractRow(ledger, "F1", "wrong page")
    ledger.events[0].from = "gone"
    const errors = validateLedger(ledger)
    expect(errors.some((e: string) => /events\[0\]: F1 is active, but the event moves it from gone/.test(e))).toBe(true)
    ledger.events[0].from = "active"
    ledger.events[0].to = "active"
    expect(
      validateLedger(ledger).some((e: string) => /events\[0\]: F1 cannot move from active to active/.test(e)),
    ).toBe(true)
  })
})
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