Make AI credit budget increases a last resort

.github/aw/optimize-agentic-workflow.md

@@ -57,6 +57,9 @@ Priority checks:
 2. Is the prompt front-loading large payloads that could be fetched on demand?
 3. Are there repetitive extraction steps that sub-agents could handle cheaply?
 4. Does the frontier model handle tasks that a small model could do?
+5. Can the workflow stay within its current budget after applying and measuring all applicable optimizations?
+
+Increasing `max-ai-credits` is the last resort. Recommend it only after the applicable optimizations below have been tried and measured, and the workflow still cannot complete with acceptable quality within the existing per-run budget.
 
 ### `max-daily-ai-credits` exceeded
 
@@ -101,6 +104,7 @@ After measuring token usage, produce a prioritized plan:
 7. **Prompt caching** — verify stable instructions and reusable experience appear before dynamic content
 8. **Experiment correctness first** — add an `experiments:` entry, compare output quality first, and use `metric: "aic"` to choose among equivalent-quality variants
 9. **Validate quality** — confirm the optimized run produces equivalent safe outputs
+10. **Raise the per-run budget only if necessary** — consider increasing `max-ai-credits` only after all applicable optimizations have been exhausted and measured
 
 Present the plan clearly before making any edits. Confirm with the user before applying changes.
 

.github/aw/token-optimization.md

@@ -30,6 +30,7 @@ Apply these in order, measuring cost and quality after each change:
 - [ ] **Telemetry**: Configure `observability.otlp` so token usage and run phases are measurable outside individual run logs
 - [ ] **AgenticOps**: Add `copilot-token-audit` / `copilot-token-optimizer` workflows so the repository keeps finding waste automatically
 - [ ] **Measure first**: Back every change with an `experiments:` field and `metric: "aic"` before promoting
+- [ ] **Budget increase last**: Increase `max-ai-credits` only after all applicable optimizations above have been exhausted and measured
 
 ---
 
@@ -367,6 +368,8 @@ To maximize cache hits:
 
 Two top-level frontmatter fields enforce AI Credit budgets directly, independent of the techniques above. Both accept an integer or a `K`/`M` short-form string (e.g. `100M`, `500K`). Typical workflow range: `100` to `2500`.
 
+Do not treat a workflow exhausting its per-run budget as a reason to increase `max-ai-credits` immediately. First apply and measure every applicable cost optimization in this guide. Increase the limit only as a last resort when the workflow still cannot complete with acceptable quality within the existing budget.
+
 - **`max-ai-credits:`** — Per-run AI credit budget enforced by the AWF firewall/API proxy (default `1000`). The agent is steered to stay within budget; set a negative value to disable enforcement and steering.
 - **`max-daily-ai-credits:`** — Per-user 24-hour guardrail. At activation, gh-aw sums the triggering user's AI credits across their runs of this workflow over the last 24 hours and blocks execution once the total exceeds the threshold. Enabled by default with a system default threshold; set `-1` to disable, or an explicit value to override the default.