Jon Chery
a4481e20de
Major rework of both presentation decks based on leadership feedback. Addresses: story arc, concept clarity, scope clarification, more visuals, appendix for detail-heavy slides, and a complete Road to the North Star. 6 new mermaid diagrams: - platform-works-03-scope-boundary (Upstream → Contract → ACDL → AWS) - developer-experience-01b-scope-boundary (both consumer paths + scope) - platform-works-04-confidence-signal (6 inputs → score → gate → decision) - platform-works-05-attestation-flow (deploy → gate → approver → evidence) - developer-experience-04-promotion-journey (dev → qa → prod → dr) - road-to-north-star (v1.0 demo → v1.9 → v1.10 → v2.0 → North Star) Both Marp decks restructured to 10 main + 6 appendix slides: PW deck (17 slides): 1. Title 2. The Problem & The North Star (anti-goals moved to slide 3) 3. Where ACDL Sits in Your World (NEW — scope boundary, infra only) 4. The Contract-Driven Model (image: removed, infra inputs instead) 5. The End-to-End Flow 6. Zero-Trust by Default 7. Safety is Computed (NEW confidence signal diagram) 8. Security by Construction 9. Accountability & Audit (NEW attestation flow diagram, QA clarification, badge reclassification: dev=Testing, qa/prod/dr=Planned) 10. Testing vs. Planned (summary, full inventory in appendix) 11. The Vision Realized + Appendix: TOC, Platform-Managed Environments, Observability, Road to North Star, Full Inventory, Glossary DX deck (16 slides): 1. Title 2. Where ACDL Sits in Your World (REPLACES Two Consumer Surfaces — scope boundary with both consumer paths) 3. The Contract — The Entire Consumer Surface (image: removed) 4. The Developer Feedback Loop 5. Versioned, Predictable Releases 6. Friendly Onboarding 7. Safe Promotion Path (NEW promotion journey diagram, rising bar annotated: dev=Testing, qa/prod/dr=Planned) 8. Safe Decommission 9. Self-Service Module Catalog 10. The Desired Outcomes + Appendix: TOC, Citizen Developer Experience, No Platform Code, Local Reproducibility, Road to North Star, Glossary Story arc: every slide has an italic 'Story beat' line connecting it to the narrative progression. Scope clarification: ACDL is infrastructure only. Upstream is anything (IDE, agentic SDLC, citizen dev vibe coding). ACDL provisions and governs AWS resources; application deployment is upstream. Contract examples now show infrastructure inputs (cpu, memory, desired_count, port) not image:. QA attestation reclassification: 'Design tested' → 'Planned'. QA attests to infrastructure readiness (contract + Terraform plan + evidence), not application code. Dev is autonomous (Testing); qa/prod/dr are Planned. Road to the North Star: phased timeline (v1.0 → v1.9 → v1.10 → v2.0 → North Star), annotated 'proposed phasing, not formally planned.' Also: scripts/sync_to_gl.sh added (GitLab mirror sync utility). ---ci--- phase: 51 milestone: v1.9 status: complete requirements: covered: [] partial: [] ---/ci---
215 lines
15 KiB
Markdown
215 lines
15 KiB
Markdown
# The Developer Experience — Talking Points
|
|
|
|
> **Companion to:** `the-developer-experience-marp.md` (10 main + 6 appendix = 16 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 — Where ACDL Sits in Your World
|
|
|
|
**Talking points:**
|
|
- This is the scope-boundary slide — here's who uses the platform, and here's where ACDL's responsibility starts and stops
|
|
- Two consumer paths converge on the same contract: **technical** developer writes the contract directly; **citizen** developer declares intent and an AI agent produces a contract that passes the same safety envelope
|
|
- Upstream is anything — your IDE, an agentic SDLC, or vibe coding on a laptop. ACDL doesn't care how the contract was produced
|
|
- ACDL is infrastructure only — it provisions and governs AWS resources. Application deployment is upstream of the contract
|
|
- The two surfaces are *parallel*, not a progression. A citizen developer doesn't "graduate" to the developer surface. There is no "citizen developer mode" with weaker checks
|
|
|
|
**Key takeaway:** Two consumer paths, one safety envelope. ACDL is infra only — anything upstream is fair game.
|
|
|
|
---
|
|
|
|
## 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
|
|
- The contract example now shows **infrastructure inputs** (cpu, memory, desired_count, port) — not an `image:` field. The consumer declares capacity and shape; the platform resolves the rest
|
|
- 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
|
|
|
|
**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
|
|
- 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 (KMS-encrypted, namespaced), 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
|
|
- 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
|
|
- The new promotion journey diagram shows the rising bar: dev (autonomous) → qa (QA attests) → prod (SRE attests) → dr (SRE attests + DR drill)
|
|
- 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 rising bar is annotated with maturity: **dev = Testing** (works internally, pilot-ready); **qa/prod/dr = Planned** (on the roadmap). Be honest about that split
|
|
- Separation of duties is enforced — the QA approver cannot be the prod approver. 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
|
|
|
|
**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.
|
|
|
|
---
|
|
|
|
## Appendix — Contents
|
|
|
|
**Talking points:**
|
|
- These are backup slides for Q&A — don't walk through them in the main talk unless time permits
|
|
- Use A1 when asked about the citizen developer detail; A2 for the no-cloning mechanism; A3 for local reproducibility; A4 for the roadmap; A5 for term definitions
|
|
|
|
**Key takeaway:** The appendix is the deep-dive drawer. Pull a slide when the audience asks for the detail behind a main-slide claim.
|
|
|
|
---
|
|
|
|
## A1 — The Citizen Developer Experience
|
|
|
|
**Talking points:**
|
|
- The framing is **vibe coding on a laptop** — the consumer describes what they want in plain language; an AI agent turns that into a contract the platform treats identically to a senior engineer's
|
|
- The consumer opens an issue (e.g. "a web API for the pricing service"); an AI agent maps the intent to a contract referencing a module from the reviewed skill catalog
|
|
- The contract enters the same pipeline and must clear the same confidence gate — no weaker mode
|
|
- Guardrails: skills are versioned, signed, and reviewed for sensitive data before release (Infra & Ops owns the review); agents are stateless — all state lives in the platform; the platform trusts and always verifies
|
|
- The agent's trace and submission confidence are captured in the contract (`profile: agentic`), so a reviewer can see how the contract was produced
|
|
- Be honest about maturity: the mechanism is designed and stub-proven; the full skill catalog and real agent runtime are planned
|
|
|
|
**Key takeaway:** Vibe coding on a laptop — but every submission passes the same safety envelope. The agent produces the contract; the platform verifies it.
|
|
|
|
---
|
|
|
|
## A2 — No Platform Code, No Cloning
|
|
|
|
**Talking points:**
|
|
- The consumer's CI definition is a thin wrapper — one `uses:` line pointing at a versioned tag. That's the only coupling
|
|
- The runner checks out the consumer repo, then checks out the platform repo into the workspace. The platform installs its own runtime dependencies — the consumer installs nothing
|
|
- The consumer never clones the platform repo, never invokes platform scripts locally (optional `--check-only` validation is available but not required)
|
|
- When the platform ships a fix, every consumer on a floating MAJOR.MINOR tag gets it on their next run — no per-repo upgrade project
|
|
- For the Head of Cloud: there is no "platform code in every consumer repo" problem. The version-pinned `uses:` line is the only coupling, and it updates itself within the line
|
|
|
|
**Key takeaway:** One `uses:` line is the only coupling. The platform fetches itself at run time. No per-repo upgrade projects.
|
|
|
|
---
|
|
|
|
## A3 — Local Reproducibility
|
|
|
|
**Talking points:**
|
|
- The entire CI pipeline runs from the shell, not just in CI — no "works on my machine, fails in CI" gap
|
|
- `scripts/run_ci.sh` mirrors the CI pipeline locally — the same three stages (lint → test → check-only) in sequence
|
|
- `scripts/run_platform.sh --check-only` runs the platform offline — no AWS, no policy engine, no outbox required. Validates a contract end-to-end before pushing
|
|
- `--plan-only` runs through the infrastructure plan without applying
|
|
- The CI and deploy pipelines are defined by declarative contracts (YAML instances validated against JSON Schemas) — a single source of truth that both workflows implement
|
|
|
|
**Key takeaway:** Validate offline, plan offline, push when confident. The same declarative contract drives local tooling and CI.
|
|
|
|
---
|
|
|
|
## A4 — The Road to the North Star
|
|
|
|
**Talking points:**
|
|
- Call this out explicitly: **proposed phasing, not formally planned** — don't let the audience read it as a commitment
|
|
- Phase 1 is what's tested today — core platform (contract, catalog, evidence)
|
|
- Phase 2 is the next milestone — safe promotion wiring for qa/prod/dr
|
|
- Phase 3 introduces the agentic surface — skill catalog + agents
|
|
- Phase 4 is the north star — citizen developer GA on the same safety envelope
|
|
- Use this slide only when an audience member asks "how do you get from here to there"
|
|
|
|
**Key takeaway:** A proposed path from the tested core to the citizen developer north star — proposed phasing, not formally planned.
|
|
|
|
---
|
|
|
|
## A5 — Glossary
|
|
|
|
**Talking points:**
|
|
- Keep this slide in your back pocket for the audience member who asks "what does ABAC actually mean?" — don't read it aloud
|
|
- OIDC = short-lived federation tokens, no long-lived credentials; ABAC = access scoped by resource tags + repo identity, not roles
|
|
- CMK = per-stack encryption key, 90-day rotation; CMDB = validates change requests for decommission
|
|
- RPO = 0 means evidence written synchronously, no data loss; HITL = deliberate human attestation for qa/prod/dr
|
|
- VCS = the git hosting platform (GitHub, Gitea, GitLab); NFR = encryption, tagging, observability standards
|
|
|
|
**Key takeaway:** The deck uses real security and ops vocabulary. The glossary is the cheat sheet for the audience member who wants the definitions. |