Read Me First — Incident Response Orchestrator

Welcome — how to use this document

This document is the starting point for everyone who encounters the Incident Response Orchestrator — evaluators, new team members, managers, and the person who will administer it. It assumes no technical background: every specialist term is explained the first time it appears, and again in the glossary near the end. Read it top to bottom, or jump to what you need: what the product is and who it serves (the first four sections), what to do first and how to set everything up (the two after that), what everyday and long-term use look like (the next two), then what the product deliberately does not do, what ships in the preview, the questions people ask most, a glossary, and where to go next.

Who this is for

The primary users are the people who get woken up when an online system misbehaves: on-call engineers, site-reliability and platform engineers, IT operations staff, and security responders. ("On-call" simply means taking a turn being the person who can be reached when something breaks.) They use the product to be alerted, to coordinate a fix, and to keep a record of what happened.

The secondary users are engineering leaders and managers. They rarely respond to problems themselves, but they read the dashboards, review what went wrong and what was learned, and use that to improve how the team works.

There is a third, often forgotten audience: your customers. The product can publish a public status page — a simple web page, requiring no sign-in, where anyone can check whether your services are healthy and read updates during a disruption.

The product is built for a mid-size organisation — think hundreds of staff operating on the order of two hundred online services. Each deployment serves exactly one organisation: your installation holds your people and your data, and nobody else's.

What it does

The Incident Response Orchestrator manages the journey from "something is wrong" to "resolved and learned from".

It starts by receiving alerts — automated warnings sent by the monitoring tools that watch your systems. Raw alerts arrive in floods, so the product groups related ones together and filters out duplicates and noise, turning hundreds of signals into a handful of meaningful problems. When a problem is serious, it pages the right person: it knows who is on call right now, and if that person does not respond in time, it automatically escalates to the next person in line.

From there, everything about the problem is tracked as one incident — a single shared record with a timeline that permanently logs every action, update, and decision, along with who made it and when. Responders can work the incident from the web application or directly from Slack, the team chat tool. While the technical work happens, the product helps you keep customers informed through the public status page.

When the dust settles, it captures the lessons: a postmortem (a written review of what happened and why), action items to prevent a repeat, and metrics that show how quickly your team acknowledges and resolves problems.

The product also includes AI assistance, deliberately kept on a short leash. The AI can draft a postmortem, suggest wording for a status update, suggest a severity level, and point out patterns across past incidents. Every AI contribution is clearly labeled as AI-generated and lands in a queue as a draft — a person reviews it and accepts or dismisses it. Nothing the AI produces takes effect without human approval.

The world it serves

Almost every organisation now runs online services — websites, apps, payment systems, internal tools. These services fail. A server crashes, a change goes wrong, a dependency slows down. When that happens at 3 a.m., someone has to notice, someone has to be woken, the right people have to work together to fix it, customers may need to be told, and afterwards the organisation should learn something so the same failure hurts less next time.

The field that deals with all of this is called incident response, practised by people in roles such as on-call engineering, site reliability engineering (SRE), and IT operations. An "incident" is their word for any unplanned disruption or degradation of a service that needs coordinated attention.

Without tooling, incident response runs on frantic group chats, phone trees, and memory. Handoffs get dropped, two people fix the same thing twice, nobody tells the customers, and a month later nobody remembers what actually happened. This product exists to give that occupation a calm, repeatable process: reliable alerting, fair on-call rotas, one authoritative record, and a habit of learning from every failure.

What it connects to

People and roles. Everyone signs in through your organisation's single sign-on (SSO) — the same "sign in with your company account" system used for your other workplace tools. There are three roles. A viewer can look at everything but change nothing. A responder can act: acknowledge pages, declare and work incidents, write postmortems. An administrator configures the system: people, services, schedules, integrations. The first time anyone signs in, an account is created for them automatically with read-only viewer access; an administrator then promotes people to responder or administrator under Settings.

External systems. Four kinds of outside systems plug in:

