The plugin-shipped statement of the recommendation-basis convention. The full
convention, with its boundary and adopters, is
docs/contracts/recommendation-basis/README.md in the marketplace repository.
- Recommendation. An option, verdict, default, or next step put to the user for a decision.
- Grounding bar. Local: read the affected code, config, or document and list its consumers and blast radius, including other repositories that use a shared artifact. External: tiered sources, with the date or version each reflects and any credible dissent named. For a tool, version, or API: official docs, then authoritative articles and recognized experts, then community. For a design pattern: the canonical source that defines it (the Gang of Four, Fowler's catalogs, Enterprise Integration Patterns, the DDD books) and recognized experts who build on it. Recency never discounts a canonical pattern definition.
- Popularity is not correctness. A pattern's use in templates, samples, or popular repositories shows adoption, not that it is right. Check it against the principle it claims to serve, and say so when a common pattern fails that check. A book cited from recall is recall; a canonical catalog page fetched this session verifies the pattern's definition.
- Consequential means cross-repo, shared infrastructure, irreversible or costly to reverse, or security. A consequential recommendation must clear the bar; any other may rest on judgment if its label says so.
- Three outcomes. Every recommendation ends in exactly one:
- verified: presented with
Basis: verifiedplus what verified it (afile:line, tool output, or URL fetched this session); - judgment: presented with
Basis: judgment; only for a recommendation that is not consequential; - withheld: a consequential recommendation that cannot be settled. It
is not presented and carries no
Basis:label; it is surfaced as an open question that names the evidence that would settle it.
- verified: presented with
- Re-emit. When evidence changes a pending recommendation, restate it as
old → new → why, where new is a verified or judgment recommendation or the
withheld open question; name the unchanged ones in one line. When the
evidence is dispatched work that returned while open items wait on the
user, the async-round-presentation contract governs instead: the message
ends with every open item in full, the moved one marked
(
docs/contracts/async-round-presentation/README.mdin the marketplace repository).