From f87fa00dfe17ddca747b01b71633e163b6930140 Mon Sep 17 00:00:00 2001 From: LinuxDev9002 Date: Sun, 19 Jul 2026 14:59:06 -0700 Subject: [PATCH] Require feature background in tutorial openings --- .agents/skills/bpf-tutorial-writing-style/SKILL.md | 6 ++++++ .../references/prose-and-bilingual-checklist.md | 5 +++++ .agents/skills/write-bpf-production-tutorial/SKILL.md | 6 ++++++ 3 files changed, 17 insertions(+) diff --git a/.agents/skills/bpf-tutorial-writing-style/SKILL.md b/.agents/skills/bpf-tutorial-writing-style/SKILL.md index e8cba32..155686c 100644 --- a/.agents/skills/bpf-tutorial-writing-style/SKILL.md +++ b/.agents/skills/bpf-tutorial-writing-style/SKILL.md @@ -21,6 +21,12 @@ Start with a short, truthful scene the reader can picture. Show one observable p Treat the scene as a teaching device, not a license to write fiction. Do not invent a named operator, customer, outage, deployment, benchmark, urgency, or result. If the implementation is a bounded lab tool, make the scene a bounded lab situation and let the real mechanism make it interesting. +## Give the feature a place in the series + +After the scene, identify the lesson once as part of the **eBPF Tutorial by Example** series. Give the reader a short ladder from eBPF to the example: explain the relevant verified-program and user-space attachment model, introduce the specific hook or subsystem, state the first Linux release that added the enabling feature, and say what became possible in that release. Close the background by pointing to the exact operation performed by this lesson. + +Keep the ladder to one or two compact paragraphs and select only concepts the later code uses. A lesson built from several new capabilities should name each release boundary and show why the capabilities work together. Put commit hashes, full configuration lists, and detailed compatibility evidence in the later requirements and references sections, while the opening keeps the version, capability, and causal link readers need before the code. + Use oral English, familiar words, and connected sentences. Write natural Chinese independently from the same facts. Chinese punctuation should be restrained: prefer one or two connected sentences that carry one technical thought over a row of short, period-heavy statements. Prefer causal explanation over inventories. A paragraph should tell the reader what happens, why it happens, and what that enables. Prefer positive, concrete statements throughout the tutorial. Explain what the hook, program, loader, command, or test does and which scope it covers. Rewrite `not`, `do not`, `cannot`, `will not`, `不要`, `不能`, `不会`, `并非`, and `别` whenever the same fact has an accurate positive form, and remove every double negative. Keep at most one compact boundary paragraph near the end, limited to two sentences, instead of distributing failure, limitation, and safety warnings through the article. diff --git a/.agents/skills/bpf-tutorial-writing-style/references/prose-and-bilingual-checklist.md b/.agents/skills/bpf-tutorial-writing-style/references/prose-and-bilingual-checklist.md index 85458b7..393674a 100644 --- a/.agents/skills/bpf-tutorial-writing-style/references/prose-and-bilingual-checklist.md +++ b/.agents/skills/bpf-tutorial-writing-style/references/prose-and-bilingual-checklist.md @@ -18,6 +18,9 @@ Use it as a reader-focused editing guide, not as a reason to add review rounds. - Use oral, direct English with familiar words and short connected sentences. Write as an experienced developer explaining a working tool, not as a paper, merge report, release note, or test log. - Open with a short, truthful story or concrete scenario that the implementation can reproduce. Show an observable symptom, action, packet, event, task, device interaction, or failure, then raise the technical question instead of answering everything in the first paragraph. +- Identify the lesson once as part of the **eBPF Tutorial by Example** series, then give the reader the eBPF background needed to follow this particular program. +- State the first Linux release that contains the enabling feature, describe the capability it added, and connect that capability to the exact hook, callback, iterator, kfunc, `struct_ops`, dynptr, or data path used in the example. Cover every release boundary when the lesson combines multiple new features. +- Keep opening provenance compact. Use the release number and capability in the narrative, then place commit IDs, configuration matrices, and extended compatibility evidence in requirements and references. - Carry the same concrete thread into the mechanism, code, and output sections. The opening should pay off when the reader sees where the event goes and how the result is produced. - Do not fabricate a persona, customer, production incident, deployment, benchmark, urgency, or result. Avoid “In this tutorial, we will explore,” generic eBPF history, product promotion, and an abstract-style contribution list. - Let each section answer the question raised by the previous one. A useful progression is problem, background, whole-system flow, complete code, focused walkthrough, deeper concept, compilation and execution, limits, summary, and references. @@ -117,3 +120,5 @@ The sample is not a factual source. Do not copy `libbpf`, CO-RE, Wasm, API claim ## Final reader check After reading in order, an intermediate or advanced eBPF developer should be able to explain the real problem, the kernel/user-space flow, why the advanced capability is needed, how the core code works, how to build and run it, what the captured output proves, and where the example stops. If the reader remembers only a feature name, a code wall, repeated caveats, or a validation transcript, revise the narrative. + +The opening passes only when the reader can also answer four questions: which tutorial series this lesson belongs to, which general eBPF execution model matters, which Linux release introduced the enabling feature, and what that feature enables in this exact example. diff --git a/.agents/skills/write-bpf-production-tutorial/SKILL.md b/.agents/skills/write-bpf-production-tutorial/SKILL.md index 84183c3..361b247 100644 --- a/.agents/skills/write-bpf-production-tutorial/SKILL.md +++ b/.agents/skills/write-bpf-production-tutorial/SKILL.md @@ -44,6 +44,10 @@ Prepare a complete technical draft before Opus writes. For an existing lesson, t Write down two private working sentences as part of the fact pack: who the reader is, and what they should be able to explain or run at the end. +Prepare an opening background ladder from primary sources. Identify the lesson once as part of the **eBPF Tutorial by Example** series, explain the small amount of general eBPF context needed for this example, then name the enabling feature, the first Linux release that contains it, and the capability that release added. End the ladder by connecting that capability directly to the program the reader will build. When the example combines features introduced in different releases, account for each version boundary and explain why the combination matters. + +Keep this background specific to the lesson. Useful context includes where the verified BPF program runs, how user space loads or attaches it, which hook, iterator, map, kfunc, `struct_ops`, dynptr, or callback carries the work, and how data returns to user space. Support version and capability claims with a primary kernel commit, documentation page, or selftest already included in the fact pack. + Choose an honest scope. A lesson may teach a small operational tool or a focused kernel feature. Do not call a lab demo production-ready, and do not invent a production story that the CLI, output, and tests cannot support. Decide once whether a technical diagram materially improves the lesson. A diagram earns its place when the reader must track at least three dependent state changes, a branch or retry loop, ownership across kernel and user space, or one source that affects several downstream components. A short linear filter or one-step attachment usually reads better as prose. @@ -64,6 +68,8 @@ Give pinned Opus the entry pair, the complete technical draft, the fact pack, im The lesson must start from one short, truthful scene that the implementation can reproduce, then follow one packet, event, task, device interaction, or failure through the whole kernel/user-space path. Use the scene to raise the technical question before naming every mechanism, requirement, counter, and limitation. Never invent a customer, outage, production deployment, performance result, or tool capability to make the opening sound important. +Immediately after the scene, use one or two compact paragraphs for the opening background ladder. The reader should learn that this is one lesson in the **eBPF Tutorial by Example** series, which eBPF execution and attachment model matters here, when the enabling feature entered Linux, what new operation it made possible, and why this example depends on it. Keep detailed commit IDs and compatibility tables in the later requirements or references sections. + Include the complete core source exactly as implemented, then walk through the important mechanisms. Tell Opus explicitly to use repeated local edits in document order and to continue without returning until the last paragraph of the second language is complete. Replacing the complete README in one write is a workflow failure even when the final prose looks acceptable. Follow the selected precedent's component rhythm. Introduce one component, present its complete source inline, and explain its important logic before moving to the next component. Do not hide source in `
` or collect every file into one uninterrupted source dump. The source must remain searchable, copyable, and byte-exact.