• Monitoring tools — the software that watches your services. Each tool you use is registered as an alert source and given its own unique web address (a webhook URL) to send its alerts to. Any tool that can send a web notification can feed the product.
• Slack — the team chat tool. Responders can declare, update, and resolve incidents with Slack commands without leaving the conversation.
• Email (optional) — if your deployment is configured with a mail service, people can also be notified by email. Paging never depends on email; without a mail service the product simply notifies in-app and in Slack.
• The public status page — read by your customers, requiring no account.

Everything above lives inside a single-organisation deployment: one installation, one organisation, one set of data.

Your first run

What you do first depends on who you are.

If you are the first administrator. Before you arrive, a technical operator will have initialized the deployment using the production initialization guide — be aware that the procedure described there is guarded and destructive (it wipes the database it targets) and is strictly for operators, not everyday users. During that initialization the operator names an email address as the bootstrap administrator — yours — and sets the organisation's name and defaults. Simply sign in through your organisation's SSO with that email and you automatically hold the administrator role: there is no separate registration step. Your first action: open Settings → Users and confirm you are listed as an administrator. Then work through the setup checklist in the next section.

If you are anyone else. Sign in through SSO. An account is created for you automatically with read-only viewer access, so you can immediately look around without breaking anything. If your job is to respond to incidents or to administer the system, ask an existing administrator to promote you — role changes happen under Settings and take effect right away.

Setting up your environment

Setup is a sequence of screens, each answering a question. The order matters: paging needs schedules and escalation policies, which need people and services. Everything in this checklist lives under Settings, which has its own menu; the working screens — Dashboard, Incidents, Alerts, On-call, Postmortems, Status pages — are what you use once it is set up. The product's screens carry the details, so this list explains the purpose of each step rather than every click.

1. Confirm organisation settings (with your deployment operator) — the organisation's name and defaults, including the alert-group idle window and whether incident Slack channels are archived when an incident is resolved. These are set during initialization and have no in-app screen, so ask your operator to confirm or change them.
2. Add people and teams (Settings → Users; teams via the API) — promote the humans who will respond, and group them into teams. Roles change on the Users screen; teams are created through the API and then appear as choices when you register services and create schedules. This defines who can be paged at all.
3. Register your services (Settings → Services) — the things that can break: your website, your API, your payment system. Each service records who owns it and how severe an alert must be before an incident is automatically opened for it.
4. Create on-call schedules (Settings → Schedules) — who is reachable, on what rotation. Overrides let people swap shifts for holidays. The On-call screen then shows who is actually carrying the pager right now.
5. Define escalation policies (Settings → Escalation) — if the on-call person does not acknowledge a page in time, who is tried next, and after them, who.
6. Connect your alert sources (Settings → Integrations) — create one source per monitoring tool. Each source gets a unique webhook URL; paste that URL into the monitoring tool's notification settings so its alerts flow in. This is the moment real signals start arriving.
7. Connect Slack (deployment configuration, plus the Slack app itself) — your operator supplies the Slack bot token and signing secret, and the Slack app is pointed at the product's command, interaction, and event URLs. Each person then links their own Slack member ID in Settings → My Slack account so pages reach them as direct messages.
8. Configure email delivery (deployment configuration, optional) — ask your operator to connect a mail service if you want email notifications; skip it and the product works fine without.
9. Create your status page (Status pages) — define the components your customers care about, then publish the page when you are ready for it to be publicly visible at its web address.
10. Add maturity features when ready (optional) — runbooks (step-by-step response guides) and SLOs (reliability targets) are added on the Settings → Services screen; grouping and suppression rules to cut noise live in Settings → Alert rules, and outbound webhooks that notify your own systems sit beside your alert sources in Settings → Integrations.

Integrators and developers who want the exact payload formats behind these steps — and the endpoints for the parts that have no screen yet — should read the API reference.

Day-to-day use

