# Write Ops Log

> Publish a tagged Echo record after a live infrastructure incident, then link its canonical URL from the associated pull request or issue.

- Skill: `marin-community/write-ops-log` (Agent Skill)
- Install (CLI): `npx skillmds@latest add marin-community/write-ops-log`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marin-community/write-ops-log/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: marin-community (https://skillmd.com/u/marin-community)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/marin-community/write-ops-log

---


# Skill: Write an Ops Log

Publish the incident record to Echo. Do not add a repository debug-log file.
An incident is a service, production run, or shared operational system failure
or degradation that required diagnosis or mitigation. Ordinary code debugging,
implementation notes, experiment progress, and local failures are not incident
records.
The audience is a future engineer who must quickly decide what to check or do
next. Record the smallest set of facts that supports that action. Link raw
evidence and detailed chronology rather than reproducing them; Echo entries
consume limited model context whenever they are retrieved.

## Search before writing

Invoke `consult-echo` and run its complete search-before-write sequence. Edit
the existing entry when it covers the same incident. Start with a natural-language
`infra/marina/apps/echo/cli.py search`, fetch likely matches with `get <source-id>`, and use
`grep` for the exact error or run identifier. Create a new entry for a different
incident even when the symptom resembles an older one; link related incidents
and create or extend a separate synthesis only when they establish a reusable
cross-incident pattern.

## Draft the Echo entry

Write an OKF document in a temporary file:

```markdown
---
type: wiki-note
title: "Incident YYYY-MM-DD: <system> — <symptom>"
use_when: when investigating <specific symptom or exact error>
tags:
  - incident
  - debugging
  - ops
  - <system>
  - <severity>
  - <resolution>
---

# <System or component>: <symptom>

## TL;DR

- <user-visible symptom>
- <diagnostic discriminator or immediate action>
- <fix or remaining caveat>

## Response

<The shortest safe procedure for diagnosing, mitigating, or avoiding the
incident.>

## Cause and resolution

<Only the evidence needed to justify the response and explain the resolution.>

## Artifacts

- <Canonical PR, issue, dashboard, durable log bundle, or report>
```

Use the incident's investigation date. Use lowercase kebab-case tags and no
more than 20. Always include `incident` and `debugging`; add `ops` for
infrastructure work, followed by the subsystem, severity, and resolution.
Omit any body section that adds no actionable value. Add a compact original
report, investigation step, or course correction only when it changes how a
future reader should recognize or respond to the incident.

## Write the record

Create a new incident:

```bash
uv run infra/marina/apps/echo/cli.py wiki add --file incident.md
```

Continue the same incident:

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

Both commands print the canonical Echo URL. Return that URL and add it to the
associated PR description or issue. Do not commit the temporary OKF file.

## Keep the record useful

- Preserve exact error strings and canonical evidence URLs.
- Prefer decisions, discriminating evidence, and response steps over narrative.
  Do not paste raw logs, duplicate source artifacts, or narrate every tool call.
- Link readers to the external source of record when its detail is not needed
  to choose or carry out the action.
- Keep incident-specific detail here. Promote recurring procedures and
  guardrails to the relevant `OPS.md`.
- Update `docs/` when behavior or configuration guidance belongs with the
  repository.
- Record an unknown root cause as unknown; do not fill the gap with speculation.