Skip to content

amazon-science/ammo / ai_cli_session/.codex/skills/ammo

Profile and optimize GPU kernels for vLLM inference on NVIDIA GPUs. Use when targeting a specific model, hardware, dtype, parallelism, and workload to improve latency.

FileKindSize
RUNTIME.mdmarkdown4.9 KB
SKILL.mdskill md18.5 KB
agents/ammo-auditor.mdmarkdown9.1 KB
agents/ammo-champion.mdmarkdown9.6 KB
agents/ammo-delegate.mdmarkdown3.2 KB
agents/ammo-implementer.mdmarkdown13.8 KB
agents/ammo-investigator.mdmarkdown4.0 KB
agents/ammo-report.mdmarkdown2.9 KB
agents/ammo-researcher.mdmarkdown10.3 KB
agents/ammo-resolver.mdmarkdown4.4 KB
agents/ammo-transcript-monitor.mdmarkdown7.8 KB
agents/openai.yamlexecutablescript313 B
data/ATTRIBUTION.mdmarkdown1.4 KB
data/gsm8k_full.jsonexecutablescript735.5 KB
data/gsm8k_subset.jsonexecutablescript116.8 KB
eval/EVAL-SKILL.mdexecutablescript21.8 KB
eval/agents/transcript_grader.mdexecutablescript18.0 KB
eval/causal/__init__.pyexecutablescript137 B
eval/causal/agents/causal_analyzer.mdexecutablescript10.5 KB
eval/causal/build_dag.pyexecutablescript21.6 KB
eval/causal/diff_versions.pyexecutablescript38.5 KB
eval/causal/extract_events.pyexecutablescript36.3 KB
eval/causal/generate_postmortem.pyexecutablescript17.0 KB
eval/causal/score_nodes.pyexecutablescript21.5 KB
eval/causal/templates/narrative_template.mdexecutablescript472 B
eval/causal/templates/viz_template.htmlexecutablescript9.5 KB
eval/causal/tests/__init__.pyexecutablescript151 B
eval/causal/tests/conftest.pyexecutablescript448 B
eval/causal/tests/fixtures/sample_session.jsonlexecutablescript10.4 KB
eval/causal/tests/fixtures/sample_session_data.jsonexecutablescript3.4 KB
eval/causal/tests/fixtures/sample_snapshot.jsonexecutablescript2.5 KB
eval/causal/tests/test_build_dag.pyexecutablescript2.7 KB
eval/causal/tests/test_diff_versions.pyexecutablescript13.5 KB
eval/causal/tests/test_extract_events.pyexecutablescript3.7 KB
eval/causal/tests/test_generate_postmortem.pyexecutablescript3.1 KB
eval/causal/tests/test_score_nodes.pyexecutablescript3.3 KB
eval/scripts/aggregate_versions.pyexecutablescript15.2 KB
eval/scripts/archive_run.pyexecutablescript9.1 KB
eval/scripts/codex_session.pyexecutablescript10.6 KB
eval/scripts/generate_dashboard.pyexecutablescript5.3 KB
eval/scripts/parse_artifacts.pyexecutablescript48.1 KB
eval/scripts/parse_session_logs.pyexecutablescript51.3 KB
eval/scripts/rescore_archived.pyexecutablescript5.5 KB
eval/scripts/score_campaign.pyexecutablescript43.8 KB
eval/scripts/snapshot_changes.pyexecutablescript11.1 KB
eval/scripts/verify_citations.pyexecutablescript8.8 KB
eval/tests/test_dashboard_bugs.pyexecutablescript8.8 KB
eval/tests/test_parse_session_logs.pyexecutablescript3.9 KB
eval/tests/test_parse_session_logs_round_inference.pyexecutablescript11.0 KB
eval/tests/test_score_campaign_diluted.pyexecutablescript9.4 KB
eval/viewer/dashboard_template.htmlexecutablescript15.1 KB
instrumentation/sitecustomize.pyexecutablescript3.6 KB
orchestration/audit-protocol.mdmarkdown9.3 KB
orchestration/debate-protocol.mdmarkdown11.2 KB
orchestration/integration-logic.mdmarkdown10.3 KB
orchestration/parallel-tracks.mdmarkdown8.9 KB
references/artifact-layout.mdexecutablescript22.4 KB
references/audit-invariants.mdmarkdown10.6 KB
references/champion-common-patterns.mdmarkdown3.4 KB
references/crossover-probing.mdexecutablescript4.7 KB
references/cudagraph-safety.mdmarkdown2.7 KB
references/debate-rules.mdmarkdown4.7 KB
references/debate-scoring-rubric.mdexecutablescript16.7 KB
references/e2e-delta-math.mdexecutablescript17.9 KB
references/e2e-latency-guide.mdexecutablescript9.6 KB
references/fusion-feasibility-heuristics.mdmarkdown5.6 KB
references/gpu-pool.mdexecutablescript5.4 KB
references/impl-track-rules.mdexecutablescript13.8 KB
references/nsys-profiling-guide.mdmarkdown9.8 KB
references/optimization-categories.mdexecutablescript11.0 KB
references/shutdown-protocol.mdexecutablescript3.1 KB
references/technology-selection.mdmarkdown5.0 KB
references/torch-compile-contract.mdmarkdown13.8 KB
references/validation-defaults.mdexecutablescript34.2 KB
references/workload-invocation.mdexecutablescript4.9 KB
references/writing-style.mdexecutablescript6.9 KB
scripts/ammo_state.pyexecutablescript142.0 KB
scripts/artifact_layout.jsonconfig16.3 KB
scripts/check_projection_accuracy.pyexecutablescript11.7 KB
scripts/create_evidence_template.pyexecutablescript9.7 KB
scripts/create_worktree_with_build.shexecutablescript10.2 KB
scripts/generate_validation_report.pyexecutablescript35.7 KB
scripts/gpu_reservation.pyexecutablescript27.1 KB
scripts/hook_cmd_classify.pyscript13.3 KB
scripts/mine_trace.pyscript29.4 KB
scripts/monitor_queue_ack.pyexecutablescript6.1 KB
scripts/ncu_sanity.shexecutablescript5.2 KB
scripts/ncu_sanity_driver.pyexecutablescript8.5 KB
scripts/new_target.pyexecutablescript22.0 KB
scripts/preflight_vllm_api.pyexecutablescript12.3 KB
scripts/reconcile_track_state.pyexecutablescript15.8 KB
scripts/remove_worktree_cleanup.shexecutablescript1.1 KB
scripts/resolve_codex_transcript.pyexecutablescript3.6 KB
scripts/run_vllm_bench_latency_sweep.pyexecutablescript249.6 KB
scripts/transcript_filter.pyexecutablescript38.4 KB
scripts/transitions.jsonexecutablescript1.5 KB
scripts/verify_validation_gates.pyexecutablescript88.8 KB
tests/agents/test-champion.mdexecutablescript20.4 KB
tests/agents/test-impl-champion.mdexecutablescript14.3 KB
tests/agents/test-implementer.mdexecutablescript15.8 KB
tests/agents/test-orchestrator.mdexecutablescript33.8 KB
tests/agents/test-researcher.mdexecutablescript21.0 KB
tests/agents/test-transcript-monitor.mdexecutablescript13.4 KB
tests/fixtures/diluted_pass/legacy_no_phase.golden.mdmarkdown1.1 KB
tests/fixtures/diluted_pass/legacy_no_phase.golden.summary.jsonconfig582 B
tests/fixtures/diluted_pass/legacy_no_phase.jsonconfig400 B
tests/fixtures/diluted_pass/legacy_scalar_phase.golden.mdmarkdown2.0 KB
tests/fixtures/diluted_pass/legacy_scalar_phase.golden.summary.jsonconfig1.0 KB
tests/fixtures/diluted_pass/legacy_scalar_phase.jsonconfig626 B
tests/fixtures/mining/real_campaign_bottleneck_analysis.mdmarkdown20.7 KB
tests/run_all.shexecutablescript1.6 KB
tests/scripts/test_transcript_filter.pyexecutablescript41.1 KB
tests/test_agent_runtime_contracts.pyexecutablescript1.8 KB
tests/test_ammo_state.pyexecutablescript71.7 KB
tests/test_artifact_layout_manifest.pyscript11.6 KB
tests/test_audit_started.pyscript18.2 KB
tests/test_correctness_comparator.pyscript12.6 KB
tests/test_diluted_pass.pyscript24.4 KB
tests/test_drift_compat.pyscript5.1 KB
tests/test_evidence_freshness.pyexecutablescript5.6 KB
tests/test_fail_closed.pyexecutablescript14.7 KB
tests/test_gpu_reservation.pyexecutablescript24.8 KB
tests/test_gpu_reservation_session_id.pyexecutablescript11.2 KB
tests/test_guidance_semantic_contract.pyscript24.9 KB
tests/test_hook_cmd_classify_parity.pyscript11.7 KB
tests/test_hook_semantics.pyexecutablescript95.3 KB
tests/test_mine_trace.pyscript24.2 KB
tests/test_mining_invalidated_schema.pyexecutablescript9.4 KB
tests/test_new_target_dp_ep.pyexecutablescript7.4 KB
tests/test_new_target_v2_scaffold.pyexecutablescript13.1 KB
tests/test_parse_artifacts.pyexecutablescript3.0 KB
tests/test_policy_convergence.pyscript797 B
tests/test_preflight_vllm_api.pyscript13.3 KB
tests/test_projection_accuracy_v2.pyexecutablescript4.1 KB
tests/test_reconcile_track_state.pyexecutablescript18.2 KB
tests/test_resolve_codex_transcript.pyexecutablescript3.1 KB
tests/test_state_schema_semantics.pyexecutablescript7.6 KB
tests/test_status_set_sync.pyexecutablescript9.1 KB
tests/test_sweep_baseline_from_arm.pyscript11.0 KB
tests/test_sweep_decode_capture.pyexecutablescript31.8 KB
tests/test_sweep_dp.pyexecutablescript45.4 KB
tests/test_sweep_fresh_cache.pyscript5.5 KB
tests/test_sweep_profiler_guard.pyscript22.6 KB
tests/test_sweep_real_prompts.pyscript20.1 KB
tests/test_sweep_refactor.pyexecutablescript37.6 KB
tests/test_sweep_round_slot.pyexecutablescript7.4 KB
tests/test_validation_report_phase_triage.pyexecutablescript10.0 KB
tests/test_validation_report_v2.pyexecutablescript6.2 KB
tests/test_verify_validation_gates.pyexecutablescript52.9 KB
tests/test_workload_matrix.pyexecutablescript19.3 KB

