continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 128 Wiki Activity

docs(P50): add talking points files + update README to 4-step process
acdl-ci / Lint (push) Successful in 7s
Details
acdl-ci / Test (push) Successful in 28s
Details
acdl-ci / Platform check-only (offline) (push) Successful in 9s
Details

Browse Source 
Create two talking points markdown files — one per deck — distilling the
source of truth (speaker notes + content) into presenter-ready cues indexed
by the Marp deck's 10-slide structure.

Each file has:
- One section per Marp slide (## Slide N — Title), matching the Marp deck
- 3-6 talking point bullets per slide — punchy, actionable cues distilled
  from the source markdown's speaker notes
- A key takeaway per slide — the one memorable thing the audience should
  walk away with

The talking points are the middle layer between the source of truth (full
detail + speaker notes) and the Marp deck (what the audience sees). They
give the presenter a cue sheet for delivery without repeating either layer.

README updated:
- 3-step → 4-step process (added Step 4: talking points)
- Process diagram updated with the 4th step
- Directory layout updated with the two new files
- 'Adding a new presentation' checklist updated with step 6 (distill talking
  points)
- Current decks table updated with a talking points column

---ci---
phase: 50
milestone: v1.9
status: complete
requirements:
  covered: []
  partial: []
---/ci---
This commit is contained in:
Jon Chery
2026-07-23 15:58:35 +00:00
parent 1eeee323c0
commit 016068fd46
3 changed files with 330 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/presentations/README.md
+60 -18
View File
@@ -2,20 +2,23 @@
Leadership-facing presentation decks for the ACDL platform.
## The 3-step slide creation process
## The 4-step slide creation process
Every presentation in this folder is produced by the same three-step process.
**Never edit the Marp deck or the PPTX directly** — always start from the full
markdown source of truth (Step 1), synthesize the Marp deck (Step 2), then
export to PPTX (Step 3). This keeps a reviewable, plain-text source of truth
for every deck.
Every presentation in this folder is produced by the same four-step process.
**Never edit the Marp deck, the PPTX, or the talking points directly** —
always start from the full markdown source of truth (Step 1), synthesize the
Marp deck (Step 2), export to HTML + PPTX (Step 3), then distill the talking
points (Step 4). This keeps a reviewable, plain-text source of truth for
every deck and a presenter-ready cue sheet for delivery.
```
Step 1: full markdown Step 2: Marp deck Step 3: PPTX export
(source of truth) ──► (lean, no notes) ──► (presentation-ready)
*.md *-marp.md *.pptx
+ speaker notes + embedded PNG diagrams + embedded images
+ mermaid code blocks + Marp frontmatter
Step 1: full markdown Step 2: Marp deck Step 3: HTML + PPTX Step 4: Talking points
(source of truth) ──► (lean, 10 slides) ──► (rendered) ──► (presenter cues)
*.md *-marp.md *.html / *.pptx *-talking-points.md
+ speaker notes + embedded PNG diagrams + 3-6 bullets per slide
+ mermaid code blocks + Marp frontmatter + key takeaway per slide
+ maturity badges + indexed by Marp slide #
+ no speaker notes + content distilled from Step 1
```
### Step 1 — Full markdown (source of truth)
@@ -103,17 +106,52 @@ PNG diagrams are embedded in the file. PPTX files are not committed to the
repo (binary, no meaningful diffs) — they are uploaded to the Gitea release
as downloadable attachments.
### Step 4 — Talking points (presenter cues)
**File convention:** `<deck-name>-talking-points.md` (e.g.
`how-the-platform-works-talking-points.md`).
Distill the source of truth (Step 1) into presenter-ready cues, indexed by
the Marp deck (Step 2) slide structure:
- **One section per Marp slide** — `## Slide N — Title`, matching the Marp
deck's 10-slide structure exactly. The Marp deck provides the indexing and
context (what the audience sees); the source markdown provides the content
(the speaker notes, the detail, the nuance).
- **3-6 talking point bullets per slide** — punchy, actionable cues distilled
from the source markdown's speaker notes. NOT the speaker notes verbatim
(those are too long and too contextual). These are prompts: "Land this
point," "Contrast with X," "Be honest about Y."
- **Key takeaway per slide** — the one memorable thing the audience should
walk away with from that slide.
- **No content duplication** — the talking points reference the Marp slides
for visual context and the source markdown for full detail. They don't
repeat either; they bridge them.
**Why this file exists:** a presenter needs a cue sheet they can glance at
during delivery — not the full speaker notes (too long), not the Marp slides
(no detail). The talking points file is the middle layer: what to say, in
what order, with what emphasis, per slide.
**When to update:** re-distill the talking points whenever the Marp deck
structure changes (slides added, removed, merged, or re-ordered) or whenever
the source markdown's speaker notes are updated. The talking points are a
*derived artifact* — if a fact is wrong, fix it in the source markdown (Step 1)
and re-distill.
## Directory layout
```
docs/presentations/
├── README.md ← this file
├── how-the-platform-works.md ← Step 1: full source of truth
├── how-the-platform-works-marp.md ← Step 2: Marp deck
├── how-the-platform-works-marp.md ← Step 2: Marp deck (10 slides)
├── how-the-platform-works.html ← Step 3: rendered HTML (committed)
├── how-the-platform-works-talking-points.md ← Step 4: presenter cues (10 sections)
├── the-developer-experience.md ← Step 1: full source of truth
├── the-developer-experience-marp.md ← Step 2: Marp deck
├── the-developer-experience-marp.md ← Step 2: Marp deck (10 slides)
├── the-developer-experience.html ← Step 3: rendered HTML (committed)
├── the-developer-experience-talking-points.md ← Step 4: presenter cues (10 sections)
└── assets/
├── puppeteer-config.json ← no-sandbox config for mmdc
├── mmd/ ← mermaid source files (Step 2 input)
@@ -241,7 +279,11 @@ attachments to the Gitea release.
`docs/presentations/<deck-name>.html`.
5. **Render to PPTX** with `--allow-local-files` and upload to the Gitea
release (do not commit PPTX to git).
6. **Verify** the PPTX slide count and that media files are embedded:
6. **Distill the talking points** as `<deck-name>-talking-points.md` — one
section per Marp slide, 3-6 talking point bullets + key takeaway, content
distilled from the source markdown (Step 1), indexed by the Marp deck
(Step 2) slide structure.
7. **Verify** the PPTX slide count and that media files are embedded:
```bash
python3 -c "
import zipfile, re
@@ -254,7 +296,7 @@ attachments to the Gitea release.
## Current decks
| Deck | Source of truth (Step 1) | Marp deck (Step 2) | Rendered HTML (Step 3) | Audience |
|---|---|---|---|---|
| How the Platform Works | `how-the-platform-works.md` | `how-the-platform-works-marp.md` | `how-the-platform-works.html` | CTO, Head of Cloud, Head of Infra, Head of DevOps |
| The Developer Experience | `the-developer-experience.md` | `the-developer-experience-marp.md` | `the-developer-experience.html` | CTO, Head of Cloud, Head of Infra, Head of DevOps |
| Deck | Source of truth (Step 1) | Marp deck (Step 2) | Rendered HTML (Step 3) | Talking points (Step 4) | Audience |
|---|---|---|---|---|---|
| How the Platform Works | `how-the-platform-works.md` | `how-the-platform-works-marp.md` | `how-the-platform-works.html` | `how-the-platform-works-talking-points.md` | CTO, Head of Cloud, Head of Infra, Head of DevOps |
| The Developer Experience | `the-developer-experience.md` | `the-developer-experience-marp.md` | `the-developer-experience.html` | `the-developer-experience-talking-points.md` | CTO, Head of Cloud, Head of Infra, Head of DevOps |
docs/presentations/how-the-platform-works-talking-points.md
+131
View File
@@ -0,0 +1,131 @@
# How The Platform Works — Talking Points
> **Companion to:** `how-the-platform-works-marp.md` (10 slides)
> **Content source:** `how-the-platform-works.md` (full source of truth with speaker notes)
> **Purpose:** Presenter-ready cues — 3-6 talking points per slide + the one key takeaway the audience should remember.
> **Audience:** Senior Leadership — CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
---
## Slide 1 — Title
**Talking points:**
- Brief introduction — this deck explains *how* the platform works internally, not what the developer experience is (that's the companion deck)
- Set the frame: the platform is not a CI/CD tool — it's the organizational lever for shipping safely at the pace the business demands
**Key takeaway:** This is a platform that computes safety, doesn't assume it.
---
## Slide 2 — The Problem & The North Star
**Talking points:**
- Open with the cost of the status quo — every team running its own pipeline, its own Terraform, its own review checklist is paying a tax that doesn't differentiate the business
- Walk through the 4 frictions quickly: cognitive load, operational work, red tape, scalability. Don't dwell — the North Star is the resolution
- Land the North Star quote: "declare intent → safe production deployment" — this is the entire value proposition in one sentence
- The litmus test: if a platform engineer still has to touch a ticket for a dev→qa promotion, we haven't delivered the vision
- Close with the two anti-goals: "not a general-purpose AI" and "not a permissive delivery highway" — the platform is deliberately scoped, not trying to be everything
**Key takeaway:** The platform absorbs all four frictions. Declare intent, not execute operations.
---
## Slide 3 — The Contract-Driven Model
**Talking points:**
- Emphasize the asymmetry — the consumer's surface is intentionally tiny (module + environment + inputs), the platform's surface is large and opinionated
- The contract is the API — it's deliberately small so it can be reviewed, validated, and audited
- The consumer does not write infrastructure modules, workflow logic, or adapter code — they declare intent; the platform reconciles, provisions, and progresses
- Land the "no AWS account, no VPC, no state backend" point — the platform owns the blast radius. Consumers can't drift into misconfigured state or over-permissioned roles because they never touch them
**Key takeaway:** A single YAML contract. The platform owns everything else — including the blast radius.
---
## Slide 4 — The End-to-End Flow
**Talking points:**
- Walk the flow left to right once — don't dwell on internals. The point is that the flow is fixed, opinionated, and identical for every consumer
- Land beat 1: security and policy checks run *before* any infrastructure is created — not after the fact, not as a post-deployment audit
- Land beat 2: every stage produces a record that feeds the confidence signal and the evidence stream. There is no "unchecked" path
- Tease the confidence signal (next slide) — this is where "safety is computed" lands
**Key takeaway:** The same pipeline, every time. Checks before creation, evidence at every stage.
---
## Slide 5 — Zero-Trust by Default
**Talking points:**
- This is the slide for the Head of Cloud/Security — the key phrase is "blast radius contained to the consumer's own stack"
- Contrast with the common failure mode: shared CI roles that can touch any account resource. The platform's ABAC model scopes every action to the consumer's own tagged resources
- OIDC means no long-lived credentials in consumer repos — each job mints a short-lived token. Be honest: this is testing on GitHub Actions runners today; all-runner coverage is planned
- The static-key override exists for edge cases but is rotated daily on platform runners — it is never the default
**Key takeaway:** A consumer can only touch the resources it created. One consumer can never affect another.
---
## Slide 6 — Safety is Computed, Not Assumed
**Talking points:**
- This is the bet that separates this platform from "yet another CI/CD tool" — reliance on operator instinct or tenure is not a substitute for a computed, auditable signal
- Walk the threshold table: dev ≥ 0.50 (autonomous) → qa ≥ 0.75 (QA attests) → prod ≥ 0.90 (SRE attests) → dr ≥ 0.95 (SRE + DR drill). The bar rises automatically with sensitivity
- A single critical policy finding hard-blocks the deployment — critical findings are not averaged away. This is non-negotiable
- When the platform halts, it gives a measured, explainable reason — never an opaque debugging exercise. Leadership cares because it makes promotion decisions *reviewable*
- The thresholds are tunable by Infra & Ops + SRE jointly, and any override is itself a confidence-event in the audit stream
**Key takeaway:** Safety is a measurable, explainable signal — not a gut feeling. A single critical finding blocks everything.
---
## Slide 7 — Security by Construction
**Talking points:**
- The phrase to land is "secure by default, not secure by effort" — teams don't opt in to security, it's on by construction
- Policy checks (Checkov, Wiz, Kyverno) are normalized to a single schema — we can add a new security tool without changing the confidence model or the evidence stream
- Tagging standards are enforced, not advisory — a missing `acdl:owner` tag fails the check, it doesn't warn
- Encryption is on every resource with per-stack customer-managed keys — no shared keys across stacks, 90-day rotation
- The decommission flow is the counter-argument to "deletion protection makes cleanup impossible" — it's a deliberate, gated, two-SRE-approval path with CMDB validation, not a lock with no key
**Key takeaway:** Encryption, deletion protection, policy checks — on by default. Decommission is gated, not impossible.
---
## Slide 8 — Accountability & Audit
**Talking points:**
- The "lower environments autonomous, higher environments attested" tenet is the resolution to the classic "move fast vs. be safe" false dichotomy
- Be honest: the separation-of-duties *mechanism* is designed and the dev path is wired; the qa/prod/dr wiring is on the roadmap
- The audit trail is a byproduct of deployment, not a project — every deployment writes a hash-chained evidence event synchronously (RPO = 0)
- Be honest about the ledger: the outbox + hash chain is testing today; the full regulatory ledger (S3 Object Lock, JWS signatures, daily checkpoints) is planned
- Every production change is traceable to a human attestation — approver identities are the only durable record outside the VCS's audit log
**Key takeaway:** Dev is autonomous. Higher environments are attested. Every change is evidenced. The audit trail is a byproduct, not a project.
---
## Slide 9 — Testing vs. Planned
**Talking points:**
- Close on honesty — the platform delivers real, verifiable value today, and the roadmap is concrete, not aspirational hand-waving
- Walk the left column (Testing) quickly — 11 capabilities that work internally today, from contract-driven deploys to encryption by default to uptime monitoring
- Walk the right column (Planned) — be clear about what's not yet done: HITL wiring, full regulatory ledger, compliance milestone, environment self-service, dynamic module creation, additional engine adapters
- Invite questions on any "planned" item — each has a defined milestone and a clear reason it isn't shipped yet (usually an upstream dependency, not an engineering gap)
- Emphasize: 0 consumer adoption today — "Testing" means it works internally, not that it's released
**Key takeaway:** 11 capabilities testing today. 9 planned items on a concrete roadmap. Zero consumer adoption — yet.
---
## Slide 10 — The Vision Realized
**Talking points:**
- Close on the strategic frame — the platform is not "a CI/CD tool," it's the organizational lever for shipping safely at the pace the business demands
- Velocity without sacrificing safety: speed is in the ergonomics (a simple contract, a one-line `uses:`), safety is in the gates the consumer cannot bypass
- Security, observability, and compliance as platform defaults — not per-team effort, not post-hoc remediation
- Auditability as a byproduct, not a project — every production change traceable to a human attestation and a tamper-evident evidence event
- Infrastructure as a utility, not a craft — teams consume, they don't maintain. The platform compounds value over time by learning from recurring patterns
- The path to the citizen developer — the same safety envelope that serves a senior engineer will serve a non-technical consumer. Expanding who can ship safely without lowering the bar
**Key takeaway:** The investment is in the abstraction, not the tool. Ship safely at the pace the business demands, with the security and audit posture the regulators require.
docs/presentations/the-developer-experience-talking-points.md
+139
View File
@@ -0,0 +1,139 @@
# The Developer Experience — Talking Points
> **Companion to:** `the-developer-experience-marp.md` (10 slides)
> **Content source:** `the-developer-experience.md` (full source of truth with speaker notes)
> **Purpose:** Presenter-ready cues — 3-6 talking points per slide + the one key takeaway the audience should remember.
> **Audience:** Senior Leadership — CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
---
## Slide 1 — Title
**Talking points:**
- Brief introduction — this deck covers *who uses the platform and how fast/safe they ship*, not the internal mechanics (that's the companion deck)
- Set the frame: velocity without sacrificing safety, and security/observability/compliance as platform defaults rather than per-team effort
**Key takeaway:** The consumer surface is intentionally tiny. The platform's surface is large and opinionated.
---
## Slide 2 — Two Consumer Surfaces, One Platform
**Talking points:**
- This is the thesis of the deck — the two surfaces are *parallel*, not a progression. A citizen developer doesn't "graduate" to the developer surface
- Both produce a contract; both get the same treatment. The platform is opinionated in what it accepts, regardless of who is declaring
- The leadership takeaway: we expand who can ship safely without lowering the bar. There is no "citizen developer mode" with weaker checks
- The citizen developer surface is agentic — an AI agent produces a contract that passes the same safety envelope as a senior engineer's. Be honest: the skill catalog and real agent runtime are planned
**Key takeaway:** Two consumer surfaces, one safety envelope. No weaker mode for non-technical users.
---
## Slide 3 — The Contract — The Entire Consumer Surface
**Talking points:**
- Hold this slide — the audience should sit with how small the consumer surface is. Three things: app code, a contract, a one-line CI definition
- The contract is a single YAML file: module, environment, inputs. That's the entire consumer-facing interface to production
- Walk the "does not" list quickly — no infrastructure modules, no platform repo cloning, no cloud credentials, no state backends. Every item is a category of toil the platform removes
- For the Head of DevOps: this is the lever for throughput — the bottleneck moves off the platform team's ticket queue
- The consumer never touches platform internals — the platform fetches itself at run time. When the platform ships a fix, every consumer on a floating tag gets it on their next run
**Key takeaway:** Three things. That's the entire consumer-side surface. Everything else is the platform's job.
---
## Slide 4 — The Developer Feedback Loop
**Talking points:**
- This directly answers "but developers hate platforms that hide what they're doing" — the platform is opinionated about *what* runs, not *opaque* about *that* it runs
- Streamed output by default — the plan, policy results, and each check record flow to stdout. A `--quiet` mode exists for log-only contexts
- PR comments after every successful pipeline stage — a developer always knows where they stand without refreshing a dashboard
- Connection strings posted as PR comments — human-readable, no hunting. Runtime secrets go to encrypted Parameter Store, never to logs
- The "errors become GitHub issues" point is a DX win that also helps the platform team — every consumer failure is a tracked, queryable artifact, not a lost log line
- Clear, explainable halt reasons — a policy violation, an insufficient confidence signal, or a missing attestation. Never an opaque debugging exercise
**Key takeaway:** The platform closes the feedback loop — streamed output, PR comments, clear halt reasons, no secrets in logs.
---
## Slide 5 — Versioned, Predictable Releases
**Talking points:**
- This is the "no surprise upgrades" story — consumers aren't forced to chase the platform, and the platform isn't forced to support N forks of every workflow
- Floating MAJOR + MINOR tags (e.g. `@v1.6`) — a consumer automatically receives patch updates within the line. Pin to exact version for stability, or float on MAJOR only for new features
- Semantic versioning with a clear contract: interface → MAJOR, behavior → MINOR, lifecycle → PATCH
- Unversioned references (`@main`, bare) are discouraged — the versioned tag is the only immutability lever a consumer has
- The automated release job computes the next semver on merge to main, creates the tag, and updates the floating tags — no manual release process
**Key takeaway:** Consumers control when they absorb platform improvements. No surprise upgrades.
---
## Slide 6 — Friendly Onboarding
**Talking points:**
- This looks like a small thing; it's actually a cultural one — the platform's posture is "help me get started," not "you should have known"
- First impressions of a platform are made when it fails for the first time. The platform fails gracefully with a guided prompt, not an opaque error
- The prompt tells the consumer: what's missing, what the platform will provision, the expected turnaround, and how to request an environment
- The pipeline exits without attempting a deployment — no partial state, no confusing errors
- Both onboarding paths end in a sandbox dev submission that must pass the confidence gate before the consumer is promoted
- Be honest: the citizen developer onboarding path is planned, not yet shipped
**Key takeaway:** The platform fails gracefully. First impressions drive adoption — platforms that fail opaquely get routed around.
---
## Slide 7 — Safe Promotion Path
**Talking points:**
- Promotion is a workflow choice, not a contract mutation — this matters because it means a promotion can be reviewed as a *diff in the workflow*, not as a rewritten contract
- Approach A (one contract, environment passed by the job) keeps the single source of truth — the contract never changes
- Approach B (environment-specific contracts) lets teams whose inputs genuinely vary keep that variation explicit and reviewable
- The platform raises the bar automatically: dev ≥ 0.50 (autonomous) → qa ≥ 0.75 (QA attests) → prod ≥ 0.90 (SRE attests). The consumer can't bypass the gates — they pick *which* environment to target, and the platform applies the right bar
- Separation of duties is enforced — the QA approver cannot be the prod approver. Be honest: design is tested, wiring for qa/prod/dr is planned
- No staging environment — the design deliberately removes the "staging is basically prod but not really" anti-pattern
**Key takeaway:** Change the environment field, not the contract. The platform raises the bar automatically. The consumer can't bypass the gates.
---
## Slide 8 — Safe Decommission
**Talking points:**
- The counter-argument to "deletion protection makes cleanup impossible" — decommission is a first-class, gated, two-approval flow, not a lock with no key
- The change request must be `approved` in the CMDB and match the consumer repo — no CR, no decommission
- Two SRE human-attestation gates: one to disable deletion protection, a second to zero counts and destroy
- The per-stack encryption key enters a 30-day grace window so encrypted data remains recoverable — the key is permanently deleted only after the window expires
- For the Head of Infrastructure: the CMDB validation means decommission is auditable, not just possible
- Uptime monitoring is not automatically destroyed — it can be left running to watch decommissioned endpoints go dark
**Key takeaway:** Tearing down is as gated as deploying. Two SRE approvals, CMDB-validated change request, 30-day key grace window.
---
## Slide 9 — Self-Service Module Catalog
**Talking points:**
- The catalog is what makes "declare intent" practical — you can only declare a module that exists
- Primitives are single-purpose resources (S3, VPC, ECS, IAM, ALB, ECR, CloudFront, WAF, RDS) — each with documented inputs/outputs, usage, compliance extension points, and versioning
- Modules are composed patterns (a static site with CDN + WAF; a microservice with VPC + ECS + ALB + registry) — one well-reviewed module serves every consumer
- Validated examples per module — `simple.yaml` + `complex.yaml` + variation files, validated against the contract schema in CI. Examples cannot drift from the schema silently
- For leadership: the catalog is the leverage — a fix to a module serves every consumer on the next run. This is the compounding asset
- Auto-promotion of patterns (after 3 observed usages) and compliance extension points (GDPR, SOX, SOC2, DORA) are planned
**Key takeaway:** The catalog is the compounding asset. One well-reviewed module serves every consumer. A fix serves everyone on the next run.
---
## Slide 10 — The Desired Outcomes
**Talking points:**
- Close on the strategic frame — the platform is not "a CI/CD tool," it's the organizational lever for shipping safely at the pace the business demands
- Velocity without sacrificing safety: speed is in the ergonomics (a simple contract, a one-line `uses:`), safety is in the gates the consumer cannot bypass
- Security, observability, and compliance as platform defaults — not per-team effort, not post-hoc remediation. Encryption, deletion protection, uptime monitoring, policy checks, and evidence are on by construction
- Auditability as a byproduct, not a project — every production change is traceable to a human attestation and a tamper-evident evidence event
- The bottleneck moves off the platform team's ticket queue — a merged change progresses through lower environments without a platform engineer joining a thread
- Infrastructure as a utility, not a craft — teams consume, they don't maintain. The platform compounds value over time by learning from recurring patterns
- The path to the citizen developer — the same safety envelope that serves a senior engineer will serve a non-technical consumer. Expanding who can ship safely without lowering the bar
**Key takeaway:** Velocity without sacrificing safety. Security and auditability as byproducts. The bottleneck moves off the platform team's queue.