Metadata-Version: 2.4
Name: rootecho
Version: 0.1.0
Summary: Catch recurring root causes across postmortems. Zero dependencies, no server.
Author: yyfjj
License: MIT
Project-URL: Homepage, https://github.com/jjdoor/rootecho-py
Project-URL: Repository, https://github.com/jjdoor/rootecho-py
Project-URL: Issues, https://github.com/jjdoor/rootecho-py/issues
Keywords: postmortem,incident,sre,devops,root-cause,cli,incident-response,reliability,on-call
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# rootecho

**Catch recurring root causes across postmortems.** Heavyweight incident
platforms (rootly, incident.io) flag when a new incident shares a root cause
with a past one — teams without that budget just... don't find out, until the
same failure bites twice. `rootecho` does the comparison locally: no account,
no server, your incident history lives in your repo.

```bash
pip install rootecho
rootecho init incident.json      # scaffold a postmortem
rootecho add incident.json       # record it, flag any echo of a past root cause
rootecho check incident.json     # same check, no recording — use as a CI gate
```

This is the Python build — a Node build (`npx rootecho`) exists too and reads
the exact same `.rootecho/history.jsonl`, so a team split across both
ecosystems shares one history.

## Why

> "We use rootly to track this automatically. It flags when incidents have the
> same root cause as previous ones."

That's a paid, hosted feature. For everyone else, a postmortem gets written,
action items get filed, and six months later the exact same root cause causes
the exact same outage — because nobody had a system for "hey, we've seen this
before, and last time's fix never shipped." `rootecho` is that system, as a
zero-dependency local CLI.

## How it works

1. **Each postmortem is one JSON record** — `root_cause` (free text) and/or
   `root_cause_tags` (curated labels), plus `action_items` with a status.
2. **`add`/`check` compare it against your history** using Jaccard similarity
   over tags (primary signal) blended with free-text overlap (secondary). No
   ML dependency, no network call.
3. **A match above the threshold prints the past incident's action items** —
   so you see immediately whether last time's fix ever actually shipped.

## Incident format

```json
{
  "id": "INC-2026-014",
  "date": "2026-07-03",
  "title": "Payment webhook retries exhausted",
  "root_cause": "webhook retry queue misconfigured to drop after 3 attempts, no dead-letter fallback",
  "root_cause_tags": ["webhook", "retry-queue", "dead-letter", "config"],
  "action_items": [
    { "id": "AI-1", "description": "Add dead-letter queue for webhook retries", "owner": "alice", "status": "open", "due_date": "2026-07-20" }
  ]
}
```

Only `id` and one of `root_cause`/`root_cause_tags` are required. `rootecho init`
writes a starter file.

## Example

```
$ rootecho add inc-2026-014.json
⚠ root cause echo detected for "INC-2026-014":

  INC-2026-003 (2026-03-15) — 100% similar root cause
  Payment webhook retries exhausted
    ✓ Add retry backoff [done]
    ✗ Add monitoring alert for queue depth [open] — 93d overdue
  → 1 action item(s) from this past incident were never finished.

recorded to .rootecho/history.jsonl
```

## Commands

```bash
rootecho add <file>      # record + compare (always exits 0 on success)
rootecho check <file>    # compare only, no recording — exit 1 if an echo is found
rootecho list [--json]   # show recorded incidents and open action-item counts
rootecho init [file]     # write a starter incident.json
```

Flags: `--dir <path>` (state location), `--threshold <0-1>` (default `0.34`,
lower = more sensitive), `--json`, `--force` (init: overwrite; add: allow a
duplicate id).

## Storage

History is a JSON-Lines file at `.rootecho/history.jsonl`, **local to your
project by default** (not your home directory) — the idea is your team commits
it alongside the postmortems it describes, so `git blame`/`git log` on the file
doubles as an incident timeline. Override the location with `--dir` or
`$ROOTECHO_HOME`.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | `add` succeeded, or `check` found no echo |
| `1` | `check` found an echo of a past root cause |
| `2` | error (bad args, invalid JSON, duplicate id) |

## License

MIT