references/optimization-categories.md

View on GitHub
# Optimization Category Taxonomy

Every Phase 0 proposal declares a `## Category`. This file is the canonical catalog of those categories, and it tells you what the declaration is for: it routes the proposal to a likely measurement boundary and an instrumentation route. Read it when you write a Phase 0 proposal, when you check one, or when you need to know where a mechanism gets measured.

Category is a **non-binding descriptor**, not the eligibility gate. Eligibility needs an authored mechanism that targets a profiled bottleneck and carries an admissible production-boundary projection. The category never supplies the mechanism.

This file is referenced from:
- `SKILL.md` — stage and role contract
- `references/e2e-delta-math.md` — projection authority (single source)
- `references/technology-selection.md` — eligible technologies per category
- `references/validation-defaults.md` — default Gate 5.2 form
- `references/debate-scoring-rubric.md` — EV / scope admissibility
- `agents/ammo-champion.md` — Category field requirement in Phase 0 template
- `agents/ammo-implementer.md` — per-category validation gate routing + scaffolds (the impl-champion runs the kernel correctness & speedup checks)
- `orchestration/debate-protocol.md` — Category eligibility gate, champion spawn context

---

## Schema-Version Guard (Legacy Campaigns)

The Category requirement applies only to campaigns with `state.json.campaign.schema_version >= "4.1"`. Legacy campaigns (`schema_version < "4.1"` or absent) keep the older Phase 0 eligibility rules: Authored-Mechanism Mandate, Technology Selection, and Precision Classification only. The lead reads `state.json` and skips every Category-related gate when the schema version is older than 4.1, because a paused or in-flight campaign must still resume.

