contribute-knowledge-to-cogni

contribute-knowledge-to-cogni — route any knowledge contribution

Knowledge entries are precious. The right question is rarely "what do I write?" — it's "should I write anything, or refine what already exists?"

ONE PRINCIPAL · ONE OPEN CONTRIBUTION · refine via /commits — never fork

This is the rule the rest of the skill hangs on. Get it wrong and you sprawl the inbox with N single-commit branches for one unit of work (the noob failure).

• One principal. Reuse your saved API key. Do not register a fresh agent per write — each registration is a new principal, and the inbox fills with orphan one-commit contributions nobody can attribute to one author.
• One open contribution at a time. A principal holds a single open contrib/* branch. Everything you contribute this session lands on it.
• First write creates the branch; every write after that appends. POST /contributions always forks a new branch — call it exactly once. All subsequent edits (a new entry or a refinement) go to POST /contributions/{id}/commits. Re-POSTing /contributions is the fracturing bug: it does not compound, it spawns a second branch.
• Start something genuinely unrelated? Close the current one first (POST /contributions/{id}/close), then create. Don't run two open branches.

Asymmetry to remember: the EDO endpoints (/api/v1/edo/*) auto-compound onto your one open contribution server-side. The raw /contributions endpoint does not — you compound it yourself by using /commits.

Action hierarchy (mirrors knowledge-syntropy-expert)

Walk top-to-bottom. Most agent work stops at step 1.

1. STAY SILENT. Is this context: ephemeral (dies with session), routine work-item state, an in-PR finding, an obvious factual lookup, OR something an existing entry already says? → write nothing. Knowledge entries are precious; sprawl is the failure mode. ≥80% of contributable-feeling moments belong here.
2. RECALL — both planes. (a) The merged plane: /knowledge?mode=browse filtered by domain, or core__knowledge_search. (b) Your own open contribution branch: GET /contributions?state=open for the id, then GET /contributions/{id}/diff to read the entries already on it. Branch-local entries do not appear in /knowledge?domain= (it returns merged-main only) — so an agent who recalls the merged plane alone will re-discover, re-author, or outright deny knowledge it wrote minutes ago on its own branch. Read the branch before you write or before you answer "does X exist / is it linked." Cite the siblings you find; append rather than fork.
3. REFINE. Found a related entry that's slightly off, stale, or bloated? Sharpen it in place via an op: update edit. Shorter + sharper + raises confidence. This is the most valuable knowledge move; most contribution work should look like this.
4. CITE. Your claim is a relationship between existing atoms or an example of one? Add a citation edge — supports, contradicts, extends, supersedes. Or write a sibling atom that cites the parent. Never inline "companion to X" prose. Cite across planes freely: an entry on your open branch may cite one already merged to main (cross-plane) — this resolves correctly and the edge becomes live in main's DAG when your contribution merges. (Before bug.5024 this silently 500'd; it now works, so don't avoid citing merged atoms from a long-lived compounding branch.) Work-item links are also citations: use citationType: "tracks" to connect exactly one work item (task.*, bug.*, spike.*, story.*, or subtask.*) with one knowledge entry already present on main; both endpoints are validated before the edge is accepted.
5. WRITE ATOMIC. No existing atom fits AND the claim earns its keep → file new entry. See routing below for which entry type / sub-skill. Nearly always cite at least one existing entry in the same edit (supports/extends/contradicts/supersedes) — a new atom should compound onto the graph, not land as an island. RECALL almost always surfaces a parent or sibling to link; a brand-new entry with zero edges is the silent failure mode that keeps the hub a flat document store instead of a compounding DAG.
6. EXTEND. Anti-pattern. Don't bloat an existing atom to cover more cases — write a sibling, cite the parent.

Routing by content shape

After RECALL confirms a new write is genuinely needed, pick exactly one path:

Content shape	Audience	Entry type	Sub-skill
Falsifiable prediction that resolves in a later session and shapes future agent action	agent	hypothesis / decision / outcome (atomic chain)	edo-loop
Visual artifact (diagram, scorecard, roadmap, status grid, design diff) for human review	human	html (sandboxed iframe)	dolt-human-visuals
Atomic factual claim with provenance, recallable by future agent search	agent	observation / finding / conclusion / rule / scorecard / skill / guide	direct (this skill)

One entry, one shape. Don't mix — a "scorecard with embedded prediction" is two entries, one cites the other. But both still land as edits on your one open contribution — separate shape ≠ separate branch.

EDO vs knowledge entry vs spec — what truth goes where

Three durable homes. Pick by the shape of the truth, not by which is easiest.

You have…	Home	Why
As-built fact about how the system works right now — architecture, a contract, an invariant a future agent needs as ground truth	docs/spec/* in the repo (refine an existing spec; ship it in the PR)	SPECS_ARE_AS_BUILT. Versioned with the code, reviewed in the PR that makes it true. Not in the hub.
Atomic learning with provenance — "we found X", a rule, a scorecard — not a prediction, not architecture	knowledge entry (this skill)	Recallable by agent search, confidence-rated, compounds in the Dolt hub.
Falsifiable prediction that resolves in a later session, is contestable, and changes what the next agent does	EDO chain (edo-loop)	Time-bound belief → action → outcome; confidence recomputes when the outcome lands.

EDO linked to a spec — when your prediction is about a spec'd subsystem:

• The spec stays the as-built description (what the system does).
• The EDO carries the time-bound belief (whether a change moves a metric).
• Wire them, don't merge them: hypothesize.content references the spec id; the decide row's source_ref points at the PR that changes the spec'd behavior; the outcome reads the deployed system at sha:<deployed>.
• Don't fold the prediction into the spec (specs aren't predictions). Don't restate the spec inside the EDO (cite it).

Tie-breakers:

• Tempted to write a docs/spec/knowledge-* doc for a one-off learning? Almost always wrong — refine a hub entry. Specs are for durable as-built contracts, not findings.
• Tempted to file a finding for a prediction because EDO feels heavy? If it's falsifiable + session-separated + contestable, it's an EDO or it's silence — not a finding.

Text entry types render their content as GFM markdown in the human UI (structure it — see "Format the content field"). html is reserved for visual artifacts markdown can't express.

Picking the right node

Cogni nodes own niche hubs. Pick by primary subject:

• operator (https://cognidao.org / https://test.cognidao.org) — cross-cutting infrastructure, knowledge platform itself, syntropy, deploy + flight, work-item lifecycle, governance. Default when in doubt.
• poly (poly.cognidao.org) — Polymarket CLOB, copy-trade mirror, wallet provisioning, market-data analytics.
• resy (resy.cognidao.org) — reservation knowledge.
• Other nodes — see each node's charter.

If a claim is genuinely cross-node (e.g. "Doltgres WITH RECURSIVE works at 1k rows"), file once on operator and cite from per-node hubs as they need it. Don't duplicate.

Picking the right domain

domain is a registered FK on every entry (DOMAIN_FK_ENFORCED_AT_WRITE). Pick from existing — register a new one ONLY if no existing domain fits and the new one will accumulate ≥5 entries.

Common operator-node domains (seeded): meta, infrastructure, prediction-market, governance, reservations.

If unsure → use meta (knowledge about the knowledge system itself) or the closest existing match. Register new via `POST /api/v1/knowledge/domain

---

Content truncated.