cohere usage rules

Copy Markdown View Source
  • cohere/map.md is derived. NEVER edit it by hand; run mix cohere.map after any structural change (new/renamed public context functions, schema fields, associations, routes, workers) and commit the diff in the same PR. The map diff is the ontology change — review it as such.
  • If cohere/map.md disagrees with the code, the file is stale — never the other way around. Regenerate; do not "fix" the map.
  • cohere/intent/*.md cards hold authored intent: purpose, invariants, decisions, non-goals. Edit the sections freely; NEVER edit the frontmatter (context/reviewed/surface/functions) by hand — it is machine-managed.
  • When mix cohere.check reports a drifted card: re-read the card against the current map and update any invalidated content. --accept is human-gated, and the gate is an explanation, not a paste: tell the human which design or decision drove the drift, show the exact +fun/1 −fun/2 delta, and say what your card edits now claim, so their confirmation is informed — then run mix cohere.check --accept <card> with --by <approver>. Do not accept without re-reading, and never unilaterally.
  • Non-trivial change? Start with mix cohere.design <slug> --contexts <ctx> and design in the doc, against its Existing ground section. Record decisions with their rejected alternatives; list the code you commit to delivering under Promised surface as backticked Module.fun/arity refs.
  • cohere/design/*.md frontmatter is machine-managed except contexts: and supersedes:. Never flip status: by hand — that is mix cohere.complete <slug>, which verifies the promised surface exists before accepting. Accepted designs are immutable history: supersede with a new design, never edit.
  • When a card re-review happens after a design lands, distill the design's durable decisions into the card and cite the design by slug — the card is the living constraint; the design is the record of the conversation.
  • A violated invariant or superseded decision in a card is either a bug in your change or a deliberate supersession — surface it explicitly; never silently contradict a card.
  • Before starting work that touches a context, run mix cohere.packet <contexts> and read it instead of re-exploring the repo. Trust the map for shape; read code for behavior. On an existing branch, mix cohere.packet --diff assembles the packet for exactly the contexts you changed; read its "Branch scope" note for changed files that did not map to a context and verify those by hand.
  • Do not copy facts from the map or cards into other documents. Link to them. One truth per fact.
  • mix cohere.check must exit 0 before a PR is done. Fix or accept — never ignore. Design advisories don't fail the build; read them anyway.