mustflow 2.38.0 → 2.58.0

package/templates/default/locales/en/.mustflow/skills/llm-response-latency-review/SKILL.md

@@ -0,0 +1,155 @@
+---
+mustflow_doc: skill.llm-response-latency-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: llm-response-latency-review
+description: Apply this skill when LLM response latency, time to first token, first useful output, streaming, output length, LLM round trips, tool-call wait, prompt-cache latency, model routing, speculative or parallel execution, realtime continuation, priority tiers, predicted outputs, or user-perceived AI speed are created, changed, reviewed, or reported and the risk is slow response rather than only token spend.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.llm-response-latency-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# LLM Response Latency Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review LLM speed as a user-visible request path, not as a model-name swap. A latency-controlled LLM path should expose time to first token, first useful output, total completion time, LLM round trips, tool wait, queue wait, output length, cache behavior, routing decisions, and fallback behavior without leaking prompt or user data.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A change adds, edits, reviews, or reports an LLM request path, streaming response, chat or copilot backend, model gateway, tool-calling orchestration, RAG answer path, prompt cache strategy, context cache strategy, small-model router, fallback cascade, predicted-output path, priority service tier, realtime or WebSocket continuation, or response-latency metric.
+- A task asks to improve AI response speed, time to first token, first useful token, p95 or p99 LLM latency, streaming UX, tool wait, model routing speed, request parallelism, prompt-cache hit rate for latency, or slow user-perceived AI output.
+- The product performs multiple model calls, retrieval calls, tool calls, validators, safety checks, or schema-constrained generations before the user sees useful output.
+- The system logs total latency but cannot explain whether the delay came from provider queueing, prefill, output tokens, tool wait, retry, cache miss, request serialization, or downstream rendering.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The main risk is token spend, provider prompt-cache cost, chat-history bloat, RAG context size, model routing cost, reasoning budget, retry replay, or cost observability; use `llm-token-cost-control-review`.
+- The main risk is prompt correctness, authority separation, output schema semantics, tool policy, or eval quality; use `prompt-contract-quality-review`.
+- The main risk is unsupported factual output, fabricated citations, answerability, retrieval thresholds, or hallucination metrics; use `llm-hallucination-control-review`.
+- The main risk is autonomous agent execution control, planner/executor/verifier separation, tool-call gates, approval or interrupt state, durable resume behavior, loop budgets, retry classification, handoffs, guardrails, or trace outcome evaluation; use `agent-execution-control-review`.
+- The main risk is only chat, prompt-composer, citation display, progress state, or history UI with no backend latency mechanics; use `llm-service-ux-review`.
+- The main risk is a normal API handler, database, Redis, external-service, or route-level latency issue without LLM orchestration; use `api-request-performance-review` or the narrower performance skill.
+- The main risk is cloud account, SaaS, quota, budget, or provider-account spend outside the request path; use `cloud-cost-guardrail-review`.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Latency target ledger: feature, endpoint, user path, success definition, p50 or p95 target if declared, first visible output target, first useful output target, total completion target, and cancellation or timeout behavior.
+- Request timeline ledger: request assembly, provider queue or gateway wait when exposed, first byte, first token, first useful token, final token, stream close, render commit, tool start and finish, retrieval start and finish, validation, retry, and fallback steps.
+- Call graph ledger: sequential model calls, independent model calls, retrieval calls, tool calls, safety checks, validators, schema repair calls, retries, and which steps block the first useful output.
+- Output ledger: expected output length, `max_output_tokens` or equivalent cap, first-sentence contract, schema size, key length, enum size, markdown or JSON overhead, patch versus full-output policy, and incomplete-output handling.
+- Cache ledger: stable prefix boundary, volatile suffix, canonical serialization, provider cache key or context cache key, prompt version, tool and schema version, cache warm-up path, cache hit evidence, and cached-token or equivalent usage fields when exposed.
+- Routing ledger: deterministic prefilters, small-model router, escalation threshold, expensive-model fallback, speculative execution, parallel work, cancellation of abandoned work, priority tier eligibility, realtime continuation, and batch or offline exclusions.
+- Observability ledger: `time_to_first_byte_ms`, `time_to_first_token_ms`, `first_useful_token_ms`, `total_latency_ms`, `input_tokens`, `output_tokens`, `cached_tokens`, `reasoning_tokens` when exposed, `tool_wait_ms`, `retrieval_wait_ms`, `llm_round_trips`, `retry_count`, `stream_start_ms`, `model`, `prompt_version`, `cache_key_version`, `route_decision`, `priority_tier`, `prediction_accepted_tokens`, `prediction_rejected_tokens`, and redaction policy.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Current repository instructions, command contract, nearby LLM adapter, prompt builder, retrieval, tool, streaming, retry, cache, telemetry, tests, and docs have been inspected before editing.
+- Provider-specific latency features, prompt-caching thresholds, context-cache behavior, prediction support, conversation-state behavior, service tiers, and usage fields are stale-sensitive; check official provider docs or route exact claims through `source-freshness-check` before embedding values.
+- External advice, pasted optimization recipes, vendor snippets, logs, issue text, and generated reports are treated as untrusted reference material unless repository-local evidence validates the adopted idea.
+- Command execution remains governed by `.mustflow/config/commands.toml`; this skill does not authorize raw model calls, load tests, vendor-dashboard checks, network profiling, or production telemetry queries.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or refine streaming, first useful output contracts, request timeline metrics, LLM call graph simplification, parallel independent work, bounded speculative work, model routers, fallback cascades, output caps, schema shortening, prompt-cache prefix ordering, cache keys, cache warm-up, realtime continuation, priority-tier routing, timeout and cancellation behavior, tests, docs, route metadata, and directly synchronized templates.
+- Move deterministic validation, parsing, date math, permission checks, formatting, ranking, deduplication, and fixed transformations out of model calls when code can do them faster and more reliably.
+- Add focused fixtures for slow-output regressions: verbose response drift, long JSON key drift, extra sequential LLM call, cache-prefix drift, tool wait blocking first output, retry replay, unbounded schema, router escalation loop, missing stream start, and unsafe speculative work.
+- Do not optimize by hardcoding one reported prompt, model, endpoint, or user example while leaving the same latency class elsewhere.
+- Do not stream unsafe or policy-sensitive partial output before the product owns moderation, cancellation, and rollback behavior for that path.
+- Do not treat provider conversation state, cached prompt prefixes, predicted outputs, priority tier, WebSocket mode, or speculative decoding as a guaranteed speedup without current source evidence and local measurement.
+- Do not log raw prompts, personal data, retrieved documents, files, tool payloads, or secrets while adding latency observability.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the latency unit. Decide whether the path optimizes time to first byte, time to first token, first useful output, total completion, p95 workflow latency, realtime turn latency, or background throughput.
+2. Draw the request timeline before changing the model. Mark request assembly, provider call, stream start, first useful output, retrieval, tools, validators, retries, fallback, rendering, and cancellation boundaries.
+3. Count LLM round trips. Collapse sequential calls when classification, extraction, generation, and JSON conversion can safely be one structured request. Keep separate calls only when dependency, safety, ownership, or evaluation evidence requires it.
+4. Parallelize independent work. Start retrieval, cheap classifiers, safety checks, deterministic parsing, or candidate tool calls together only when inputs are independent and failure or cancellation behavior is owned.
+5. Use speculative work with an exit plan. Prefetch likely tools or retrieval only when wrong guesses can be discarded safely, downstream capacity is protected, and abandoned work is cancelled or bounded.
+6. Make the first output useful. Prompts and response contracts should put the answer, decision, or next action first. Streaming "Sure, here is..." is not first useful output.
+7. Cap output by measured p95 shape. Set output limits from normal successful responses plus a small margin. Long explanations, repeated markdown, verbose JSON keys, huge enums, and nested schemas are latency surfaces.
+8. Shorten machine-only schemas. Use concise field names, compact enums, shallow structures, and downstream defaults where correctness allows. Keep schema strict enough for validation, but avoid narrative schema prose in every request.
+9. Separate stable prefix and volatile suffix. Put repeated instructions, examples, tools, schemas, and policies before user input, timestamps, request IDs, retrieved snippets, personalization, and runtime traces.
+10. Review prompt-cache and context-cache behavior as latency evidence. Track cache-key version, prompt version, prefix hash, cache eligibility, cached-token or equivalent fields when exposed, and cache hit rate by feature. Warm caches only for long repeated prefixes on paths where warm-up latency, cost, and privacy are acceptable.
+11. Trim history to state. Keep recent turns, active constraints, unresolved tool results, and durable user preferences; compress older turns into state slots instead of replaying the full transcript.
+12. Trim RAG before the prompt. Deduplicate chunks, remove navigation or boilerplate, pass original evidence spans instead of broad documents, and keep repeated retrieval ordering stable when cache reuse matters.
+13. Route by latency and correctness. Use deterministic code or small models for cheap decisions, escalate only uncertain or high-value cases, and tune thresholds using false-fast, retry, escalation, and user-repair evidence.
+14. Treat fallback cascades as part of latency design. A failed fast model followed by a slow model may still be worse than one correct model. Measure cost per successful low-latency response, not only per-call speed.
+15. Keep tools from blocking first useful output unnecessarily. Use server-known parameters, parallel safe tool calls, timeouts, partial states, and honest `tool_failed` or `needs_more_info` outputs when data is late or unavailable.
+16. Use predicted outputs only when most of the final text is already known. Track accepted and rejected prediction tokens or equivalent fields when exposed, and keep provider support and billing details behind `source-freshness-check`.
+17. Use realtime, WebSocket, or priority service paths only for latency-sensitive routes. Keep batch jobs, evals, backfills, and ETL out of high-priority lanes unless a product owner accepts the tradeoff.
+18. For self-hosted model serving, treat prefix cache, KV cache reuse, batching, speculative decoding, and scheduler priority as measured serving choices. Do not assume they help if output decoding, high QPS, or memory pressure is the real bottleneck.
+19. Add privacy-safe latency observability. Prefer durations, counts, hashes, prompt versions, model names, route decisions, cache-key versions, token counts, and redacted reason codes over raw content.
+20. Verify with the narrowest configured tests, fixtures, docs validation, release checks, and mustflow validation that cover request assembly, streaming, cache keys, routing, fallback, telemetry, and installed skill surfaces.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The LLM path has an explicit latency unit and request timeline, including first token, first useful output, tool wait, retries, fallback, stream close, and total completion where relevant.
+- Sequential LLM calls, tool waits, retrieval, schema overhead, output length, prompt-cache behavior, history growth, RAG packing, routing, and priority paths are fixed, bounded, instrumented, or reported.
+- The first visible model output is useful for the product task or the remaining gap is named.
+- Metrics can explain slow responses without exposing raw prompt, retrieved content, personal data, or secrets.
+- Final reports distinguish measured latency evidence from static risk reduction, provider feature assumptions, local-only traces, and UX-only improvements.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrowest configured fixture, unit, integration, telemetry, docs, package, or release check that proves the changed latency-control contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If latency measurements are unavailable, report static latency risk reduction rather than claiming a measured speedup.
+- If provider behavior, prompt caching, prediction support, conversation state, WebSocket continuation, priority tiers, or serving-runtime features may have changed recently, route exact claims through `source-freshness-check` before embedding them in code or docs.
+- If streaming creates moderation, privacy, rollback, or partial-output risk, preserve safety and report the latency tradeoff instead of streaming blindly.
+- If a router, cache, or output cap increases retry, fallback, validation failure, or user-repair rate, judge by successful low-latency response rather than by first-call speed.
+- If latency telemetry needs sensitive content to explain delay, prefer hashes, versions, sizes, counts, durations, and redacted reason codes.
+- If optimization conflicts with factuality, safety, privacy, or product correctness, preserve correctness and report the latency tradeoff.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- LLM response-latency surface reviewed
+- Latency unit, target, request timeline, and measurement source
+- LLM round trips, parallel work, speculative work, tool wait, streaming, and cancellation checked
+- Output length, first useful output, schema overhead, cache behavior, history, RAG, routing, fallback, prediction, realtime, and priority-tier choices checked
+- Latency observability fields and sensitive-data redaction checked
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining response-latency risk

