| name | consult-echo |
| description | Search and cite Marin's Echo activity and wiki, then capture incident records or reusable shared knowledge. Use when looking for prior discussions, decisions, workflows, incident patterns, exact errors, tags, or identifiers; when prior context could shorten debugging; or when an investigation reaches resolution and its record or lessons may belong in Echo, docs, or OPS.md. |
Skill: Consult Echo
Search Echo before rediscovering prior work. Cite canonical Echo, GitHub, or
Discord URLs for the evidence you use.
Search
Use federated search when prior decisions, incidents, workflows, current GitHub
work, or indexed repository documentation could inform the task. Natural-language
questions work:
uv run infra/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:
uv run infra/echo/cli.py search "stalled TPU collective" \
--domain wiki --domain file --domain issue
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.
Search output is deliberately compact. Fetch any result's complete indexed or
raw-source detail with the printed ID:
uv run infra/echo/cli.py get <domain:id>
When a result materially helps, is irrelevant, or the result set fails the task,
submit a compact judgment using the exact query and printed result IDs:
uv run infra/echo/cli.py feedback --query "stalled TPU collective" \
--grade wiki:123=0 --grade file:lib/iris/OPS.md=10 \
<<< "The file result answered the task; wiki results were off-topic."
Use 0 for an irrelevant result and 10 for one that directly changes or answers the
task. Grade only results you evaluated. Always add a short stdin explanation of the
overall result quality without restating each score. Explanation-only feedback is valid
for an empty result set.
Use grep for exact strings in GitHub or Discord activity, with --source or
--kind when needed:
uv run infra/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. Use it at the
start of an investigation when prior context could materially shorten
debugging.
Choose the durable home
At resolution, choose the narrowest durable home:
- 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.
- Add one Echo entry for the evidence, decisions, and outcome of a specific
incident. Tag it
incident, debugging, the subsystem, severity, and
resolution; add ops for infrastructure incidents. Link its canonical Echo
URL from the associated PR or issue.
- 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 that entry only when the same
incident continues. Keep raw logs and commit diffs in their source systems; the
incident entry records the investigation and links the evidence. A fixed bug can
also justify a separate cross-incident synthesis when several incidents support
a reusable diagnostic pattern. Edit a near-duplicate synthesis instead of
adding another.
Write or revise a wiki note
Write for future action, not for exhaustiveness. Echo results are loaded into
limited model context, so every unnecessary detail makes later work slower and
more expensive. Prefer the shortest entry that changes what a future reader
will do:
- 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 so a search
result is useful before the full entry is fetched.
- Keep investigation history outside the wiki when it provides no reusable
decision or procedure. An issue, logbook, or source artifact is a better home
for a record whose only value is completeness.
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/echo/cli.py wiki add --file note.md
Revise the closest existing note:
uv run infra/echo/cli.py wiki show <id> > note.md
uv run infra/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.
