Deterministic integration layer: format-facts, pricing-diff, classify-request

.codex/skills/shipwright-concierge/SKILL.md

@@ -41,9 +41,10 @@ This skill gives Codex a conversational Shipwright entry point. Use it when the
 If fresh public-web evidence is needed, follow this protocol in order:
 
 1. First run the local research collector if available:
-   - `node .codex/scripts/collect-research.mjs --query "<primary query>" --mode auto`
-   - otherwise `node scripts/collect-research.mjs --query "<primary query>" --mode auto`
+   - `node scripts/collect-research.mjs --query "<primary query>" --mode auto`
+   - otherwise `node .codex/scripts/collect-research.mjs --query "<primary query>" --mode auto`
    - otherwise `node .claude/scripts/collect-research.mjs --query "<primary query>" --mode auto`
+   - Prefer the repo-level `scripts/collect-research.mjs` when available because it writes `facts.json`; the `.codex` and `.claude` copies are fallback collectors and may only emit the evidence pack.
 2. If `facts.json` exists alongside the evidence pack, read it first and use it as a structured shortcut before synthesizing from the full evidence pack.
 3. Interpret `facts.json` by `confidence_hint`:
    - `high`: use directly for structured fields, tables, and summaries, while keeping source attribution.

.codex/skills/shipwright-research-brief/SKILL.md

@@ -17,23 +17,42 @@ Use this skill for web-heavy product, market, and business research in Codex.
 
 ## Retrieval Workflow
 
-1. Translate the user's request into one primary query.
+1. **Classify the request** to configure retrieval before collecting:
+   - `node scripts/classify-request.mjs "<primary query>"`
+   - The output names a `requestType` (pricing, competitive, market-size, acquisition, funding, reviews, general), a collector-compatible `suggestedMode` (`standard`, `auto`, or `deep`), and `priorityFacts` to watch for in the facts sidecar.
+   - Use `suggestedMode` as the `--mode` value in step 2.
+
 2. Run the local collector first:
-   - `node .codex/scripts/collect-research.mjs --query "<primary query>" --mode auto`
-   - otherwise `node scripts/collect-research.mjs --query "<primary query>" --mode auto`
-   - otherwise `node .claude/scripts/collect-research.mjs --query "<primary query>" --mode auto`
-3. If `facts.json` exists alongside the evidence pack, read it first and use it as a structured shortcut before synthesizing from the full evidence pack.
+   - `node scripts/collect-research.mjs --query "<primary query>" --mode <suggestedMode>`
+   - otherwise `node .codex/scripts/collect-research.mjs --query "<primary query>" --mode <suggestedMode>`
+   - otherwise `node .claude/scripts/collect-research.mjs --query "<primary query>" --mode <suggestedMode>`
+   - Prefer the repo-level `scripts/collect-research.mjs` when available because it writes `facts.json` for the deterministic pre-flight. The `.codex` and `.claude` copies are fallback collectors and may only emit `evidence.json`/`evidence.md`.
+
+3. **Format the facts sidecar** if `facts.json` exists:
+   - `node scripts/format-facts.mjs path/to/facts.json`
+   - The compact block output (~300-500 tokens) is ready to inject directly into a synthesis prompt as structured evidence. Read it before the full evidence pack — if `priorityFacts` fields are all present at high confidence, the full pack may only be needed for context.
+
 4. Interpret `facts.json` by `confidence_hint`:
    - `high`: use directly for structured fields, tables, and summaries, while keeping source attribution.
    - `medium`: treat as provisional; verify against the cited evidence pack entry before relying on it for a material claim, comparison, or recommendation.
    - `low`: treat as a lead only; do not present it as settled unless corroborated from the evidence pack or another source.
    - if `confidence_hint` is missing, treat it as `medium`.
+
 5. Read the generated evidence pack.
 6. If the evidence pack is usable, synthesize from it without starting a broad `Web Search` pass.
 7. Only if the evidence pack still has material gaps should you use interactive browsing.
 8. Keep any follow-up browsing gap-focused rather than restarting the whole search pass.
 9. Treat raw `Web Search` as fallback, not first-pass retrieval, whenever the local collector is available.
 
