From dbeb2599bf4075871453942e1d7e1388b19d2cc3 Mon Sep 17 00:00:00 2001 From: CodexManvik Date: Thu, 17 Sep 2026 22:49:28 +0530 Subject: [PATCH] docs: a single-page project flowchart The judge's note on the deck was that it covers a lot and takes too long to get through, and asked for a 10-minute pitch. One page that carries the whole product does more for that than any amount of trimming, so this adds a sixth diagram: five steps along a spine, a decision diamond under each, and every exit the system can take. The point the picture makes is that three of the five exits are the system declining to touch production. The geometry gate earned its keep again: the first cut routed the rollback branch straight through the "runbook fits?" diamond, which no amount of looking at the code would have shown. Co-Authored-By: Claude Opus 5 --- docs/diagrams/06-project-flowchart.dark.svg | 84 ++++++++++++ docs/diagrams/06-project-flowchart.light.svg | 84 ++++++++++++ docs/diagrams/README.md | 4 +- docs/diagrams/index.html | 8 ++ scripts/make-diagrams.mjs | 137 +++++++++++++++++++ 5 files changed, 316 insertions(+), 1 deletion(-) create mode 100644 docs/diagrams/06-project-flowchart.dark.svg create mode 100644 docs/diagrams/06-project-flowchart.light.svg diff --git a/docs/diagrams/06-project-flowchart.dark.svg b/docs/diagrams/06-project-flowchart.dark.svg new file mode 100644 index 0000000..b7facf1 --- /dev/null +++ b/docs/diagrams/06-project-flowchart.dark.svg @@ -0,0 +1,84 @@ + + + + + + + + + + + How IntelliOps handles one incident + Five steps, four decisions, and every exit the system can take. + + Alert storm + 8 metrics fire + on one fault + + + Correlate + median/MAD baseline + one Situation + + + Diagnose + rank the cause + pick a runbook + + + Gate + RBAC, reversible + human if not earned + + + Execute and verify + 1 of 7 typed verbs + re-check the metric + + + self-heals? + from outcomes + + + yes + + Suppressed + no page raised + + + runbook fits? + confidence floor + + + no + + Escalated + a human is told, nothing is guessed + + + approved? + or timed out + + + no + + No action + refusal recorded in the audit trail + + + recovered? + vs its baseline + + + yes + + Closed + verified healthy, playbook credited + + no + + Rolled back + undone automatically, then escalated + Every box is code that runs. Nothing on this page is a plan. + Measured on a live cluster: 75% of alerts never become a page, and the fastest alert-to-verified-fix was 28.8 seconds. + diff --git a/docs/diagrams/06-project-flowchart.light.svg b/docs/diagrams/06-project-flowchart.light.svg new file mode 100644 index 0000000..87a8675 --- /dev/null +++ b/docs/diagrams/06-project-flowchart.light.svg @@ -0,0 +1,84 @@ + + + + + + + + + + + How IntelliOps handles one incident + Five steps, four decisions, and every exit the system can take. + + Alert storm + 8 metrics fire + on one fault + + + Correlate + median/MAD baseline + one Situation + + + Diagnose + rank the cause + pick a runbook + + + Gate + RBAC, reversible + human if not earned + + + Execute and verify + 1 of 7 typed verbs + re-check the metric + + + self-heals? + from outcomes + + + yes + + Suppressed + no page raised + + + runbook fits? + confidence floor + + + no + + Escalated + a human is told, nothing is guessed + + + approved? + or timed out + + + no + + No action + refusal recorded in the audit trail + + + recovered? + vs its baseline + + + yes + + Closed + verified healthy, playbook credited + + no + + Rolled back + undone automatically, then escalated + Every box is code that runs. Nothing on this page is a plan. + Measured on a live cluster: 75% of alerts never become a page, and the fastest alert-to-verified-fix was 28.8 seconds. + diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md index b56814c..a88ba5b 100644 --- a/docs/diagrams/README.md +++ b/docs/diagrams/README.md @@ -1,6 +1,6 @@ # Diagrams -Five diagrams, each in a dark and a light variant, generated by +Six diagrams, each in a dark and a light variant, generated by `node scripts/make-diagrams.mjs`. **Do not hand-edit the SVG.** Edit the generator and regenerate, or the geometry gate below @@ -13,6 +13,7 @@ stops meaning anything. | `03-recovery-ladder` | What happens when the first fix does not work, and where we stop | | `04-data-sources` | The three stores and which question each one answers | | `05-earned-autonomy` | How a playbook reaches unattended execution, and how it loses it | +| `06-project-flowchart` | The whole product on one page: five steps, four decisions, five exits | Open `index.html` to view them all with a theme switch. @@ -35,6 +36,7 @@ non-zero if any two overlap or anything falls outside the canvas. It has already - two boxes running off the right edge of `02-incident-flow` - the `situations.diagnosed` label being wider than the gap it sat in, so it overprinted the node on either side +- the rollback branch in `06-project-flowchart` routed straight through a decision diamond What the gate does **not** check is whether the result reads well. Look at the diagrams after regenerating. diff --git a/docs/diagrams/index.html b/docs/diagrams/index.html index d17eac9..55d2cd4 100644 --- a/docs/diagrams/index.html +++ b/docs/diagrams/index.html @@ -91,6 +91,14 @@

04 · the three data sources

05 · autonomy is earned

Earned autonomy +
+

06 · the whole project on one page

+ The project as a single flowchart +