ADR 0006 wa tool writeback

ADR-0006: Well-Architected Tool write-back semantics

Status: Accepted (2026-07-23)

Context

The AWS Well-Architected Tool is a system of record — humans answer its questionnaire, and auditors and leadership rely on its HRI/MRI counts and milestones. UpdateAnswer overwrites answers. The agent produces two very different kinds of finding (ADR-0004): scanner-backed (deterministic, evidence-linked) and judgment (Performance, process-side Operational Excellence, Sustainability — LLM/questionnaire-assessed).

Letting an automated agent write freely into this record has real hazards: corrupting the official record with a wrong mapping or a hallucinated judgment answer; clobbering human-authored answers and notes; ambiguous attribution (who "answered"?); and taking on write access to a governance system against the otherwise read-only posture (ADR-0007). But a pure read-only report throws away the native value: a continuously-current WA posture and AWS's own authoritative scoring.

Decision drivers

• Protect the integrity of the authoritative record.
• Keep the value of native HRI/MRI scoring where it is defensible.
• Attribution & auditability — automated answers must be distinguishable and evidence-linked.
• Least-privilege — minimise and localise any write scope.
• Human accountability for the judgment calls no scanner can make.

Decision

Scoped write-back to a dedicated automation workload.

1. Ownership by separate workload. The agent writes to its own WA Tool workload — e.g. "<system> — NWAF automated assessment" — and never touches any human-review workload for the same system. The automation fully owns its workload, so there is no clobber-detection logic and no ambiguity about who authored an answer.
2. The automation workload is provisioned out-of-band (IaC/Terraform), not created by the agent — so the runtime write scope stays minimal (no CreateWorkload).
3. Write only scanner-backed answers via UpdateAnswer. Each answer's notes cite source tool + check ID + evidence + "generated by NWAF agent · run <id> · <ts>".
4. Do not write judgment answers. Performance, process-Ops, and Sustainability items are surfaced as recommendations in the report for a human to accept into their own workload — this is the human-in-the-loop for the soft pillars (ADR-0008).
5. Record a CreateMilestone each run — preserves history/trend and makes every write reversible/comparable run-to-run.
6. Read back the updated workload summary → AWS's authoritative HRI/MRI counts for the scanner-backed set feed the report.
7. This is the only write in the entire pipeline, held only by the Scorer stage (per-stage least-privilege, ADR-0003). Runtime WA-Tool scope: UpdateAnswer, CreateMilestone, and read APIs (GetWorkload/ListAnswers/GetAnswer) — recorded in ADR-0007.

Consequences

• The human record is never mutated by the agent — humans compare the automation workload against their own review workload; trust is preserved.
• No clobber logic — the automation owns its workload outright.
• Native scoring retained for the defensible (scanner-backed) answers; the judgment calls stay human-gated.
• Duplication cost — two workloads per system (human review + automation) to reconcile. Accepted as the price of a clean governance boundary.
• Reversible & auditable — milestones give history; every answer carries its evidence and run attribution.
• Minimal, localised write scope — one write permission, one stage, one workload the automation owns.

Alternatives considered

Option	Verdict	Why
Scoped write-back to a dedicated automation workload	Chosen	Cleanest ownership boundary; human record untouched; native scoring where defensible; judgment human-gated.
Attributed answers in the shared human workload	Rejected	One workload, but relies on discipline to avoid clobbering human answers, and blurs attribution — the exact integrity risks we want to eliminate. Revisit if a single-workload model is ever required.
Full auto write-back (all answers, shared workload)	Rejected	Writes LLM judgment answers into the authoritative record and can overwrite human input — weakest governance posture.
Read-only report only (no WA-Tool write)	Kept as fallback	Safest — WA Tool stays fully human-owned — but forfeits native scoring and a continuously-current posture. Fall back here if any write to the WA Tool is disallowed by policy.

Revisit trigger

• Move to the attributed-answers-in-shared-workload model (with strict ownership detection and skip-on-human-answer) if customers require a single workload rather than a separate automation one.
• Fall back to read-only report only if org policy forbids automated writes to the Well-Architected Tool entirely.

References

• ADR-0003 (detection & orchestration — the Scorer stage that performs the write)
• ADR-0004 (deterministic-vs-judgment boundary — what is eligible to be written)
• ADR-0007 (least-privilege IAM — the single write scope this introduces)
• ADR-0008 (human-in-the-loop — judgment answers are proposed, not written)