docs/how-it-works

How it works

A deterministic seven-stage pipeline turns incoming telemetry webhooks and DSN crash events into a human-ready GitHub issue draft — with the AI scoped to explanation only.

Core rule: Deterministic code gathers facts. The LLM only explains those facts. It never selects suspect commits, assignees, or severities — those come from Git and fixed arithmetic rules.

Pipeline stages

1 · Ingest & verify

The crash event arrives at Ichnois’s Edge Gateway webhook (/api/v1/telemetry/ingest or /api/{project_id}/envelope/). Project DSN authentication, 8-layer perimeter inspection, and rate limiting run synchronously. Invalid or malformed payloads are rejected immediately.

2 · Parse in-app frame

The stack trace is parsed to identify the outermost in-app frame — stripping container path prefixes (e.g. /app/, /workspace/) and filtering out third-party library frames. The result is a single (file, line, function) tuple.

3 · Fingerprint & deduplicate

A deterministic SHA-256 fingerprint is computed from the exception type, normalised file path, and line number. If the fingerprint already exists in the run store, the event is suppressed as a duplicate without further processing.

4 · Blame at release SHA

A GitHub GraphQL blame query is issued against the deployed release commit SHA. This identifies the last author and commit to touch the failing line. The suspect commit diff is then fetched via REST API and truncated to a safe context budget (≤ 6 KB).

5 · Redact secrets

The diff text passes through a regex-based secret scanner that strips bearer tokens, AWS access keys, Stripe secrets, database connection strings, and common password patterns before the prompt is assembled.

6 · Bounded AI explanation

The LLM receives: the normalised stack frame, the suspect diff, and a strict system prompt forbidding it from identifying suspect authors, naming commit hashes, assigning severity, or making deployment recommendations. It outputs a domain label, a root-cause hypothesis, and exactly 3 verification steps.

7 · Human approval gate

The assembled draft (blame metadata + AI explanation + severity) is stored with status pending_approval. A Slack notification is dispatched. The dashboard shows the draft for engineer review. Only after explicit human approval does the GitHub issue get published.

Deterministic Pipeline Flow

The incident triage pipeline executes deterministically step-by-step. The pseudocode below illustrates the verification and blame flow.

Pipeline Orchestration Logic

1	# Triage Pipeline Execution Flow
2	def run(event: dict) -> TriageResult:
3	payload = parse(event) # extract in-app frame
4	fp = fingerprint(payload) # SHA-256 dedup key
5	if is_duplicate(fp):
6	return TriageResult(status="duplicate")
7
8	blame = get_blame(payload) # GitHub GraphQL @ release SHA
9	diff = get_diff(blame) # suspect commit diff (≤6 KB)
10	clean = redact(diff) # strip secrets
11	explain = llm_explain(clean) # bounded explanation only
12	severity = compute_severity(event)
13	draft = build_issue(payload, blame, explain, severity)
14
15	store_run(draft) # persisted for human review
16	notify_slack(draft)
17	return draft # status = "pending_approval"

What the AI cannot do

Select or name a suspect commit hash
Assign an issue to a specific engineer
Determine incident severity (that uses deterministic rules)
Access file system, git push, or deploy infrastructure
Receive raw credentials or un-redacted environment values