Orchestration Workflow

Optimization Cycle

1. ANALYZE    -> Read devlog overview + current best results
2. PROFILE    -> Launch Profiler Agent -> get compact bottleneck analysis
3. SELECT     -> Choose implementation language based on the required control level
4. STRATEGIZE -> Load the shared optimization guidance plus the language-specific optimization catalog
5. DESIGN     -> Launch Kernel Designer Agent -> implement optimizations in new version
6. VERIFY     -> Launch Profiler Agent on new version -> compare with previous
7. EVALUATE   -> Target met? -> Done. Not met? -> Back to step 3
8. LEARN      -> If novel insight: update knowledge base (mandatory)

LEARN

Default Configurations

Speculative Decoding

b=32, s=16, t=4096

b

Default Trial Matrix for Exploratory Tuning

• Decode-like:

  b=32, s=1, t=4096

• Speculative-like:

  b=32, s=16, t=4096

• Add a third stress configuration only when a strategy or devlog evidence shows the first two points are insufficient.

Tuning Space Exploration

• Start with testing a manual tuning tiling configuration that is expected to be good
• Explore some tiling configurations to understand how performance changes with tile sizes
• If the situation is complex, consider gross autotuning to find good configurations, but be mindful of the combinatorial explosion (use domain knowledge to prune the search space), autotuning time should be small enough to keep the kernel design exploration fast (e.g., < 1 hour per kernel version)
• If a kernel version shows significant potential, consider a more fine-grained autotuning to further refine the performance, otherwise, proceed to the next optimization iteration (do not spend too much time autotuning a kernel version that is not promising enough)

mla_var6_plus_v3

mla_var6_plus_v2

Sub-Agent Launch Templates

.claude/agents/

Profiler

profiler

Profile <kernel> <version> at b=X, s=X, t=X.
Return compact summary per the output contract.
Update the devlog performance section in docs/kernels/<kernel>.md.

/profile-kernel

Kernel Designer

kernel-designer

Create <kernel> <new_version> from <current_version>.
Language: <cutile-dsl|cute-dsl>.
Load /design-<language>-kernel and the matching reference skill if one exists.
Apply optimizations: [specific list with rationale].
Return implementation summary per the output contract.

/design-kernel

Agent Communication Contracts

Profiler -> Orchestrator (compact output)

## Profile: [kernel] [version] | b=X, s=X, t=X
### Stages
| Stage | Duration | TC% | DRAM% | Occ% | Bottleneck | Key Issue |
### Bottleneck: [Memory/Compute/Latency]-bound
Root cause: [2 sentences]
### Top 3 Opportunities (ranked by estimated impact)
1. [name] -- est. X% gain -- trigger: [metric=value]

### vs Baseline (if applicable)
| Metric | Previous | Current | Change |
|--------|----------|---------|--------|

Orchestrator -> Designer (instructions)

## Optimization Task: [kernel] [current] -> [new_version]
### Current Bottleneck: [from profiler]
### Optimizations to Apply:
1. [specific optimization + rationale + link to the shared or language-specific knowledge file]

### Constraints
- register budget, target occupancy, required control level, and language-specific constraints

Designer -> Orchestrator (summary)

## New Version: [kernel] [version]
### Changes Applied: [list]
### Files: Created/Modified [paths]
### Correctness: [PASS/FAIL]

### Trial Configurations Checked
1. [b, s, t] -- [why this point matters]

### Devlog Entry Written: [path]

Knowledge Base Update Protocol

When to Update

• After profiling a kernel, if a new relevant optimization or anti-pattern is identified that is not currently in the catalog
• After profiling a kernel, if an existing optimization/anti-pattern is confuted, to update its validity conditions or change it to an anti-pattern/optimization as needed
• When new performance evidence refines the estimated impact of an optimization or the failure mode of an anti-pattern
• When new interactions between optimizations are discovered
• When a device-specific result can be abstracted into a reusable rule

New Optimization Validated

1. Decide whether the finding is shared algorithmic/hardware knowledge or language-specific implementation knowledge.
2. Shared knowledge goes under

   docs/knowledge/optimizations/<name>.md

   .
3. Language-specific knowledge goes under

   docs/knowledge/languages/<language>/optimizations/<name>.md

   .
4. Add the corresponding row to the optimization index in the

   /optimization-catalog

   skill.
5. Capture the reusable pattern, applicability context, and the primary metrics affected.
6. Explicitly separate local evidence and generalization.

Optimization Caused Clear Regression

1. Decide whether the failure mode is shared or language-specific.
2. Shared anti-patterns go under

   docs/knowledge/anti-patterns/<name>.md

   .
3. Language-specific anti-patterns go under

   docs/knowledge/languages/<language>/anti-patterns/<name>.md

   .
4. Add the corresponding row to the anti-pattern index in the

   /optimization-catalog

   skill.
5. Document the failure mode in reusable terms, not just the failing kernel/version.
6. Record which metrics exposed the problem and under what context it appears.

Detail File Template

When to Apply

# [Optimization Name]

## When to Apply
- [Context 1: e.g., specific kernel design or reference layer/kernel]
- [Context 2]
- [Metric condition 1]
- [Metric condition 2]

## Mechanism
[How and why this optimization works]

## Affected Metrics
- [Metric 1: e.g. occupancy]
- [Metric 2: e.g. registers/thread]
- [Metric 3: e.g. Tensor Core utilization, DRAM throughput, L2 hit rate, local-memory traffic]

## Implementation
\`\`\`python
# Code snippet
\`\`\`

## Performance Evidence
Source type: [local experiment / external report]
| Config | Before | After | Change |
|--------|--------|-------|--------|

## Generalization
[Device-agnostic takeaway. Mention architecture/device facts only insofar as they sharpen the reusable rule.]

## Pitfalls
- [Known failure modes]

## Interactions
- [How this interacts with other optimizations]