This mirrors the schema-version guard in `new_target.py`.

---

## When the Category Is Chosen (Phase 0)

A category is a conclusion you draw from data. The data answers questions like these: does a fusable seam exist, can a kernel be replaced by a faster one, or do host-side dispatch gaps dominate? The existing profiling data for the component(s) a candidate attacks makes the answer clear.

The champion selects the category in **Phase 0**, after it analyzes the full profile. Each of a champion's 2-3 ranked candidates declares its own category. See `agents/ammo-champion.md` § Candidate Eligibility and Generation and `orchestration/debate-protocol.md` § Phase 0: Independent Proposals.

This shapes exhaustion filtering. During candidate generation, a champion skips a component only when its relevant mechanisms are unambiguously closed. The lead then applies the soft exhaustion check during Phase 0 eligibility, once the proposal declares a concrete category and technology. This matches the structured `exhausted_technologies[]` scope.

---

## The Category Catalog (a descriptor, not a gate)

The authored-mechanism and evidence rules decide eligibility, not this table. Each row gives you a descriptor, a likely boundary, and an instrumentation hint. The catalog is also **non-exhaustive**: a novel mechanism stays eligible, so choose the closest schema-defined descriptor and explain the mismatch instead of inventing a state value outside the schema enum.

**Decode-kernel-slice classes** (likely boundary: kernel / fused chain):

