web-research-kb-refresh

Web-Research KB Refresh

Operational pattern for refreshing a knowledge base from the web with predictable cost, time, and provenance. Generalizes the consulting-toolkit /facts-update pattern so it applies to any KB-backed analysis (vendor facts, compliance posture, market data, security advisories, library/API references, etc.).

Companion rules:

• 015-context-engineering.mdc - prompt packing, retrieval, compaction
• 120-utilities.mdc - the underlying tools (lynx, curl, jq, ripgrep)
• 316-zero-trust.mdc - audit and observability principles

When to invoke

Use when the user asks to:

• "Refresh the KB" / "update the facts" / "regenerate from the web"
• "Pull current pricing / docs / advisories" for a list of items
• "Re-research vendor X across the catalog"
• Build a new long-running command that calls web tools at scale

Do not use for:

• One-off queries (just call WebSearch / WebFetch directly)
• Real-time streams (this pattern is batch-style)
• Anything where the answers are not stored in a structured KB

The Five Golden Rules

1. Hard cap per unit of work - state it up front; refuse to exceed it.
2. Cross-reference threshold - claims need >=2 independent sources or 1 vendor-primary + 1 analyst.
3. Up-front warning + explicit confirmation before any potentially-long operation.
4. Atomic write + rollback - archive the old file before writing; verify the new file imports / parses; restore on failure.
5. REVIEW placeholders, never fabrication - if coverage is thin, mark the gap explicitly with reason; never silently invent.

The pattern, end to end

flowchart TD
    start[User invokes refresh] --> warn["Up-front warning + AskQuestion confirm"]
    warn -->|"No"| stop1[Stop]
    warn -->|"Yes"| scope["AskQuestion: scope (all / gaps / specific)"]
    scope --> enum[Enumerate units of work]
    enum --> dump[Dump current KB to JSON]
    dump --> loop["For each unit (per item)"]
    loop --> initial["Initial pass: 2-3 multi-intent searches"]
    initial --> deep["Deep reads: 0-3 fetches on highest-signal hits"]
    deep --> gaps["Targeted gap-fills: 0-3 focused searches"]
    gaps --> cap{"<= 9 calls?"}
    cap -->|"No, mark REVIEW"| synth
    cap -->|"Yes"| synth[Synthesize per-column answer]
    synth --> evid["Record evidence tuple per claim<br/>(source, vendor-docs, analyst, market, etc.)"]
    evid --> nextItem{More items?}
    nextItem -->|"Yes"| loop
    nextItem -->|"No"| assemble[Assemble entries JSON]
    assemble --> apply[Apply: archive-then-write-then-verify]
    apply --> ok{Import OK?}
    ok -->|"No"| rollback[Restore archived file]
    ok -->|"Yes"| summarize[Summarize per-item + REVIEW gaps]