+**For multi-competitor pricing requests:** run the collector once per competitor, then generate the comparison table from the specific facts packs you intend to compare:
+```bash
+node scripts/pricing-diff.mjs \
+  .shipwright/research/comp-a/facts.json \
+  .shipwright/research/comp-b/facts.json
+```
+If you staged the intended packs into a comparison-only directory, you can also use `node scripts/pricing-diff.mjs --dir path/to/comparison-set/`.
+Paste the table directly into the brief's pricing evidence section.
+
 ## Synthesis Rules
 
 - Keep the work bounded to one primary deliverable.

docs/deterministic-helpers-roadmap.md

@@ -64,6 +64,59 @@ Citation shortcut: if the document has a `## Sources` / `## References` /
 
 CLI: `node scripts/validate-artifact.mjs path/to/artifact.md --expect-sections "Sources,Risks"`
 
+Wired into:
+- `adversarial-review/SKILL.md` — Pre-Check step before manual review begins
+- `artifact-quality-audit/SKILL.md` — Step 1b pre-pass to floor Correctness scoring
+
+### Facts formatter (`scripts/format-facts.mjs`)
+
+Converts a `facts.json` sidecar into a compact structured block (~300-500 tokens)
+suitable for direct prompt injection, or a markdown report for human review.
+
+```
+node scripts/format-facts.mjs path/to/facts.json
+node scripts/format-facts.mjs path/to/facts.json --format markdown
+```
+
+Groups facts by source domain, reconstructs pricing tuples from shared excerpts,
+resolves product identity, and annotates adapter-sourced fields with `[schema]`.
+
+Wired into:
+- `shipwright-research-brief/SKILL.md` — Step 3 of the retrieval workflow
+
+### Pricing diff (`scripts/pricing-diff.mjs`)
+
+Builds a deterministic markdown comparison table from two or more `facts.json` packs.
+Produces: Competitor × Plan × Price × Billing × Free Tier × Confidence table,
+optional Review Signals table, and per-source Coverage Notes.
+
+```
+node scripts/pricing-diff.mjs facts-a.json facts-b.json
+node scripts/pricing-diff.mjs --dir path/to/comparison-set/
+```
+
+Wired into:
+- `pricing-strategy/SKILL.md` — Step 5 (Competitive Pricing Analysis)
+- `competitive-landscape/SKILL.md` — Step 3 (Positioning Analysis)
+- `shipwright-research-brief/SKILL.md` — multi-competitor pricing requests
+
+### Request classifier (`scripts/classify-request.mjs`)
+
+Pattern-matches a query string to a request type and returns collector hints.
+No network calls. Returns: `requestType`, collector-compatible `suggestedMode`
+(`standard`, `auto`, or `deep`), `priorityFacts`,
+`collectorHints`, `matchedSignals`, `confidence`.
+
+Request types: `pricing`, `competitive`, `market-size`, `acquisition`, `funding`, `reviews`, `general`
+
+```
+node scripts/classify-request.mjs "how does Stripe pricing compare to Paddle?"
+node scripts/classify-request.mjs --json "Series B funding in developer tools"
+```
+
+Wired into:
+- `shipwright-research-brief/SKILL.md` — Step 1 of the retrieval workflow
+
 ## Remaining backlog
 
 If Shipwright continues investing in deterministic acceleration, the next
@@ -88,6 +141,13 @@ highest-value additions are:
    identified; the adapter pattern is already in place.
 5. **`marketplace_last_updated` field** — useful for currency-checking cached
    listing data; add once a stable adapter target is confirmed.
+6. **Preflight classifier wiring into collect-research** — `classify-request.mjs`
+   currently produces hints for the caller to use manually. A future iteration
+   could have `collect-research.mjs` call it internally and auto-select `--mode`
+   when none is specified, reducing required arguments for common queries.
+7. **Pricing diff HTML output** — `pricing-diff.mjs` currently outputs markdown.
+   An `--html` flag could produce a self-contained table for pasting into
+   slide decks or Notion pages.
 
 ## Workflow-specific candidates