---
title: '60111'
pageLayout: default
slug: thoughts/inference/vllm-prs/60111
permalink: https://aarnphm.xyz/thoughts/inference/vllm-prs/60111.md
generator:
  quartz: v4.6.0
  hostedProvider: Cloudflare
  baseUrl: aarnphm.xyz
full: https://aarnphm.xyz/llms-full.txt
---
# [#60111](https://github.com/aarnphm/aarnphm.github.io/issues/60111) \[Docs\] Add disagg PD flow-example guidance to /pr-checklist skill

[vllm-project/vllm#60111](https://github.com/vllm-project/vllm/pull/60111) · NickLucche · MERGED · created 2026-10-05T19:59:35Z · merged 2026-10-07T22:16:06Z

## Overview

Follow-up to [#57084](https://github.com/aarnphm/aarnphm.github.io/issues/57084) (merged). Extends the `/pr-checklist` skill so that fixes involving disaggregated prefill/decode (PD) logic, such as the NIXL connector, include a minimal example of the flow being changed and/or the initial flow that caused the failure.

## Claims

- Adds one paragraph to section 4.3 (Root-Cause Analysis) of `.agents/skills/pr-checklist/SKILL.md`: for disagg PD fixes (NIXL connector named as the example), make a best effort to include a minimal example of the changed flow and/or the initial failing flow.
- Links the existing disaggregated-prefill feature doc and the NIXL design docs for reference.
- Documentation/agent-instructions only: no code, PR template, or `AGENTS.md` changes.

## Validation

Docs-only change; no runtime behavior is modified, so runtime tests, model evaluations, and benchmarks are not applicable.



```bash
git diff --check
.venv/bin/pre-commit run --files .agents/skills/pr-checklist/SKILL.md
# verify the linked docs and the referenced code path resolve
test -f docs/features/disagg_prefill.md
test -f docs/design/nixl_kv_push_connector.md
test -f docs/design/nixl_kv_cache_lease.md
test -d vllm/distributed/kv_transfer/kv_connector/v1/nixl
```

- `git diff --check`: clean (no whitespace errors).
- `pre-commit run --files .agents/skills/pr-checklist/SKILL.md`: all hooks passed, including `markdownlint-cli2` and the agent-instruction/skill checks (also enforced again by the commit-time hooks).
- All three linked docs and the referenced NIXL connector path exist at the linked locations.
- Reviewed the full diff: one added paragraph, no other changes.

### Duplicate-work checks (run 2026-10-05)



```bash
gh search prs --repo vllm-project/vllm --state open --limit 30 "pr-checklist"
gh search prs --repo vllm-project/vllm --state open --limit 30 "skill in:title"
gh search prs --repo vllm-project/vllm --state open --limit 30 "checklist in:title"
gh search prs --repo vllm-project/vllm --state open --limit 30 "disagg PD flow"
gh search prs --repo vllm-project/vllm --state open --limit 30 "nixl flow example"
gh search prs --repo vllm-project/vllm --state open --limit 20 "57084 in:body"
gh pr list --repo vllm-project/vllm --state open --author NickLucche --limit 20
gh api "repos/vllm-project/vllm/commits?path=.agents/skills/pr-checklist/SKILL.md&per_page=10"
```

- No open PR modifies the `pr-checklist` skill or adds a similar flow-example requirement; the only commit touching `SKILL.md` is the original merge `8fb16ea5` ([#57084](https://github.com/aarnphm/aarnphm.github.io/issues/57084)).
- No associated issue exists (this is a follow-up to a merged PR), so issue-specific duplicate checks were not applicable.

## Details

### Motivation

The review discussion on [#57084](https://github.com/aarnphm/aarnphm.github.io/issues/57084) (njhill) suggested adding “pointers to examples of some of the points, in the form of prior PR or existing code sections / features that exemplify our expectations” as a later improvement. Recent NIXL / disagg PD fixes (e.g. [#59953](https://github.com/aarnphm/aarnphm.github.io/issues/59953), [#59586](https://github.com/aarnphm/aarnphm.github.io/issues/59586), [#56341](https://github.com/aarnphm/aarnphm.github.io/issues/56341)) show the gap this closes: the root cause often only manifests across the P/D boundary (scheduler admission, prefill execution, KV transfer registration/write, decode-side read), and a reviewer cannot trace it from the diff alone.

### Change

One paragraph added to section 4.3 (Root-Cause Analysis); see the diff for the full text. In short: for fixes that involve disaggregated prefill/decode (PD) logic, such as the NIXL connector (`vllm/distributed/kv_transfer/kv_connector/v1/nixl/`), make a best effort to include a minimal example of the flow being changed and/or the initial flow that caused the failure, as a short numbered sequence (or diagram) of a request’s path across the P and D instances, kept to the steps and components involved in the change.

Placement rationale: section 4.3 owns bug-fix PR contents (root cause), and section 4 applies to both authors and reviewers, so reviewers can also use it to request a missing flow example. The requirement is a “best effort” rather than a hard gate. The PR template and `AGENTS.md` are unchanged: the template’s “Pull Request Contents” checklist item already covers root causes, and `AGENTS.md` already mandates the skill for agents.

### A/B test on [#59586](https://github.com/aarnphm/aarnphm.github.io/issues/59586) (reviewer request)

> Ran the updated skill against [#59586](https://github.com/aarnphm/aarnphm.github.io/issues/59586) (NIXL/disagg-PD bugfix). The only difference between skill versions is the new §4.3 paragraph:
>
> - Old skill: §4.3 passes on the prose root cause; no flow example requested.
> - New skill: §4.3 flags that the description lacks a minimal PD flow example. Draft produced by that check:
>   1. Startup (P and D): the runner picks a kernel block size per KV cache group from that group’s backends (`prepare_kernel_block_sizes`) — the MLA group gets 128/256.
>   2. Startup (P and D): `_sync_block_size_with_kernel` picks one block size across all attention backends in the process; the drafter’s backend supports only 64 → NIXL block = 64, `num_blocks` doubled.
>   3. Startup, failing flow: `register_kv_caches` builds the MLA view `[num_blocks, 1, 128, C]`; a kernel row spans two 64-token NIXL pages → `AssertionError: KV cache view cannot be partitioned into NIXL regions` (silent variant: whole storage registered as one region with the 128-token row stride).
>   4. Serving, failing flow: P writes KV through those descriptors, D reads them → wrong bytes, no error.
>   5. Fixed flow: the contiguous MLA row is split into dense 64-token NIXL pages (`_uses_dense_virtual_transfer_pages`, now also for `tokens_per_state == 1` and `SlidingWindowMLASpec`); one region per layer, page-sized `block_len`/`block_stride`, identical on both peers via the handshake.
> - All other sections: identical verdicts under both versions. §1/§2/§3 pass; re-review items on [#59586](https://github.com/aarnphm/aarnphm.github.io/issues/59586) (4 inline comments + 1 open question) remain outstanding there.
> - Fix verification: new unit test fails without the fix (`[256]`: the partition `AssertionError` above; `[128]`: silent wrong registration, `num_regions == 1 != 2`) and passes with it; full `test_nixl_desc_geometry.py`: 224 passed.
>
> A/B run with Mistral Vibe.

### AI assistance

AI assistance (Mistral Vibe) was used to draft this one-paragraph change, run the duplicate-work checks, and prepare this description. Opened as a draft: per the `AGENTS.md` accountability policy, the human submitter must review every changed line before this PR is marked ready for review.

---

<details>
<summary> Pull Request Checklist </summary>

- [x] I used vLLM’s `/pr-checklist` skill.
- [x] AI assistance was used during the creation of this PR.
- [x] **Design Fit:** Single-paragraph addition to an existing skill; no core-component or runtime impact.
- [x] **Testing and Validation:** Docs-only; whitespace, pre-commit, and link/path checks run as shown above; runtime validation not applicable.
- [x] **Code Quality and Style:** Matches the skill’s existing single-paragraph style; no unrelated formatting changes.
- [x] **Pull Request Contents:** Summary, claims, evidence, duplicate-work checks, motivation, limitations, and AI disclosure included.

</details>

---

## comments

**benchislett** (2026-10-05T20:59:59Z):

seems like an easy one to A/B test, @NickLucche can you run it on e.g. [vllm-project/vllm#59586](https://github.com/vllm-project/vllm/pull/59586) and see if the output is more to your liking?

**benchislett** (2026-10-05T21:00:18Z):

I’m happy to merge in the meantime, don’t let me block. We can always follow-up with more changes

**NickLucche** (2026-10-07T22:12:34Z):

Sorry for the delay @benchislett , added the AB testing on the PR description.
I think stepping with roles is clearer

**NickLucche** (2026-10-07T22:12:41Z):

/ci run —allow-stale

**github-actions** (2026-10-07T22:13:02Z):

✅ Triggered [Buildkite CI #93434](https://buildkite.com/vllm/ci/builds/93434) for commit `cf46c0d31925`.

⚠️ This PR is 31 commits behind upstream `main`. Running CI at your own risk because `--allow-stale` was requested; outdated CI configuration may cause failures. Before merging, merge or rebase onto the latest `main`, then rerun `/ci run` on the latest PR commit.

