otto-project-knowledge

name	otto-project-knowledge
description	Operate Otto's project knowledge safely: query pages, manage project charters and delivery, evaluate references, update current truth with reasons, append evidence, and review status. Use when an agent needs to read or change durable project knowledge.

Otto project knowledge operations

Use the daemon-owned project-knowledge tools as the only write path. The canonical store is Markdown, kept either in the repository under .otto/knowledge or host-local under the daemon's $OTTO_HOME, depending on how the project is configured. The tools are identical in both cases, and either way current truth and its provenance must be changed atomically by Otto rather than by editing files directly.

Read

• At task start, consult the automatically injected active-page catalog. Use list_project_knowledge, read_project_knowledge, or read_project_knowledge_root for pages relevant to the task before broad repository searches.
• Use query_project_knowledge when the relevant page is not obvious. Normal reads return only confirmed active pages. Include inactive pages only for an explicit knowledge review.
• Read compiled truth, evidence, tags, and the complete timeline. Treat superseded pages as history, not current guidance.
• The optional KNOWLEDGE.md beside the store is on-demand project guidance. When it holds project-specific content the injected catalog names its actual path; read it before writing or managing Knowledge. Do not load it merely because a task reads existing Knowledge. Unlike record pages and the generated index, the project may edit or remove this file directly; baked-in behavior applies when it is absent.

Write

• Use record_project_knowledge for a new fact. Include one of decision, constraint, requirement, or architecture, a precise title, rich Markdown compiled truth, evidence, and useful tags. Use a readable kebab-case id when a specific human slug matters. New pages start as proposed.
• Use record_project_charter for a durable initiative. Include rich Markdown outcomes, scope, constraints, and acceptance criteria. Review status says whether the charter is trusted; delivery status independently says whether it is chartered, in build, partial, blocked, complete, retained as reference material, deferred, or cancelled.
• Use update_project_delivery for a delivery or structured progress change. Supply a reason. Progress is completed, total, and unit; Otto derives percentage.
• Use record_project_reference for an external source and its project-specific evaluation. Record adopted and rejected sources. Use update_project_reference when disposition or URL changes.
• Use update_project_knowledge_root to maintain background, architecture, flow, mindmap, stack, and roadmap. Preserve rich Markdown and link atomic pages with [[wiki links]].
• Use update_project_knowledge_truth only when the current understanding changes. Supply a concrete reason and preserve the expected-update timestamp to detect stale edits.
• Use append_project_knowledge_evidence when new provenance strengthens a page without changing its current truth.
• Use set_project_knowledge_status to confirm or supersede only after explicit user agreement. A proposal is not authorization to confirm it.
• During exploration, trial and error, and implementation, keep tentative conclusions in the task context or .tmp/; do not turn each query, hypothesis, attempted fix, or abandoned approach into Project Knowledge.
• At the end of the effort, after the requested outcome is verified and before the final handoff, perform one knowledge reconciliation pass. An effort ends when the requested work is complete or a stable result is being handed off, not at the end of every assistant turn.
• In that pass, review the relevant active pages and any related proposed pages. Update the best existing page, charter delivery record, or reference instead of creating an overlapping page.
• Record only stable, evidence-backed outcomes that will matter beyond the current task: an explicit decision or requirement, a verified constraint or architecture claim, a measured finding, actual charter progress, or a reference whose project impact is now known. If the effort produced no such outcome, write nothing.
• A direct request to create, ingest, review, or revise Project Knowledge may write during the task; it is itself the effort being performed. Never turn a proactive proposal into confirmed truth without agreement.
• Use delete_project_knowledge only for accidental or junk pages after the user explicitly approves deleting that exact page. Supersede valid historical knowledge instead.
• Run lint_project_knowledge_links after changing links. Fix current truth or roots, never old timeline entries.

Review discipline

• Prefer one durable page over several overlapping pages.
• Record facts that are difficult to reconstruct from code and likely to matter in six months.
• Name concrete files, tests, documentation, commits, or user statements as evidence.
• Separate observed facts from recommendations and label uncertainty.
• Do not preserve failed experiments merely because they happened. Keep one only when the failure is itself a verified, reusable finding that changes future work.
• Keep review status, delivery status, and reference disposition distinct.
• Do not record people or team relationships; that belongs to team or personality memory.
• Never store secrets, credentials, temporary TODOs, routine implementation details, or copied source.
• If project knowledge is unavailable on the host, report the capability gap. Do not fall back to a second storage format.