| Category | Scope / what's authored | Slice targeted |
|----------|-------------------------|----------------|
| `kernel_replacement` | Single kernel → faster alternative | `f_e2e(kernel)` |
| `kernel_fusion` | N kernels → 1 fused kernel | `f_e2e(chain)` |
| `custom_kernel` | New/rewritten kernel compute (Triton/CuTeDSL/CUTLASS/CUDA C++) — legacy alias of `kernel_replacement` | `f_e2e(kernel)` |
| `weight_layout_transform` | Load-time weight concat/repack/requant + slice, library does the matmul (e.g. QKV/gate-up weight-merge) | `f_e2e(chain)` |
| `attention_kv_layout` | Authored KV-cache layout / new AttentionBackend / metadata builder | `f_e2e(kernel)` |

**Inter-kernel-slice classes** (likely boundary: actual-runner host interval):

| Category | Scope / what's authored | Slice targeted |
|----------|-------------------------|----------------|
| `dispatch_optimization` | CPU↔GPU pipelining, dispatch elimination | host portion of `inter_kernel_share` |
| `execution_pipeline_restructuring` | Authored scheduling / H2D-D2H overlap / async-stream / CUDA-graph capture-boundary code — legacy alias of `dispatch_optimization` | host portion of `inter_kernel_share` |
| `communication_strategy` | Authored collective-comm algorithm / EP dispatch / EPLB / comm-compute overlap | host portion of `inter_kernel_share` |
| `compute_graph_pass` | Authored Inductor/FX pattern-matcher pass that rewrites the compiled graph | host portion of `inter_kernel_share` |

**Legacy aliases (retained, never deleted):** `kernel_replacement` conceptually folds into `custom_kernel`; `dispatch_optimization` conceptually folds into `execution_pipeline_restructuring`. Both old values stay valid so paused campaigns resume.

Retuned constants and existing-path flag flips are configuration, not authored mechanisms.

---

## Where the Projection and Evidence Rules Live

Projection formulas, the slice-split rule, and the evidence-scope ladder live in their own authority docs, never here. This file gives descriptors, likely boundaries, and instrumentation hints only.

See `references/e2e-delta-math.md` § Projection Authority — One Boundary Equation and § Pre-Implementation Magnitude — Slice Split. See `references/debate-rules.md` § Evidence-Scope Ladder for scope admissibility.

---

## Phase 0 Evidence (by slice)

Attach the strongest bounded evidence you have for the load-bearing claim, per `references/debate-rules.md` § Claim-Driven Experiments (run an experiment or declare the evidence gap).

See `references/e2e-delta-math.md` § Pre-Implementation Magnitude — Slice Split (which scope is EV-eligible per slice) and § Projection Authority. Tier caps: `references/debate-rules.md` § Execution Confidence.

---

## Validation Gate Routing

Gate 5.2 is defined once, and its boundary follows the mechanism (kernel, fusion, dispatch/graph, overlap); `references/validation-defaults.md` § Gate 5.2 owns the mechanism → boundary mapping. Gate 5.3a always uses production activation evidence for the mechanism at hand; host and inter-kernel work does not pretend to have a replacement-kernel proof.

---

## Technology Fit