For responders, most days are quiet: alerts arrive, get grouped, and auto-close if their underlying noise stops. When something real happens, you are paged — as a Slack message if you have linked your account, and always in Notifications, at the foot of the left menu, where a badge counts what you have not yet read. You acknowledge the page — telling everyone "I'm on it" — and the time this takes is tracked as MTTA (mean time to acknowledge). Serious alert groups at or above a service's threshold become incidents automatically; smaller ones you can promote to an incident yourself. You work the incident from the web app or from Slack: assign roles, set the severity (SEV1 for the worst emergencies down to SEV4 for minor issues), post updates, optionally follow a runbook — the product guides you through its steps and you mark each one complete as you do it. If customers are affected, a responder chooses to make the incident visible on the status page and posts updates there. When fixed, you resolve the incident; the time from start to fix is tracked as MTTR (mean time to resolve). Everything you and your teammates did sits in the incident's timeline — a permanent, unchangeable record of who did what, when. Afterwards, you create the postmortem from the incident: the timeline is already there as its backbone, the AI offers a clearly-labeled draft to start from, and you publish the finished review with action items.

For administrators, day-to-day work is upkeep: keeping schedules and rotations current, arranging overrides when people are away, promoting new joiners, glancing at integrations to confirm alert sources and Slack are healthy, and pruning alert rules that no longer earn their place.

For leaders, the product is a reading habit rather than a pager: dashboards show MTTA and MTTR trends, postmortems tell you what actually happened, and the AI's cross-incident pattern findings — labeled and human-reviewed like everything the AI does — point at recurring weaknesses worth investing in.

Ongoing care and periodic tasks

A little regular attention keeps the system trustworthy. Suggested cadence:

• Weekly — review alert noise: look for alert groups that never became incidents and pages that woke someone for nothing, then tune your deduplication and suppression rules so signals stay meaningful.
• After every incident — hold the postmortem while memories are fresh, publish it, and assign action items with owners.
• Monthly — review open action items (are they actually getting done?), check on-call coverage and fairness (upcoming gaps, who is carrying too many overrides), and read the MTTA/MTTR dashboards for trends.
• Quarterly — review user accounts and roles, the health of your integrations (alert sources, Slack, outbound webhooks), whether the status page's components still match reality, and whether runbooks are still accurate.

One important boundary: in this deployment model, database backups, infrastructure care, upgrades, and restoring after a platform failure are the hosting platform's responsibility, handled by your deployment operator. There is no in-app backup button, and none is needed — your job inside the product is the operational hygiene above, not system administration.

What it deliberately does not do (yet)

To set expectations honestly: the product today does not execute runbooks autonomously — runbooks are guided checklists and a person performs every step. It does not predict degradations before they happen. Its monitoring integrations are webhook-based rather than installable apps: Datadog, Prometheus and CloudWatch each have their own verification method and severity mapping, so their alerts arrive correctly labelled, but you connect them by pasting a web address into the tool rather than clicking "install", and any other tool that can send a webhook works through the generic source. And there is no mobile app or voice assistant; you use it through the web application and Slack. Some of these ideas appear in the project README — read that as vision and market background, not as a description of current features.

What comes preloaded, and how to start fresh

If you are looking at the preview or the online demo, everything in it is invented: roughly sixteen incidents with full timelines, several hundred alerts already grouped, on-call schedules and rotations, published postmortems, service level objectives, and a customer status page. It exists so you can judge the product with something to look at instead of empty screens.

Two things worth knowing about that data. It is display data, not accounts — the people named in it cannot be signed in as; you sign in as yourself through your organisation's single sign-on. And it is ephemeral in the preview image: restart the container and you are back to the same starting snapshot, which is the point of a preview.

A real deployment never carries any of it. Your operator prepares an empty system with the production initialization guide, which creates your organisation's settings and your first administrator and nothing else — the first thing you see is your own empty incident list, waiting for the setup checklist above.

Common questions

Why didn't my alert page anyone? Most often it joined an existing group that had already paged, matched a suppression rule such as a maintenance window, or arrived for a service with no escalation policy attached. The Alerts screen shows which, and Settings → Alert rules lists every grouping and suppression rule in plain language — readable by everyone, changeable by administrators.

