Use Echo

Use this entry point for prior-work search and knowledge publication. For live incidents, read incident records, which defines when to publish, how to format the record, and how to update it. Ordinary search does not require publishing a note.

Search Echo before rediscovering prior work. Cite canonical Echo, GitHub, or Discord URLs for the evidence you use.

Treat one incident, debugging session, or research question as one logical investigation across continuation turns. Search once when that investigation starts, then reuse relevant results already fetched in the conversation. Do not search again merely because the user asks a follow-up question or requests the next operational step. Search again only when the incident, question, repository scope, or freshness requirement changes, when a selected workflow requires a current duplicate check, or when the user explicitly asks.

Search

Use a natural-language federated search:

uv run infra/marina/apps/echo/cli.py search "how do I diagnose a stalled TPU collective" --limit 10

Search covers wiki, file, pr, and issue by default. Repeat --domain to select a subset.

File search infers the configured Marin-community repository from the current Git checkout, including ordinary contributor forks. Pass --repository <owner/repo> to choose one configured repository or --repository all to search all six. The CLI prints the resolved file scope once. Searches that omit the file domain work outside a Git checkout.

Discord is excluded by default because messages may be noisy or untrusted. Add --domain discord only when discussion history is relevant, and open the canonical URL when surrounding thread context matters.

Fetch a result's full detail with the value in the SOURCE ID column:

uv run infra/marina/apps/echo/cli.py get <source-id>

The GRADE KEY column is for feedback. get also accepts file grading keys with numeric suffixes, such as file:20849.

Grade evaluated results with the exact query and printed keys:

uv run infra/marina/apps/echo/cli.py feedback --query "stalled TPU collective" \
  --grade wiki:730=0 --grade file:731=10 \
  <<< "The file result answered the task; wiki results were off-topic."

Use 0 for irrelevant and 10 for directly useful. Grade only evaluated results and always explain overall quality on stdin, including for an empty result set.

Use grep for exact strings in GitHub or Discord activity, narrowing with --source or --kind when needed:

uv run infra/marina/apps/echo/cli.py grep "FAILED_PRECONDITION" --source github

Use rg for exact identifiers in the current checkout. Echo's file index follows the periodically refreshed GitHub head, so it does not contain branch-only or uncommitted files. Use wiki search --tag <tag> when tags, rather than federated relevance, define the desired synthesis. Authentication reuses the shared Marin login via iris login; see Echo setup and access.

Run this search sequence before adding or editing a wiki note.

Choose the durable home

Every live infrastructure incident, as defined in incident records, gets a standalone Echo record linked from its associated PR or issue. Also use the narrowest reusable home when the incident or other work changes durable guidance:

• Update OPS.md for a recurring operational procedure, diagnostic workflow, or guardrail in one subsystem.
• Update docs/ for reusable product or user guidance that belongs with the repository.
• Edit an existing Echo wiki note for a cross-cutting pattern or synthesis that has no single repository home.
• Add a wiki note only when the searches find no near-duplicate.

Create one incident entry per incident and edit it while the same incident continues. Keep raw logs and diffs in their source systems. Edit a near-duplicate synthesis instead of adding another.

Write or revise a wiki note

Write the shortest entry that changes a future action:

• Lead with an actionable value: a decision, command, diagnostic discriminator, guardrail, or recovery step.
• Include only the facts needed to support or apply that action. Link to the canonical PR, issue, dashboard, log bundle, or report for chronology and raw evidence instead of copying it into Echo.
• Put the action in the title, use_when, or opening paragraph.
• Keep chronology without a reusable decision in an issue, logbook, or source artifact.

Write an Open Knowledge Format document:

---
type: wiki-note
title: Stalled TPU collectives can have several low-power causes
use_when: when a distributed TPU job stalls before the first optimizer update
tags:
  - ops
  - debugging
  - iris
---

State the reusable pattern, how to distinguish its causes, and the evidence URLs.

Use lowercase kebab-case tags. Keep the title concrete and make use_when describe the future search trigger. Make the body stand alone. Cite canonical URLs inline. Concision still requires enough context to apply the guidance safely; do not omit a precondition, destructive-action warning, or material caveat.

Create a note:

uv run infra/marina/apps/echo/cli.py wiki add --file note.md

Revise the closest existing note:

uv run infra/marina/apps/echo/cli.py wiki show <id> > note.md
# Edit note.md.
uv run infra/marina/apps/echo/cli.py wiki edit <id> --file note.md

Both write commands print the canonical Echo URL. Return and cite that URL after every add or edit.