Skip to content

feat(gcp-to-aws): Design summary card + cost baseline-quality labels - #175

Merged
icarthick merged 3 commits into
awslabs:mainfrom
herosjourney:usability/pr5-design-card-cost-badges
Jul 22, 2026
Merged

feat(gcp-to-aws): Design summary card + cost baseline-quality labels#175
icarthick merged 3 commits into
awslabs:mainfrom
herosjourney:usability/pr5-design-card-cost-badges

Conversation

@herosjourney

Copy link
Copy Markdown
Contributor

Summary

The problem, in plain English: Two related blind spots. First, the Design phase does the most interesting work in the whole flow — mapping every GCP service to an AWS target with reasoning — and then tells the user nothing but "AWS Architecture designed. Proceeding to Phase 4." The user's first look at their own architecture comes buried in a report two phases later. Second, cost comparisons can silently mix baselines that measure different things: a GCP figure estimated from Terraform resource configs only captures standing charges for discovered resources, while a user's stated spend band covers their whole bill. Put side by side without labels, a "$10/mo GCP vs $112/mo AWS" row can appear in the same report as a "$1K–$5K/mo" spend band, and the savings math looks broken or dishonest — the exact failure observed in a real test migration.

Changes:

  • Design summary card (design.md): after the outer-run handoff gate passes, present a compact chat card — top 3–5 GCP → AWS mappings with the existing user-facing vocabulary (Standard pairing / Tailored to your setup / Estimated from billing only), deferred-specialist services called out, and one line on what Estimate answers next. Skipped on inner workshop reprices; phase-status protocol untouched.
  • Baseline-quality labels (estimate-infra.md Part 1): display-label table derived from the existing current_costs.source enum (no new schema field): "Measured from your GCP billing (±5%)" / "Estimated from resource configs (±20–30%, standing charges only)" / "Your stated spend band" / etc. The Estimate chat summary's GCP-vs-AWS line now carries the label.
  • Not-comparable rule (estimate-infra.md + generate-artifacts-report.md): an inventory-only GCP figure and a user spend band must never sit side-by-side unlabeled; when both exist and disagree beyond the accuracy band, show both with an explicit "these measure different things" line and name the decision baseline. Report Section 3 requires the baseline badge on the GCP column.

Why

Usability review of the outputs: mid-flow value checkpoints and honest cost comparability were the two report-side gaps. The design card reuses vocabulary and data that already exist (design-refs/fast-path.md, design artifact rationale); the baseline labels reuse the existing current_costs.source enum rather than adding a parallel field.

Test plan

  • mise run lint:md — 0 errors
  • No schema change: current_costs.source enum reused as-is (schema-estimate-infra.md untouched)
  • Inner-reprice paths excluded from the design card (explicit skip), phase-status update order preserved
  • Manual: inventory-only run (no billing, Q3 answered) shows both figures with the not-comparable line rather than a single misleading comparison row

Out of scope

Note for maintainers: this PR and #169 both touch the design.md completion area (breadcrumb line vs. card insertion above it). Merge #169 first; this branch rebases cleanly — the card block sits above the line #169 rewords.

@herosjourney
herosjourney requested a review from a team as a code owner July 22, 2026 20:07
Clean merge to current main (through awslabs#174; estimate-infra.md + generate-artifacts-report.md
co-touched by awslabs#173, no overlap). dprint clean, full build green.
icarthick added a commit to herosjourney/startups that referenced this pull request Jul 22, 2026
Clean merge to current main (through awslabs#175). The canonical workshop-invariants.md +
all 3 vendored copies stay byte-identical (shared:check OK, 4 trees, 1 distinct md5).
dprint clean, full build green.
@icarthick
icarthick merged commit 9727065 into awslabs:main Jul 22, 2026
8 checks passed
herosjourney pushed a commit to herosjourney/startups that referenced this pull request Jul 24, 2026
…round 2)

The preamble declared decision fallbacks while the moved body still
commanded Generate-first sources — under-specified mode overrides, not a
verbatim move. Fixes:

- Inline '_Decision mode:_' overrides next to each affected rule, declared
  authoritative in the preamble: decision-summary item 4 + Section 6
  timeline (timeline_hint -> complexity band, labeled 'if you execute',
  never invent weeks, omit effort hours), Section 2b (diagram from
  aws-design.json clusters only, omit cluster_order), Section 7 risks
  (ordered decision sources: recommendation conditions/would_flip_if ->
  deferred rows -> material defaulted assumptions; never leave exec-risks
  empty when those exist)
- Decision-inappropriate Generate copy split by mode: cost footnote ('if
  you generate the execution pack...'), security teaser Appendix G
  pointers, startup-program validate script marked full-mode-only
- Anti-stub / don't-truncate-appendices prose marked full-mode-only for
  the appendix clauses
- estimate.md gate A validate command uses absolute $PLUGIN_ROOT /
  $MIGRATION_DIR paths (cwd not load-bearing)
- Golden asserter now locks content, not just structure: verdict-headline
  (awslabs#173), the not-comparable sentence (awslabs#175), and the 'if you execute'
  timeline label
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants