Prior-art research — cyberine research --prior-art (ks0sh)

Competitor and alternatives research that ends in a feature parity matrix and a recommendations ledger, where every recommendation leaves the report as a task id or a dated rejection reason.

Run recipe:

cyberine research --prior-art --depth quick "alternatives to fzf, the command-line fuzzy finder"
cyberine research --prior-art --depth deep --ours @.local/research/ours-widget.txt "competitors of the Widget tool"
cyberine research recs .local/research/prior-art-<slug>.md             # which recommendations are open, filed or rejected
cyberine research recs <report> --check                                # exit 1 while any recommendation has neither a task id nor a rejection reason
cyberine research recs <report> --json                                 # the ledger plus each disposition, for a skill to read
cyberine research recs <report> --save-batch --only R1,R3 | cyberine tasks save --input -
cyberine research recs <report> --save-batch --only R1,R3 --owner R3 --status backlog | cyberine tasks save --input -
cyberine research recs <report> --add-commands                         # single `cyberine tasks add` lines for the open ones instead
cyberine research dispose <report> R1 --task k3wf6                     # record R1 as filed (or covered by an existing task)
cyberine research dispose <report> R2 --reject "needs a sync engine, out of scope this quarter"

The same mode is reachable without the CLI (k30t5): the MCP research tool takes priorArt: true and ours: "<text>", and cyberine chat takes /xmode research then /run --prior-art [--ours <text|@file>] <subject>. Both write .local/research/prior-art-<slug>.md like the CLI.

What the report gains, between the ordinary sections and ## Sources: ## Feature parity matrix (rows are features, columns are Ours and each competitor; a has, partial or none cell carries the [N] source it rests on, and a cell no verified claim backs reads unknown), ## Recommendations (each with a do, a done-when, an effort and the matrix rows it closes), and ## Dispositions (empty until shaped). After ## Sources comes ## Recommendation ledger, a fenced prior-art-recommendations/1 JSON block that recs, dispose and the cyberine:research skill read. The matrix is built from the claims that survived verification, so a cell cannot cite a URL the run did not verify: an uncited has, partial or none cell is downgraded to unknown, and a recommendation with no sourced feature row is dropped before it reaches the report. The Ours column is whatever --ours carries (plain text, or @file relative to the current directory); without it every Ours cell is unknown.

The follow-up shaping is the cyberine:research skill: dedupe against cyberine tasks corpus, preview in titles, file the chosen ones with --save-batch (all six brief sections filled), then dispose. --owner R3 files the named recommendations as Owner: decide whether to ... tasks with exec: manual and no model, for a money, legal or positioning choice that no agent should run; --status backlog puts every filed task on the backlog instead of todo, which the A-Z flow uses so nothing becomes runnable before its owner checkpoint. Both work with --add-commands too, and --owner refuses an id that is not among the open recommendations being filed. Then dispose every recommendation and finish on recs --check exiting 0. dispose appends one line under ## Dispositions and refuses an unknown id, a second line for the same id, an empty reason or a malformed task id or date; rejections live in the research file, never on the board. If the matrix cannot be built (no synthesizer model, unparseable model output, no verified claims) the report is still written, the command prints prior-art: matrix NOT produced: <reason> and exits 1.

Cell verification (k30t5): after the matrix is built, every has, partial and none cell that cites a source is turned into one claim (Alpha offers "SSO" (note). or Gamma does not offer "SSO".) carrying its cited URLs, and the verify stage's ClaimVerifier runs it past independent skeptics with the same strict-majority refute rule as the claim verification step. A refuted cell becomes unknown with the skeptic's reason in its note, a recommendation left with no has or partial cell behind it is dropped, and the survivors are renumbered R1..Rn before the ledger is written. A line under the matrix states how many cells were checked, by how many skeptics, and how many were refuted, or that the check was skipped because no verifier model is configured. Cells are checked by the verify step's skeptic count capped at two (quick uses two, deep and max also use two), one model call per cell per skeptic, so a full 8 by 20 matrix costs up to 320 extra calls.

First live run (2026-10-04, --depth quick, run 8d3b6a44-02b0-42b6-9120-f4c789b1385d): 7 claims verified and 8 dropped produced a 5 by 5 matrix and 2 sourced recommendations; most cells were unknown, which is the expected shape at quick depth, and the matrix text came back in the wrong language until the matrix prompt was told to follow the subject's language (not re-run after that fix).

Unit-level checks, free and offline: npm run selftest:prior-art-matrix (schema normalisation, rendering, dispositions, save batch, and the --owner / --status shaping) and npm run selftest:prior-art-followups (the chat flags, the MCP request, the background launch env, and the cell verification pass with a stub verifier).

Known Limitations and Deferred Work: unknown means the web fleet found nothing it could verify, never that a competitor lacks the feature. --ours is taken on trust and is not checked against this repo, and the Ours column is never verified. Cell verification sees the cited URL, its title and the quote a verified claim recorded for it, not a fresh fetch of the page, so a skeptic judges the cell against what the run already read; a verifier error on a cell counts as not refuted and is reported as unchecked. The chat planner itself cannot start a prior-art run (only the operator's /run in research xmode does), and the MCP tool takes ours as text only. The live English shaping pass (a quick prior-art run whose recommendations all end disposed with recs --check exiting 0) has not been run since the cell verification landed. Dispositions are append-only lines edited in place in the report; an operator hand-editing them is read back as long as the line shape matches. Competitor pricing is only reported when the angle worker found the vendor's pricing page; the mode never estimates it. Recommendations are capped at 12 and features at 20 per report.