feat(review): inline IaC Fix: blocks for Critical/High/Medium findings (#134) (#137)

Every Critical/High/Medium finding in the report now carries a Fix: block —
a minimal ready-to-copy remediation snippet:

- Language-matched: emitted in the IaC dialect recorded during Step 2
  discovery (CDK/CloudFormation/Terraform/SAM); AWS CLI fallback when the
  workload has no IaC
- Evidence-grounded: uses the actual resource names from the finding's
  evidence, not placeholders
- Report-only: never applied to the user's codebase, never a diff/patch
  (design principle: review and guidance, not code mutation); the JSON
  artifact's recommendation field stays prose-only
- Reuses the named anti-pattern wrong/right pairs (#133) as fix skeletons

Applied consistently to SKILL.md, SKILL-sequential.md, SKILL-devops-agent.md,
the steering doc and its Kiro Power copy, and the claude-code/cursor/
antigravity adapter templates. New eval case 7 (Terraform workload) asserts
language-matched, resource-grounded fix blocks; case 4 gains a CLI-fallback
assertion.

Author: ibrahimcesar

adapters/antigravity/rules/aws-well-architected-framework-review.md

@@ -117,8 +117,8 @@ Structure:
 - Executive Summary (date, workload, criticality, lens, findings count, overall maturity 1-5)
 - Architecture Overview (PlantUML diagram)
 - Pillar Scorecard (table: pillar, score 1-5, key strength, key gap)
-- Critical and High Risk Findings (ID, pillar, title, evidence file:line, impact, recommendation, effort, AWS services)
-- Medium Risk Findings (condensed)
+- Critical and High Risk Findings (ID, pillar, title, evidence file:line, impact, recommendation, fix — ready-to-copy snippet in the workload's IaC dialect, AWS CLI when no IaC, report-only, effort, AWS services)
+- Medium Risk Findings (condensed, each with its fix snippet)
 - Low Risk Findings (summary table)
 - Cross-Pillar Trade-offs
 - Prioritized Remediation Plan (Quick Wins < 1 week, Foundation 1-4 weeks, Strategic 1-3 months)

adapters/claude-code/commands/aws-well-architected-framework-review.md

@@ -158,10 +158,10 @@ Output a structured report:
 | Sustainability | {score} | {strength} | {gap} |
 
 ## Critical and High Risk Findings
-{For each: ID, pillar, title, description, evidence (file:line), impact assessment, recommendation, effort, AWS services}
+{For each: ID, pillar, title, description, evidence (file:line), impact assessment, recommendation, **Fix:** block — a minimal ready-to-copy snippet in the workload's IaC dialect (AWS CLI when no IaC), using the actual resource names from the evidence; shown in the report only, never applied — effort, AWS services}
 
 ## Medium Risk Findings
-{Same format, condensed}
+{Same format, condensed — each finding still carries its **Fix:** block}
 
 ## Low Risk Findings
 {Summary table: ID | Pillar | Title | Recommendation}

adapters/cursor/rules/aws-well-architected-framework-review.md

@@ -117,8 +117,8 @@ Structure:
 - Executive Summary (date, workload, criticality, lens, findings count, overall maturity 1-5)
 - Architecture Overview (PlantUML diagram)
 - Pillar Scorecard (table: pillar, score 1-5, key strength, key gap)
-- Critical and High Risk Findings (ID, pillar, title, evidence file:line, impact, recommendation, effort, AWS services)
-- Medium Risk Findings (condensed)
+- Critical and High Risk Findings (ID, pillar, title, evidence file:line, impact, recommendation, fix — ready-to-copy snippet in the workload's IaC dialect, AWS CLI when no IaC, report-only, effort, AWS services)
+- Medium Risk Findings (condensed, each with its fix snippet)
 - Low Risk Findings (summary table)
 - Cross-Pillar Trade-offs
 - Prioritized Remediation Plan (Quick Wins < 1 week, Foundation 1-4 weeks, Strategic 1-3 months)

powers/aws-well-architected-framework-review/steering/aws-well-architected-framework-review.md

@@ -436,10 +436,10 @@ Empirical measurement shows this section is where recall reaches the user. Skipp
 {After writing this table, count the rows and confirm the count matches the sum of subagent rows. If not, you dropped citations — go back and add them.}
 
 ## Critical and High Risk Findings
-{For each: ID, pillar, title, description, evidence (file:line), impact assessment, recommendation, effort, AWS services. This section EXPANDS on rows in the Full BP Ledger — it does NOT replace them.}
+{For each: ID, pillar, title, description, evidence (file:line), impact assessment, recommendation, **Fix:** block — a minimal ready-to-copy snippet in the workload's IaC dialect (AWS CLI when no IaC), using the actual resource names from the evidence; shown in the report only, never applied — effort, AWS services. This section EXPANDS on rows in the Full BP Ledger — it does NOT replace them.}
 
 ## Medium Risk Findings
-{Same format, condensed. Also references ledger rows.}
+{Same format, condensed — each finding still carries its **Fix:** block. Also references ledger rows.}
 
 ## Low Risk Findings
 {Summary table: ID | Pillar | Title | Recommendation. Also references ledger rows.}

skills/aws-well-architected-framework-review/SKILL-devops-agent.md

@@ -110,6 +110,11 @@ For each infrastructure component, document:
 - Resilience configs (multi-AZ, backups, scaling)
 - Cost-relevant configs (instance types, capacity mode)
 
+Record the workload's **primary IaC dialect** (CDK, CloudFormation, Terraform, or
+SAM) — Step 6 emits a per-finding **Fix:** block in this dialect. When the
+workload has no IaC (on-premises or legacy), fix blocks fall back to AWS CLI
+commands or explicit configuration guidance.
+
 Create an architecture diagram in PlantUML showing major components, data flows,
 and trust boundaries.
 
@@ -369,11 +374,11 @@ paraphrase. Target row count: 250-307.
 subagent rows. If not, you dropped citations — go back and add them.}
 
 ## Critical and High Risk Findings
-{For each: ID, pillar, title, description, evidence, impact, recommendation, effort, AWS services.
+{For each: ID, pillar, title, description, evidence, impact, recommendation, **Fix:** block (see "Fix blocks" below), effort, AWS services.
  This section EXPANDS on rows in the Full BP Ledger — it does NOT replace them.}
 
 ## Medium Risk Findings
-{Same format, condensed.}
+{Same format, condensed — each finding still carries its **Fix:** block.}
 
 ## Low Risk Findings
 {Summary table: ID | Pillar | Title | Recommendation}
@@ -411,6 +416,24 @@ subagent rows. If not, you dropped citations — go back and add them.}
 {Top 5 concrete actions from the "Do First" quadrant}
 ```
 
+### Fix blocks — ready-to-copy remediation snippets
+
+Every 🔴 Critical/High and 🟡 Medium finding in the report MUST include a **Fix:**
+block — a minimal, ready-to-copy remediation snippet:
+
+- **Language-matched.** Use the primary IaC dialect recorded in Step 2
+  (CDK / CloudFormation / Terraform / SAM); fall back to AWS CLI commands or
+  explicit configuration guidance when the workload has no IaC.
+- **Evidence-grounded.** Use the actual resource names and identifiers from the
+  finding's evidence — not generic placeholders — whenever the source is available.
+- **Minimal.** Only the lines needed to close the gap; elide unchanged
+  surrounding configuration with a comment.
+- **Report-only.** The fix appears in the report for the team to review and
+  apply. Do NOT apply it to the workload's codebase and do NOT emit it as a
+  diff/patch (repo design principle: review and guidance, not code mutation).
+- **Reuse anti-pattern examples.** When a finding matches a named anti-pattern
+  from the pillar playbooks, start from that entry's Right example.
+
 ## Calibration Guidance
 
 - A workload with multi-AZ, encryption, CI/CD with rollback, monitoring, and auto-scaling is MATURE — most findings should be improvements, not Critical

skills/aws-well-architected-framework-review/SKILL-sequential.md

@@ -55,6 +55,8 @@ For each infrastructure component, document:
 - Resilience configs (multi-AZ, backups, scaling)
 - Cost-relevant configs (instance types, capacity mode)
 
+Record the workload's **primary IaC dialect** (CDK, CloudFormation, Terraform, or SAM) — Step 6 emits a per-finding **Fix:** block in this dialect. When the workload has no IaC, note that fix blocks will fall back to AWS CLI commands.
+
 You MUST create an architecture diagram in PlantUML showing:
 - All major components and their relationships
 - Data flows and external dependencies
@@ -465,10 +467,10 @@ Empirical measurement shows this section is where recall reaches the user. Skipp
 {After writing this table, count the rows and confirm the count matches the sum of per-pillar rows. If not, you dropped citations — go back and add them.}
 
 ## Critical and High Risk Findings
-{For each: ID, pillar, title, description, evidence (file:line), impact assessment, recommendation, effort, AWS services. This section EXPANDS on rows in the Full BP Ledger — it does NOT replace them.}
+{For each: ID, pillar, title, description, evidence (file:line), impact assessment, recommendation, **Fix:** block (see "Fix blocks" below), effort, AWS services. This section EXPANDS on rows in the Full BP Ledger — it does NOT replace them.}
 
 ## Medium Risk Findings
-{Same format, condensed. Also references ledger rows.}
+{Same format, condensed — each finding still carries its **Fix:** block. Also references ledger rows.}
 
 ## Low Risk Findings
 {Summary table: ID | Pillar | Title | Recommendation. Also references ledger rows.}
@@ -539,6 +541,28 @@ For each solution in "Do First" and "Plan":
 {Top 5 concrete actions from the "Do First" quadrant — the team should start this week}
 ```
 
+### Fix blocks — ready-to-copy remediation snippets
+
+Every 🔴 Critical/High and 🟡 Medium finding in the report MUST include a **Fix:** block — a minimal, ready-to-copy remediation snippet the user can apply themselves:
+
+- **Language-matched.** Emit the snippet in the primary IaC dialect recorded in Step 2 (CDK / CloudFormation / Terraform / SAM). When the workload has no IaC (e.g., a verbal review), fall back to equivalent AWS CLI commands.
+- **Evidence-grounded.** Use the actual resource names and identifiers from the finding's evidence — not generic placeholders — whenever the source is available.
+- **Minimal.** Only the lines needed to close the gap; elide unchanged surrounding configuration with a comment.
+- **Report-only.** The fix appears in the report for the user to review and apply. Do NOT apply it to the user's codebase and do NOT emit it as a diff/patch (repo design principle: review and guidance, not code mutation). The JSON artifact's `recommendation` field (Step 6b) stays prose-only; fix blocks live in the markdown report.
+- **Reuse anti-pattern examples.** When a finding matches a named anti-pattern from the pillar playbooks, start from that entry's Right example.
+- **Scope.** Applies to full and pillar-scoped reports. Score mode and quick review stay snippet-free, and the Full BP Ledger table stays snippet-free — fixes belong in the findings sections.
+
+Example (finding SEC08-BP02, Terraform workload, evidence `infra/rds.tf:12`):
+
+**Fix:**
+```hcl
+# infra/rds.tf — aws_db_instance.orders (line 12)
+resource "aws_db_instance" "orders" {
+  # ...existing configuration...
+  storage_encrypted = true
+}
+```
+
 ## Step 6b: Emit structured output (`aws-well-architected-framework-review.json`)
 
 After the markdown report, ALSO emit a machine-readable `aws-well-architected-framework-review.json` so the review can be

skills/aws-well-architected-framework-review/SKILL.md

@@ -46,6 +46,8 @@ For each infrastructure component, document:
 - Resilience configs (multi-AZ, backups, scaling)
 - Cost-relevant configs (instance types, capacity mode)
 
+Record the workload's **primary IaC dialect** (CDK, CloudFormation, Terraform, or SAM) — Step 6 emits a per-finding **Fix:** block in this dialect. When the workload has no IaC, note that fix blocks will fall back to AWS CLI commands.
+
 You MUST create an architecture diagram in PlantUML showing:
 - All major components and their relationships
 - Data flows and external dependencies
@@ -456,10 +458,10 @@ Empirical measurement shows this section is where recall reaches the user. Skipp
 {After writing this table, count the rows and confirm the count matches the sum of subagent rows. If not, you dropped citations — go back and add them.}
 
 ## Critical and High Risk Findings
-{For each: ID, pillar, title, description, evidence (file:line), impact assessment, recommendation, effort, AWS services. This section EXPANDS on rows in the Full BP Ledger — it does NOT replace them.}
+{For each: ID, pillar, title, description, evidence (file:line), impact assessment, recommendation, **Fix:** block (see "Fix blocks" below), effort, AWS services. This section EXPANDS on rows in the Full BP Ledger — it does NOT replace them.}
 
 ## Medium Risk Findings
-{Same format, condensed. Also references ledger rows.}
+{Same format, condensed — each finding still carries its **Fix:** block. Also references ledger rows.}
 
 ## Low Risk Findings
 {Summary table: ID | Pillar | Title | Recommendation. Also references ledger rows.}
@@ -530,6 +532,28 @@ For each solution in "Do First" and "Plan":
 {Top 5 concrete actions from the "Do First" quadrant — the team should start this week}
 ```
 
+### Fix blocks — ready-to-copy remediation snippets
+
+Every 🔴 Critical/High and 🟡 Medium finding in the report MUST include a **Fix:** block — a minimal, ready-to-copy remediation snippet the user can apply themselves:
+
+- **Language-matched.** Emit the snippet in the primary IaC dialect recorded in Step 2 (CDK / CloudFormation / Terraform / SAM). When the workload has no IaC (e.g., a verbal review), fall back to equivalent AWS CLI commands.
+- **Evidence-grounded.** Use the actual resource names and identifiers from the finding's evidence — not generic placeholders — whenever the source is available.
+- **Minimal.** Only the lines needed to close the gap; elide unchanged surrounding configuration with a comment.
+- **Report-only.** The fix appears in the report for the user to review and apply. Do NOT apply it to the user's codebase and do NOT emit it as a diff/patch (repo design principle: review and guidance, not code mutation). The JSON artifact's `recommendation` field (Step 6b) stays prose-only; fix blocks live in the markdown report.
+- **Reuse anti-pattern examples.** When a finding matches a named anti-pattern from the pillar playbooks, start from that entry's Right example.
+- **Scope.** Applies to full and pillar-scoped reports. Score mode and quick review stay snippet-free, and the Full BP Ledger table stays snippet-free — fixes belong in the findings sections.
+
+Example (finding SEC08-BP02, Terraform workload, evidence `infra/rds.tf:12`):
+
+**Fix:**
+```hcl
+# infra/rds.tf — aws_db_instance.orders (line 12)
+resource "aws_db_instance" "orders" {
+  # ...existing configuration...
+  storage_encrypted = true
+}
+```
+
 ## Step 6b: Emit structured output (`aws-well-architected-framework-review.json`)
 
 After the markdown report, ALSO emit a machine-readable `aws-well-architected-framework-review.json` so the review can be

skills/aws-well-architected-framework-review/evals/evals.json

@@ -71,7 +71,8 @@
         "BP IDs cited: SEC04 (detective controls/GuardDuty), SEC05 (network protection/WAF), REL10 (fault isolation/single-AZ RDS), and DLQ gap referenced as REL06 or REL07",
         "Risk assessment: no WAF = Medium, no GuardDuty = Medium, single-AZ RDS = High, no DLQ = High",
         "Eisenhower prioritization covers only the scoped findings",
-        "Pillar scorecard shows only Security and Reliability scores (not all 6)"
+        "Pillar scorecard shows only Security and Reliability scores (not all 6)",
+        "High Risk findings each include a Fix: block with a concrete remediation snippet (AWS CLI or IaC, since only a verbal description was provided) referencing the named resources (e.g., the metadata RDS instance, the SQS queue)"
       ]
     },
     {
@@ -105,6 +106,20 @@
         "Depth filter is respected — only Critical and High findings shown",
         "All 6 pillars receive a score even though findings are filtered"
       ]
+    },
+    {
+      "id": 7,
+      "prompt": "Review the Security and Reliability pillars of this Terraform workload:\n\n```hcl\nresource \"aws_s3_bucket\" \"uploads\" {\n  bucket = \"acme-uploads\"\n}\n\nresource \"aws_db_instance\" \"orders\" {\n  engine                  = \"postgres\"\n  instance_class          = \"db.t3.medium\"\n  backup_retention_period = 0\n}\n\nresource \"aws_iam_role_policy\" \"app\" {\n  role   = aws_iam_role.app.id\n  policy = jsonencode({\n    Version   = \"2012-10-17\"\n    Statement = [{ Effect = \"Allow\", Action = \"*\", Resource = \"*\" }]\n  })\n}\n```",
+      "expected_output": "A pillar-scoped Security + Reliability review whose High/Medium findings each include a ready-to-copy Fix: block written in Terraform (the workload's IaC dialect), referencing the actual resource names from the input.",
+      "assertions": [
+        "Every High Risk finding includes a Fix: block containing a syntactically plausible Terraform (HCL) snippet — not CloudFormation, CDK, or bare CLI",
+        "Fix blocks reference the actual resource identifiers from the input (aws_s3_bucket.uploads / acme-uploads, aws_db_instance.orders, aws_iam_role_policy.app), not generic placeholders",
+        "The wildcard IAM policy is flagged (SEC03) with a fix narrowing Action and Resource to least privilege",
+        "The disabled backup retention is flagged (REL09) with a fix setting backup_retention_period to a value greater than 0",
+        "The bucket's missing public-access block or missing encryption at rest is flagged (SEC08) with a corresponding Terraform fix resource",
+        "Fix snippets are presented in the report only — the response does not claim to have modified or applied changes to the user's files",
+        "The review stays scoped to Security and Reliability — no findings for the other four pillars"
+      ]
     }
   ]
 }

steering/aws-well-architected-framework-review.md

@@ -629,10 +629,10 @@ Compile all analyses into a comprehensive report.
 | Sustainability | {score} | {strength} | {gap} |
 
 ## Critical and High Risk Findings
-{For each finding: ID, pillar, title, description, evidence (file:line), impact, recommendation, effort, AWS services}
+{For each finding: ID, pillar, title, description, evidence (file:line), impact, recommendation, **Fix:** block — a minimal ready-to-copy snippet in the workload's IaC dialect (AWS CLI when no IaC), using the actual resource names from the evidence; shown in the report only, never applied — effort, AWS services}
 
 ## Medium Risk Findings
-{Same format, condensed}
+{Same format, condensed — each finding still carries its **Fix:** block}
 
 ## Low Risk Findings
 {Summary table only}