大模型/agent便于理解的技术交接报告skill前言skill正文前言我发现“技术报告难读往往不是因为术语太多而是因为知识出现顺序错了”。我发现大模型很多时候抓不准问题是因为我们脑子里知道我们整体在解决什么问题而大模型则被一堆细节淹没了它在一堆细节里忘掉了整个任务一开始的那个问题是什么。同时我们光让他去生成技术交接报告但他不知道给哪个读者写去交接他不知道整个报告最重要的要解释清楚的问题是哪一个……所以我补了下面这一段如果他对这些问题感觉很模糊的话就先不断的和我们讨论不断的提问我们明确了这些问题再做Before drafting, establish: - who the reader is; - the one question the handoff must answer; - the exact work in scope; - whether that work is complete, incomplete, failed, or inconclusive; - the evidence available for the important claims. Resolve any ambiguity that would materially change the scope, conclusion, or interpretation of the evidence before writing. Ask the user concise questions when those ambiguities cannot be resolved from authoritative artifacts or prior context, and continue until the material ambiguity is removed. Group related questions when practical rather than asking mechanically one at a time.然后我把这个认识压缩成了一个极简 Codex Skill。skill正文--- name: write-technical-handoff description: Create or revise an engineering handoff or PR-readiness technical report that a competent engineer unfamiliar with the specific investigation can understand and audit. Use for root-cause investigations, bug-fix validation, behavior/performance/correctness analysis, implementation changes that require evidence, and technical reports that may later feed a pull request. Do not use for routine README/API documentation or ordinary status updates. --- # Write Technical Handoff Write for a fresh reviewer who knows the engineering stack but has not followed this investigation. A good report lets that reviewer answer, in order: 1. What is wrong? 2. Where and when does it happen? 3. Why does the proposed mechanism explain the symptom? 4. What changed, and why is that the right fix boundary? 5. What evidence distinguishes causation from coincidence? 6. What exactly is proven, and what is not? 7. What remains before submission or merge? ## First principles ### Order by knowledge dependency Treat the report as a dependency graph of ideas. Introduce each concept before asking the reader to use it in an inference. Do not simplify by deleting important technical qualifiers. Simplify by moving prerequisites earlier and explaining each causal step plainly. ### Preserve the causal chain The report is not a diary of the investigation. Organize around the final engineering argument: trigger - execution path - state/data effect - observable outcome If part of the root cause is inferred rather than directly observed, say so and show the evidence supporting the inference. ### Match claims to measurements Never make a broader claim than the measurement supports. Examples: equivalence at one observed boundary does not prove equivalence of all intermediate behavior; one configuration does not establish behavior for all configurations; a proxy metric does not prove a broader system property. Use the narrowest accurate wording. ### Make causal attribution explicit State what evidence distinguishes the proposed cause from plausible alternatives. When causal attribution relies on a baseline/fix or other comparison, identify what differs between the compared conditions and what is held constant. When useful, classify evidence as: - **Direct:** the evidence isolates the proposed causal factor closely enough to support attribution. - **Supporting:** corroborating evidence from a different revision, partial run, different environment, narrower scope, or other non-identical setup. - **Confounded:** multiple causally relevant variables changed, so the result cannot be attributed to the target change alone. Do not hide confounded evidence that appears to disagree with the conclusion. Explain why it cannot answer the causal question. ### Disclose detail progressively Separate three layers: 1. **Decision layer:** problem, fix, strongest evidence, current readiness. 2. **Causal layer:** concepts, runtime path, mechanism, fix rationale, validation, results, limits. 3. **Audit layer:** frozen revisions, environment, commands, evidence paths, raw provenance. A first-time reader should not need the audit layer to understand the argument. ## Lock the handoff Before drafting, establish: - who the reader is; - the one question the handoff must answer; - the exact work in scope; - whether that work is complete, incomplete, failed, or inconclusive; - the evidence available for the important claims. Resolve any ambiguity that would materially change the scope, conclusion, or interpretation of the evidence before writing. Ask the user concise questions when those ambiguities cannot be resolved from authoritative artifacts or prior context, and continue until the material ambiguity is removed. Group related questions when practical rather than asking mechanically one at a time. Use the narrowest interpretation consistent with the request. Do not expand the scope merely because adjacent work is relevant, and do not block on details that do not affect the engineering argument. ## Workflow Before drafting: 1. Read applicable repo instructions such as AGENTS.md, CONTRIBUTING.md, and the PR template. 2. Inspect the target diff, relevant callers/callees, tests, and evidence. 3. Freeze relevant provenance: base commit, candidate diff/worktree, runtime and dependency versions, configuration and feature flags, inputs/data, external service/model/evaluator revisions when relevant, important parameters, and hardware/topology when relevant. 4. Write a one-sentence causal chain in scratch notes. 5. List only the concepts needed to understand that chain; define them before use. 6. Derive observable predictions from the proposed root cause and map each prediction to a test or measurement. 7. Record uncontrolled variables, alternative explanations, limitations, and remaining gates. Do not invent missing evidence. Mark it as unverified or pending. ## Default report architecture Use this order by default. Merge or omit sections that add no value, but preserve the dependency order. | Section | Purpose | | --- | --- | | **0. One-minute conclusion** | Plain-language problem, mechanism, minimal fix, strongest evidence, readiness state. | | **1. Minimal concepts** | Explain only the few components or terms needed by the later argument. | | **2. Runtime path** | Show what happens in execution order; use a small diagram/table when ordering or scope matters. | | **3. Fix** | Show the net change and explain why this location enforces the intended contract and what boundary/risk remains. | | **4. Verification design** | Map root-cause predictions to tests; state controls and uncontrolled variables. | | **5. Results** | Give exact baseline/fix results with units, denominators, run counts, skips, and relevant frozen context. | | **6. Evidence boundaries** | State what is supported, not supported, inferred, and still untested. | | **7. Change scope** | Separate intended product/test changes from instrumentation, generated artifacts, unrelated fixes, and experiment-only code. | | **8. Readiness** | Separate passed gates, pending gates, authorization boundaries, and stop/re-diagnose conditions. | | **Appendix** | Put environment details, revisions, evidence indexes, repo-relative paths, and raw reproduction material here. | ## Writing rules - Use the users requested language; keep identifiers, commands, revisions, metrics, and file paths exact. - Explain a non-obvious term on first use or immediately before first use. - Prefer concrete subject-verb sentences over stacked nouns and unexplained identifiers. - Keep one main claim per paragraph; put the plain-language claim before implementation detail. - Use one consistent name for each concept. - Put evidence near the claim it supports. - Give important numbers the needed unit, denominator, comparison target, and experimental context. - Distinguish observation from interpretation: “we observed X” is different from “X supports mechanism Y.” - State controlled and uncontrolled variables. Never claim “all variables were identical” when they were not. - Prefer “the experiment did not observe a change in X” over the broader “nothing changed.” - Prefer “supports” or “is consistent with” when the literal mechanism was not directly observed. - Do not narrate dead ends in chronological order unless they change how the final evidence must be interpreted. - Do not use local absolute paths in upstream-facing material; use repo-relative paths or stable links. - Keep large evidence blobs out of the main narrative; summarize and index them. ## Public PR package When the handoff will feed an upstream PR, derive the public PR material from the completed report rather than writing both independently. - Follow the repository PR template. - Explain **why** before **what**. - Describe the net change, not discarded attempts. - Include accuracy/benchmark/profiling/test evidence when the change or template requires it. - Label local results as local; do not present them as official CI. - Keep confounded experiments, local filesystem details, internal evidence indexes, and unrelated investigations outside the public PR unless a limitation is necessary for honest review. - Keep the public PR concise; the technical handoff is the deeper audit document. ## Cold-reader gate Before finishing, reread the report as if you know the codebase but have never seen this bug. Revise if any answer is “no”: - Can the first section explain the problem, fix, strongest evidence, and current state in about a minute? - Is every concept introduced before the first inference that depends on it? - Can the reader reconstruct the runtime/cause chain without immediately opening source code? - Does each strong claim have nearby evidence? - Does each experiment state what was controlled and what was not? - Are conclusions no stronger than the measurements? - Are contradictory or confounded results accounted for rather than hidden? - Are completed work and pending gates clearly separated? - Can the appendix be skipped on a first read? For complex or high-risk reports, use an independent cold-review pass when available: one pass for comprehensibility and one for technical/evidence accuracy. Do not make multi-agent review mandatory for routine reports. ## Output contract Produce a self-contained Markdown report unless the user requests another format. When revising an existing report, preserve correct conclusions, numbers, provenance, and evidence status. Improve order and explanation without silently changing technical claims. If repository state has changed since the evidence was frozen, say so and require re-audit before treating the report as current PR evidence.