Create Optimization Hypothesis

Create Optimization Hypothesis

<!--
SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

Materialize an already-reasoned proposal. Treat knowledge-consult.md as a flexible reasoning record, not a rigid schema. Do not select a different lever, broaden the proposal, deploy, benchmark, or approve it.

Inputs

Require:

• the current DEPLOY_ROOT;
• DEPLOY_ROOT/applied_manifests/deploy.yaml; and
• DEPLOY_ROOT/next-candidate/knowledge-consult.md written by consult-perf-knowledge.

Use:

<EXP_ROOT>/artifacts/deploy-iter-<NNN>/next-candidate/

as HYPOTHESIS_ROOT. The enclosing deploy-iter-<NNN> remains the analyzed source iteration. Do not create the next deployment-iteration directory; recipe-deployer owns it after challenger approval.

Read The Consultation

Read the entire consultation. Keep its freedom of form: do not require a particular bullet order, table shape, or subsection beyond the core Decision, Evidence, Proposed Change, and Materialization Handoff sections.

Inspect Decision first:

• For Status: no-proposal or Status: blocked, stop without creating deploy-draft.yaml.
• For Status: proposed, continue only when the remaining content makes one candidate actionable.
• For a missing, conflicting, or unknown status, return the consultation without creating a draft.

For a proposed candidate, require the consultation to communicate, anywhere in its relevant sections:

• the successful source manifest path and SHA256;
• at least three distinct qualifying evidence categories, including AIPerf profiler data;
• the selected primary knob, its owner, and an exact target setting or state;
• whether the candidate is single-knob or coupled-bundle;
• one intended mechanism connecting the change to the expected measurable effect;
• the performance question and target operating region for evaluating the candidate;
• the important risks or metrics that may regress; and
• for a coupled bundle, every required setting, the qualifying coupling reason, and any required follow-up ablation.

Accept evidence and reasoning as concise prose or tables. Do not require the consultation to precompute YAML paths, current values, a source-to-draft diff, a separate validation plan, or a materialization-status field. Do not repeat the performance analysis or re-rank the selected lever. Count the evidence categories represented by the entries; do not rely only on the declared category count.

If the proposed target value, affected component, bundle membership, or intended mechanism is ambiguous, return the consultation to consult-perf-knowledge. Do not choose a value, add a related optimization, or infer a broader candidate.

Resolve The Manifest Change

Require the recorded source path to identify the current successful manifest. Recompute its SHA256 and require it to match Source manifest SHA256 in Materialization Handoff. Then translate the selected proposal into the smallest mechanical manifest edit:

1. Locate the selected knob in DEPLOY_ROOT/applied_manifests/deploy.yaml.
2. Resolve its exact YAML path and current value from that manifest.
3. If it is embedded in a command or argument string, identify the owning YAML path and change only the selected fragment.
4. If the consultation explicitly requires adding an absent setting, add only that setting in the location used by the owning component.
5. For a coupled bundle, resolve every explicitly named setting and no others.

Use cited source or official documentation only to confirm the selected knob's syntax and placement. Do not use it to choose a different knob or target value. If the selected knob maps to multiple components or the requested state cannot be mapped unambiguously, stop and return the consultation.