A category never whitelists technologies, and it never implies a static abstraction ranking. Use the closest schema-defined category as a descriptor, then apply the capability-based production-baseline rule in `technology-selection.md` to the actual mechanism. Kernel, compiler, library, and host-side implementations are all valid when their evidence and production integration support the claim.

---

## Disambiguating Examples

These worked cases fix the two boundaries the table cannot: which slice a mechanism really targets, and where configuration ends and an authored mechanism begins.

### Example 3 — dispatch_optimization (accepted)

> Fuse the MTP target-model preamble (28 eager kernel launches: torch.compile op + H2D copies + elementwise updates) into a single Triton `delta_advance` kernel that eliminates 27 dispatches and caches structurally-constant H2D uploads.

- **Category: `dispatch_optimization`**. The win is dispatch elimination — the 28 kernels collectively compute ~107 µs but incur ~6800 µs of inter-kernel gap time.
- **Boundary**: actual-runner host interval (Gate 5.2 measures wall-time drop, not kernel-vs-kernel speedup — see `references/validation-defaults.md` § Gate 5.2). The kernel speedup is decorative; the preamble wall-time reduction drives E2E.
- **Technology**: Triton (fused dispatch kernel) + Python (H2D caching, sync deferral).

### Example 4 — Rejected proposal: env-var flip (no Category will save it)

> Set `VLLM_USE_FLASHINFER_SAMPLER=1` in production.

- **Rejected at authored-mechanism eligibility.** The env var selects an existing code path; no mechanism is authored.

### Example 4b — Rejected proposal: tuning constant in `.py` (no Category will save it)

> Change `num_stages=2` → `num_stages=3` (or `num_warps`, `BLOCK_SIZE_M`, an `@autotune` config tuple, or a TRTLLM tactic-table entry) in a Triton/kernel source file. Measured +0.69% E2E.

- **Rejected at authored-mechanism eligibility** even with a measured win. The kernel body is unchanged; a constant in `.py` is still configuration.

### Example 4c — Eligible: authored logic that achieves the same effect

> Hand-write a software-pipelined prefetch loop in the kernel body that achieves what `num_stages` would, with an explicit double-buffer and `cp.async` schedule you wrote.

- **Eligible at authored-mechanism eligibility.** The mechanism logic is authored; magnitude still requires admissible evidence.

---

## Cross-Category Anti-Regression

A new category string alone does not prove forward progress, because two aliases can describe the same measured slice and the same mechanism. Across rounds, require one of three things: a changed mechanism, a different measured slice, or new evidence that invalidates the prior failure. The structured exhaustion scope stays authoritative.

---

## Verifying a Proposal's Category Block

The lead's eligibility check in `orchestration/debate-protocol.md` § Eligibility, revision, and elimination validates the Category block on schema_version ≥ 4.1 campaigns. These fields are required, verbatim from `agents/ammo-champion.md`:

```markdown
## Category
- Selected: <a schema-defined category; for a novel mechanism, choose the closest descriptor and explain the mismatch>
- Slice targeted: <f_e2e(component) | f_e2e(chain) | host portion of inter_kernel_share>
- Projection formula: <the one boundary equation from `references/e2e-delta-math.md`, numeric>
- Justification: <1-2 sentences citing the champion's analysis of the existing profiling data for the assigned component (the seam/op-character that makes this the right mechanism), with workload-composition data from bottleneck_analysis.md as support>
- Expected validation gates: <list per `validation-defaults.md` Gates 5.1-5.3>
- Evidence scope: <bound | proxy | production_boundary | clean_e2e>
```

A missing block is rejected at the eligibility gate after one revision opportunity — the same severity as a missing Technology Selection block. Projection uses the one boundary equation in `references/e2e-delta-math.md`; proxy-scope magnitude is EV-ineligible. Category membership never makes an otherwise ineligible mechanism eligible.

---

## References

- `e2e-delta-math.md` — `f_e2e` definition, four-slice composition, projection authority (single source)
- `technology-selection.md` — eligible technologies per category (§5.5)
- `validation-defaults.md` — Gate 5.2 authority
- `debate-scoring-rubric.md` — EV / scope admissibility
- `audit-invariants.md` — Stage 2 invariants on category fields
- `agents/ammo-champion.md` — Phase 0 Category block template
- `orchestration/debate-protocol.md` — Phase 0 eligibility/exhaustion check and champion choreography
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall