Skip to content

Latest commit

 

History

History
41 lines (39 loc) · 2.56 KB

recommendation-basis.md

File metadata and controls

41 lines (39 loc) · 2.56 KB

Recommendation basis: the contract this plugin applies

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: verified plus what verified it (a file: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.
  • 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.md in the marketplace repository).