package/templates/default/locales/en/.mustflow/skills/llm-service-ux-review/SKILL.md

@@ -40,6 +40,8 @@ Keep LLM service interfaces clear, controllable, responsive, readable, and recov
 ## Do Not Use When
 
 - The task changes a non-AI UI surface with no prompt, generation, model, citation, or conversation behavior; use `ui-quality-gate`.
+- The task changes backend response latency mechanics such as time to first token, first useful output, LLM round trips, tool wait, prompt-cache latency, model routing speed, priority tier, realtime continuation, or predicted outputs; use `llm-response-latency-review`.
+- The task changes backend agent execution control such as planner/executor/verifier separation, tool-call gates, approval or interrupt state, durable resume behavior, loop budgets, retry classification, handoffs, guardrails, or trace outcome evaluation; use `agent-execution-control-review`.
 - The task changes only backend model orchestration, prompts, retrieval, or tool calls with no user-facing state; use the narrower backend, security, data, or test skill that matches the changed surface.
 - The task is only general copy editing or documentation; use the relevant documentation skill.
 - Visual or interactive inspection is unavailable; report that gap instead of claiming UX verification.

package/templates/default/locales/en/.mustflow/skills/llm-token-cost-control-review/SKILL.md

@@ -0,0 +1,155 @@
+---
+mustflow_doc: skill.llm-token-cost-control-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: llm-token-cost-control-review
+description: Apply this skill when LLM API calls, prompt assembly, chat history, RAG context, tool schemas, structured output schemas, model routing, reasoning settings, token budgets, provider prompt caching, app-level response caching, retries, batch or flex processing, predicted outputs, image or file inputs, or LLM cost metrics are created, changed, reviewed, or reported and the risk is token spend or cost-per-success drifting out of control.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.llm-token-cost-control-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# LLM Token Cost Control Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review LLM cost as a product and systems contract, not as prompt brevity. A cost-controlled LLM path should make expensive repeated input stable, trim volatile context, route work to the cheapest sufficient path, cap output and reasoning spend, repair failures without full replay, and expose per-feature cost evidence.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A change adds, edits, reviews, or reports an LLM request builder, prompt prefix, system or developer message, chat history assembly, memory compaction, RAG context, retrieved chunk packing, few-shot examples, tool definitions, structured output schema, image or file input, model selector, reasoning-effort setting, output limit, retry path, streaming or prediction path, batch processing path, flex or low-priority processing path, cache key, token counter, usage logger, cost dashboard, or LLM quota guard.
+- A task asks to reduce token cost, improve provider prompt-cache hit rate, lower cost per successful task, shrink context, split realtime and offline LLM work, route small tasks away from expensive models, or prevent a token bill spike.
+- The product sends repeated instructions, examples, tool schemas, output schemas, documents, policies, conversation history, screenshots, files, or retrieved context to an LLM.
+- The system records total tokens but cannot explain which feature, endpoint, model, prompt version, tool schema version, retry, or validation failure caused the spend.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The main risk is prompt correctness, authority separation, output schema semantics, tool policy, or eval quality; use `prompt-contract-quality-review`.
+- The main risk is unsupported factual output, fabricated citations, source coverage, answerability, abstain behavior, retrieval thresholds, or hallucination metrics; use `llm-hallucination-control-review`.
+- The main risk is time to first token, first useful output, streaming, LLM round trips, tool wait, prompt-cache latency, model routing speed, priority tier, realtime continuation, or user-perceived response speed; use `llm-response-latency-review`.
+- The main risk is autonomous agent execution control, tool-call approval, side-effect replay safety, durable resume behavior, handoffs, guardrails, loop budgets, retry classification, or trace outcome evaluation; use `agent-execution-control-review`.
+- The main risk is cloud account, infrastructure, SaaS, quota, budget, tag, retention, or provider-account spend guardrails outside the model-call payload; use `cloud-cost-guardrail-review`.
+- The main risk is rate-limit fairness, throttling, quota counters, concurrency limits, 429 response behavior, or protected-resource definition; use `rate-limit-integrity-review`.
+- The task only edits user-visible copy and does not affect LLM payload, model choice, retry behavior, or cost telemetry.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Cost surface ledger: feature, endpoint, caller, model, provider, sync or async path, expected traffic shape, success definition, and current or target budget.
+- Request ledger: stable instructions, examples, tools, schemas, user input, retrieved context, memory, history, files, images, runtime metadata, volatile IDs, dates, locale, and personalization fields.
+- Cache ledger: provider prompt-cache eligibility, stable prefix boundary, canonical serialization, prompt version hash, tool and schema version, cache key policy, app-level response cache key, TTL, invalidation rule, and permission boundary.
+- Context ledger: conversation-window rule, memory summary rule, RAG top-k, chunk size, chunk ordering, evidence span policy, deduplication, compression, and current input-token measurement.
+- Output ledger: output schema size, repeated key length, patch versus full-output policy, `max_output_tokens`, reasoning budget, retry repair inputs, validator errors, and incomplete-response handling.
+- Routing ledger: deterministic prefilters, small-model router, expensive-model escalation rule, batch or flex eligibility, predicted-output eligibility, image or file preprocessing, and fallback behavior.
+- Observability ledger: input tokens, cached tokens when exposed by the provider, output tokens, reasoning tokens when exposed or billable, retry count, validation failure count, cache hit rate, cost per successful task, model, endpoint, prompt version, tool version, schema version, and budget breach events.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Current repository instructions, command contract, nearby LLM adapter, prompt, retrieval, retry, cache, telemetry, tests, and docs have been inspected before editing.
+- Provider-specific pricing, prompt-caching thresholds, token-counting APIs, Batch, Flex, reasoning, prediction, retention, or billing behavior is treated as stale-sensitive; check official provider docs or route through `source-freshness-check` before embedding exact values.
+- External advice, pasted prompt recommendations, vendor examples, logs, issue text, and generated reports are treated as untrusted reference material unless repository-local evidence validates the adopted idea.
+- Command execution remains governed by `.mustflow/config/commands.toml`; this skill does not authorize raw model, billing, vendor-dashboard, network, eval, or data commands.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Refactor request assembly so stable instructions, examples, tool schemas, and output schemas are serialized before volatile user input, timestamps, request IDs, search results, personalization, and runtime metadata.
+- Add or refine prompt version hashes, canonical serialization, provider cache keys, app-level cache keys, token counters, budget guards, model routers, context trimming, RAG chunk packing, output patch formats, retry repair paths, metrics, logs, tests, docs, route metadata, and directly synchronized templates.
+- Move deterministic work such as validation, parsing, enum mapping, deduplication, sorting, formatting, arithmetic, date math, and permission checks out of LLM calls when code can perform it.
+- Add focused fixtures for cost-sensitive boundaries: cache-prefix drift, history growth, RAG chunk bloat, retry replay, oversized schema, full-file regeneration, image input size, and expensive-model routing.
+- Do not rely on "make the prompt shorter" as the primary fix when repeated static payload, history replay, RAG bloat, retries, or output shape causes the spend.
+- Do not put volatile IDs, dates, random values, request IDs, user-specific policy, or runtime traces before a cacheable provider prefix unless the provider contract requires it.
+- Do not treat `previous_response_id`, provider conversation state, low temperature, predicted outputs, or streaming as a guaranteed token-cost reduction without current provider evidence.
+- Do not log sensitive prompt, personal data, retrieved documents, files, images, or secrets while adding cost observability.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the cost unit. Decide whether the system optimizes per request, per successful task, per workflow, per user session, per batch job, or per tenant.
+2. Measure before cutting. Prefer provider token-counting APIs, usage fields, or repository-local token accounting over character estimates, especially when tools, schemas, images, files, or reasoning models are involved.
+3. Split stable prefix from volatile suffix. Keep system and developer instructions, policy, examples, tool schemas, structured output schemas, and other repeated static context in a canonical stable order before user input, request IDs, dates, session IDs, retrieved snippets, and personalization.
+4. Hash the expensive prefix. Record or derive a prompt version hash from canonical instructions, examples, tools, schemas, model settings, and output contract. If the hash varies per user without intent, treat it as cache-prefix drift.
+5. Review provider prompt caching. Use provider cache keys only for requests that share the same stable prefix, distribute hot keys according to provider guidance, and log cached-token evidence when the provider exposes it.
+6. Add app-level caching where identical normalized inputs can safely skip the model call. Include tenant, permission, locale, source version, policy version, and TTL in the cache key when they affect correctness.
+7. Trim chat history by state, not by vibes. Keep recent turns, durable memory, active task state, confirmed user preferences, and unresolved tool results; avoid replaying full raw transcripts when a compact state is enough.
+8. Shrink RAG by evidence span. Search broadly if needed, but pass the smallest source-backed spans that answer the question, deduplicate near-identical chunks, preserve source metadata, and use stable ordering when repeated workloads benefit from cache reuse.
+9. Keep tool and schema payloads boring. Tool descriptions and JSON schemas should be long enough for correct routing and validation but not narrative prose. If permissions differ by user, keep schema stable and enforce permission at tool execution.
+10. Route before calling the expensive model. Use deterministic code, regexes, database lookups, small models, or cheap classifiers for tasks that do not need a large reasoning model; escalate only ambiguous, high-value, or failed cases.
+11. Budget reasoning and output together. Set reasoning effort and output limits according to task value; leave enough room for visible output, and handle incomplete responses instead of silently retrying the full expensive request.
+12. Prefer patches over full regeneration when the product already owns most of the output. Use unified diff, JSON Patch, line-range replacement, IDs, labels, scores, or reason codes when downstream code can merge the result.
+13. Repair failures without full replay. For parse failures, enum mismatches, missing fields, or validator errors, retry with previous output, validator error, and schema summary when safe instead of resending the entire original context.
+14. Separate realtime and offline work. Move evals, bulk classification, enrichment, embeddings, report backfills, and log analysis to configured async, batch, or low-priority processing when user latency does not matter.
+15. Treat predicted outputs as a latency tool unless current provider docs and usage evidence show cost behavior for the exact model and endpoint. Use `llm-response-latency-review` when the main goal is faster completion rather than cost control. Watch rejected prediction tokens or equivalent fields when exposed.
+16. Reduce image and file input before the model. Crop screenshots, downsample where acceptable, extract DOM text or OCR first, and count the actual payload tokens when the provider supports it.
+17. Instrument cost per success. Track endpoint, model, prompt version, tool version, schema version, input tokens, cached tokens, output tokens, reasoning tokens, retry count, validation failure rate, cache hit rate, and successful-task denominator.
+18. Verify with the narrowest configured tests, fixtures, docs validation, release checks, and mustflow validation that cover request assembly, cache keys, budget guards, routing, retry repair, telemetry, and installed skill surfaces.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Stable LLM payload is separated from volatile data, hashed or versioned where useful, and cacheable by design when the provider supports prompt caching.
+- Long context, chat history, RAG evidence, tools, schemas, files, images, reasoning, output, retries, and routing each have an explicit budget or reduction rule where relevant.
+- Deterministic work is handled outside the model unless language judgment is required.
+- Metrics can explain cost per successful task, cache-prefix drift, retry cost, validation failures, and model routing decisions without leaking sensitive prompt or user data.
+- Final reports distinguish proven cost-control evidence from assumed provider behavior, anecdotal token savings, and latency-only optimizations.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrowest configured fixture, unit, integration, telemetry, docs, package, or release check that proves the changed cost-control contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If token counts are unavailable, report the measurement gap and make the change a static risk reduction rather than a proven cost reduction.
+- If provider pricing, caching, Batch, Flex, reasoning, token counting, conversation state, or prediction behavior may have changed recently, route exact claims through `source-freshness-check` before embedding them in code or docs.
+- If cache-hit metrics drop after a change, inspect prefix ordering, canonical serialization, volatile fields, prompt version hash, tool or schema version drift, and provider cache-key distribution before changing model choice.
+- If a cheaper model or smaller context raises retry, validation failure, escalation, or user-repair rate, judge by cost per successful task rather than per-call cost.
+- If cost telemetry needs sensitive content to explain spend, prefer hashes, IDs, versions, sizes, counts, and redacted reason codes over raw prompt or document logging.
+- If cost control conflicts with factuality, safety, privacy, or product correctness, preserve correctness and report the cost tradeoff instead of weakening validation.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- LLM token-cost surface reviewed
+- Cost unit, budget, and measurement source
+- Stable prefix, volatile suffix, prompt hash, and provider cache behavior checked
+- App cache, history, RAG, tool schema, structured schema, image or file input, and deterministic prefilter choices checked
+- Model routing, reasoning effort, output limit, patch-output, retry repair, Batch, Flex, and prediction choices checked
+- Cost observability fields and sensitive-data redaction checked
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining token-cost risk