Can I correct a mistake in a timeline? No, and deliberately so. Nothing in an incident's record can be edited or deleted; you add a correcting entry instead. That is what makes the timeline worth trusting afterwards.

Why is there no AI in my deployment? The AI features appear only when your operator has connected a provider. Without one, everything else works identically — the drafts simply are not offered. Nothing in the product waits on the AI.

An incident appeared that nobody declared. A severe enough alert group promotes itself, if the service it belongs to has a threshold set. The first entry in the timeline says so, and names the rule.

How do I sign out? Exit, at the bottom of the left menu, below your name. It ends your session here and hands you back to your identity provider — there is deliberately only one way out, so nobody leaves half signed-in.

Who can see our incidents? Only people signed in to your organisation. The status page is the single exception, and it shows only what a responder has deliberately published.

Glossary

• Acknowledge — a responder's "I've seen it, I'm on it" for a page. MTTA (mean time to acknowledge) averages how long this takes.
• Action item — a follow-up task from a postmortem, with an owner, meant to stop the problem recurring.
• AI draft — a suggestion written by the product's AI (a postmortem draft, proposed status text, a severity suggestion). Always labeled as AI-generated; a person must accept it before it counts.
• Alert — an automated warning from a monitoring tool that something looks wrong. An alert is a signal; an incident is the managed response. Many alerts may feed one incident, and some alerts never become one.
• Alert group — related alerts bundled together so a flood of signals reads as one problem. Idle groups close automatically.
• Deduplication — rules that recognise repeats of the same alert and fold them together instead of piling up.
• Escalation policy — the ordered list of who to page next when a page is not acknowledged in time.
• Incident — an unplanned disruption or degradation being actively managed: it has a severity, a status, assigned people, and a timeline.
• On-call — taking a scheduled turn as the person who can be reached when something breaks.
• Override — a temporary change to an on-call schedule, e.g. covering a colleague's holiday shift.
• Page — an urgent notification demanding acknowledgement, sent to whoever is on call. "Paging" is sending it.
• Postmortem — the written review after an incident: what happened, why, and what will change. Blame-free by convention.
• Resolve — mark an incident as fixed. MTTR (mean time to resolve) averages how long incidents take from start to fix.
• Rotation — the repeating pattern by which an on-call schedule cycles through team members.
• Runbook — a step-by-step guide for handling a known situation. The product walks a responder through the steps; a person performs each one.
• Severity — how bad an incident is, from SEV1 (drop everything) to SEV4 (minor). Sets urgency and who gets involved.
• SLO (service level objective) — a reliability target for a service. Its error budget is how much unreliability you can still afford this period before the target is missed.
• Status page — the public web page where customers see service health and incident updates. No sign-in required.
• Suppression — rules that silence alerts you expect and do not want to be paged for, such as during maintenance.
• Timeline — the incident's permanent, append-only record: every action and update, attributed and timestamped, never edited or deleted.

Where to get help and what to read next

The rest of this folder

Document	What it is for
READ-ME-FIRST.md	This document — the orientation for everyone.
production-initialization.md	For deployment operators: preparing a real environment for first use. Guarded and destructive; not for everyday users.
api-reference.md	For integrators and developers: every endpoint the product exposes, and which role may call it.
openapi.yaml	The same interface in machine-readable form, for generating clients or importing into an API tool.
store-thumbnail.png	The product's catalogue image; nothing to read.

Longer-form material — plain-language and detailed user guides, installation and integration guides, technical documentation and white papers — lives in the collateral/ folder at the top of the repository, alongside a single-page website you can open in any browser.

Who to ask

Where to go from here depends on your role. Integrators and developers who need endpoints, payloads, and webhook formats should read the API reference. Deployment operators preparing a stage or production environment should follow the production initialization guide — once more: that procedure is guarded and destructive, wiping the target database, and is for operators only. For the project's broader ambitions, the repository README is the vision and market-research backdrop — not a feature list. For everything day-to-day, ask your administrator inside the product (Settings → Users shows who that is); for platform matters — sign-in problems, hosting, backups, upgrades — contact your deployment operator. Welcome aboard.