lightrun-error-remediation-automation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseUsage Tracking Preflight
使用情况跟踪预检
Before any other action in this skill, find every available MCP tool instance named , including provider-prefixed or namespaced instances. Call each instance with to record skill usage; do not stop after the first occurrence. Treat empty responses, unavailable tools, or tracking failures as non-blocking and continue the workflow.
skill_startskillName: "lightrun-error-remediation-automation"在本 skill 执行任何其他操作之前,查找所有名为 的可用 MCP 工具实例,包括带提供商前缀或带命名空间的实例。对每个实例调用 ,以记录 skill 使用情况;不要在找到第一个实例后停止。将空响应、工具不可用或跟踪失败视为非阻塞情况,并继续工作流。
skill_startskillName: "lightrun-error-remediation-automation"Goal
目标
Provide a repeatable runtime debugging workflow that helps QA and engineers investigate incidents to a fix proposal with focused, high-signal runtime evidence.
提供可重复的运行时调试工作流,帮助 QA 和工程师利用聚焦、高信号的运行时证据调查事故,直至形成修复方案。
Scope
范围
- In scope: problem framing, hypothesis ranking, runtime evidence capture and storage, hypothesis elimination, diagnosis confidence, blocker handling, PR-first fix proposal delivery, source-code fallback when PR creation is blocked.
- Out of scope: rollout decisions or postmortem ownership.
- 范围包括:问题界定、假设排序、运行时证据捕获与存储、假设排除、诊断置信度、阻塞项处理、优先通过 PR 交付修复方案,以及在 PR 创建受阻时回退到源代码修改。
- 范围不包括:发布决策或事故复盘负责人安排。
Preconditions
前置条件
- User can access the target service source path and line location.
- Lightrun MCP server is installed and authenticated.
- OAuth authorization for Lightrun MCP is completed before runtime capture.
- A durable state persistence tool or facility is installed/configured when needed and writable.
- 用户可以访问目标服务的源代码路径和行号位置。
- Lightrun MCP server 已安装并完成身份验证。
- 在捕获运行时数据之前,已完成 Lightrun MCP 的 OAuth 授权。
- 在需要时,已安装或配置可写入的持久化状态存储工具或设施。
State persistence tool discovery
状态持久化工具发现
This skill requires saving small investigation state (e.g., problem IDs, hypothesis IDs, runtime action IDs, timestamps, status flags, or cleanup status) to persist between unattended sessions.
Storage Discovery Protocol:
- Identify durable storage: Inspect available MCP tools/resources and agent-provided durable automation memory facilities before scheduling asynchronous runtime actions. Prefer tools or facilities described as "AutomationMemory", "memory", "memories", "knowledge", "notes", "state", "database", "records", "tasks", "issues", "cases", "notebooks", or "documents".
- Priority:
- Highest priority: use a Memories/Memory MCP, Cursor , or an equivalent agent-native durable automation memory when available. Store one durable record per unique problem ID and update it as hypotheses, runtime action IDs, outputs, and cleanup status change.
AutomationMemory - Next priority: use another connected persistent store, such as a database, task tracker, case tracker, notebook, wiki, document store, or repository-native issue/PR metadata exposed through MCP or the host agent.
- Lowest priority: use an MCP-exposed filesystem only when it is clearly a configured remote/shared persistent store. Do not use local filesystem paths through shell tools or filesystem MCPs for investigation state.
- Highest priority: use a Memories/Memory MCP, Cursor
- No local-file fallback: Do not write persistent investigation state to repository files, workspace files, temp directories, agent conversation logs, agent-specific local memory folders, user-home directories, or any ad hoc local . This ban does not apply to an explicitly exposed durable automation memory facility such as Cursor
state.jsonwhen it supports read/update by stable key.AutomationMemory - Requirement: The selected storage must be able to read and update a simple key-value pair or small JSON-like object keyed by a stable problem ID.
- Fail closed: If no approved persistent storage is available and writable, do not create ad hoc files and do not ask for interactive clarification. Stop before scheduling asynchronous runtime actions and return a machine-readable blocker: .
state-storage-unavailable
此 skill 要求保存少量调查状态(例如问题 ID、假设 ID、运行时操作 ID、时间戳、状态标志或清理状态),以便在无人值守会话之间持续保存。
存储发现协议:
- 确定持久化存储: 在调度异步运行时操作之前,检查可用的 MCP 工具、资源以及 Agent 提供的持久化自动化记忆设施。优先选择描述中包含 "AutomationMemory"、"memory"、"memories"、"knowledge"、"notes"、"state"、"database"、"records"、"tasks"、"issues"、"cases"、"notebooks" 或 "documents" 的工具或设施。
- 优先级:
- 最高优先级:使用 Memories/Memory MCP、Cursor 或等效的 Agent 原生持久化自动化记忆。为每个唯一问题 ID 保存一条持久记录,并随着假设、运行时操作 ID、输出和清理状态的变化而更新该记录。
AutomationMemory - 次优先级:使用其他已连接的持久化存储,例如通过 MCP 或宿主 Agent 暴露的数据库、任务跟踪器、案例跟踪器、notebook、wiki、文档存储或仓库原生 issue/PR 元数据。
- 最低优先级:仅当 MCP 暴露的文件系统明确属于已配置的远程或共享持久化存储时,才使用该文件系统。不得通过 shell 工具或文件系统 MCP 将本地文件系统路径用于调查状态。
- 最高优先级:使用 Memories/Memory MCP、Cursor
- 不允许使用本地文件回退: 不得将持久化调查状态写入仓库文件、工作区文件、临时目录、Agent 对话日志、Agent 特定的本地记忆文件夹、用户主目录或任何临时创建的本地 。如果明确暴露的持久化自动化记忆设施(例如支持按稳定键读取和更新的 Cursor
state.json)不适用此项限制。AutomationMemory - 要求: 所选存储必须能够按稳定的问题 ID 读取和更新简单的键值对或小型 JSON 类对象。
- 失败即关闭(fail closed): 如果没有可用且可写入的已批准持久化存储,不得创建临时文件,也不得请求交互式澄清。停止在调度异步运行时操作之前,并返回机器可读的阻塞项:。
state-storage-unavailable
Automation and portability
自动化与可移植性
This skill may run unattended and with different coding agents. Do not rely on agent-specific directories, local files, user-home directories, or interactive prompts for storage, source-selection, or reproduction decisions. Use approved durable persistent storage only: a Memories/Memory MCP, Cursor , an equivalent agent-native durable automation memory, or another connected persistent store. If required input is unavailable, return a machine-readable blocker with an explicit retry condition instead of asking the user.
AutomationMemory此 skill 可能在无人值守环境中运行,并可能搭配不同的编码 Agent。存储、源代码选择或复现决策不得依赖 Agent 特定目录、本地文件、用户主目录或交互式提示。只能使用已批准的持久化存储:Memories/Memory MCP、Cursor 、等效的 Agent 原生持久化自动化记忆或其他已连接的持久化存储。如果所需输入不可用,应返回带有明确重试条件的机器可读阻塞项,而不是询问用户。
AutomationMemoryMCP Tool Discovery
MCP 工具发现
Follow MCP tool discovery. Do not assume fixed tool names or client prefixes.
遵循 MCP 工具发现。不要假定工具名称或客户端前缀是固定的。
MCP Preflight
MCP 预检
Complete source discovery per MCP tool discovery before any runtime evidence capture.
- Pass and fail criteria: see Source discovery (preflight).
- Missing-MCP recovery: see Missing-MCP recovery.
在捕获任何运行时证据之前,按照 MCP 工具发现 完成源代码发现。
- 通过和失败标准:参见源代码发现(预检)。
- MCP 缺失恢复:参见 MCP 缺失恢复。
Resume Criteria
续跑标准
- Resume the investigation after preflight pass criteria are met.
- Runtime evidence tools are activated only after preflight success.
- Re-enumerate exposed Lightrun MCP tools when resuming a later run.
- 满足预检通过标准后恢复调查。
- 仅在预检成功后启用运行时证据工具。
- 续跑后续会话时,重新枚举已公开的 Lightrun MCP 工具。
Runtime Tool Selection Strategy
运行时工具选择策略
- At run start, inspect currently exposed Lightrun runtime tools and their descriptions before selecting an evidence path.
- For evidence collection, explore available Lightrun MCP tools and their descriptions, then select the best-fit async tool for each hypothesis signal.
- Record the selected tool identifier exactly as exposed by MCP.
- Prefer the smallest useful set of tools for each investigation step.
- 在运行开始时,检查当前公开的 Lightrun 运行时工具及其说明,然后再选择证据获取路径。
- 收集证据时,先探索可用的 Lightrun MCP 工具及其说明,然后为每个假设信号选择最匹配的异步工具。
- 按 MCP 公开的准确形式记录所选工具标识符。
- 对于每个调查步骤,优先使用能够完成任务的最小工具集合。
Source Selection Confidence
源代码选择置信度
- Apply Source selection guidance.
- Choose the most appropriate option automatically when confidence remains low but a defensible target exists; if no defensible target can be selected without guessing, return with an explicit retry condition.
runtime-source-ambiguous
- 应用源代码选择指南。
- 如果置信度仍然较低但存在合理的目标,应自动选择最合适的选项;如果无法在不猜测的情况下选出合理目标,则返回 ,并附上明确的重试条件。
runtime-source-ambiguous
Investigation Principles
调查原则
- Start with hypotheses first, then choose tools.
- Capture evidence that can confirm or falsify a specific hypothesis.
- Collect runtime evidence whenever feasible, even when a bug cause appears obvious.
- Treat scheduled Lightrun runtime actions as evidence gates, not as optional supporting data.
- Do not make a final diagnosis, open a PR, implement a fallback fix, or cancel a still-relevant action until its required results have been retrieved or the action has produced a definitive falsifying outcome.
- Treat terminal no-hit, timeout, failed, cancelled, or error action states without usable results as blockers or reproduction-required handoffs, not as permission to proceed to fix delivery.
- Do not block the active session waiting for a reproduction that may take a long time; check action status once per investigation run, then either retrieve available results or hand off the active reproduction requirement.
- Prefer eliminating wrong hypotheses quickly over collecting broad low-signal data.
- Choose the final diagnosis statement only after all hypotheses are ruled out with runtime evidence.
- Explain the bug mechanism with concrete runtime-to-code traceability.
- End with a concrete fix proposal that includes validation checks.
- 先提出假设,再选择工具。
- 捕获能够确认或证伪具体假设的证据。
- 只要可行,即使缺陷原因看起来很明显,也应收集运行时证据。
- 将已调度的 Lightrun 运行时操作视为证据门控,而非可选的辅助数据。
- 在检索所需结果或操作产生明确证伪结果之前,不得作出最终诊断、开启 PR、实施回退修复或取消仍然相关的操作。
- 将没有可用结果的终态无命中、超时、失败、取消或错误操作状态视为阻塞项或 交接,而不是继续交付修复的许可。
reproduction-required - 不要在活动会话中等待可能耗时较长的复现;每次调查运行仅检查一次操作状态,然后检索可用结果或交接活动复现要求。
- 优先快速排除错误假设,而不是收集广泛但低信号的数据。
- 仅在使用运行时证据排除所有假设后,才选择最终诊断陈述。
- 使用具体的运行时到代码可追溯关系解释缺陷机制。
- 最终给出包含验证检查的具体修复方案。
Tool Call Timing
工具调用时机
- Use tool default collection timing unless the investigation clearly benefits from a different window.
- Avoid adding extra timeout constraints to runtime tool calls during normal investigation flow.
- When timing is adjusted, include a short reason describing the expected diagnostic benefit.
- Before using asynchronous tools, verify state storage is available. If it is unavailable, return and do not schedule runtime actions. When state storage is available, save action IDs, cleanup status, and related investigation state before ending the run.
state-storage-unavailable
- 除非调查明显受益于其他时间窗口,否则使用工具的默认收集时机。
- 在正常调查流程中,避免为运行时工具调用增加额外的超时限制。
- 调整时机时,附上一段简短说明,解释预期获得的诊断收益。
- 使用异步工具前,验证状态存储是否可用。如果不可用,则返回 ,并且不调度运行时操作。状态存储可用时,在结束运行前保存操作 ID、清理状态和相关调查状态。
state-storage-unavailable
Mandatory Runtime Action Result Gate
强制运行时操作结果门控
When a Lightrun runtime action is created for a hypothesis, the investigation MUST verify whether the expected result is available before moving to diagnosis or fix delivery. Verification is a single status or result check per investigation run, not an open-ended polling loop.
- Immediately check the action status or result once after creation, and once when resuming a known problem with a persisted action.
- Use the status/result tool that matches the created action type exactly as exposed by MCP. For example, use snapshot status and value/call-stack getters for snapshots, metric result/status tools for metrics, and duration/timing result/status tools for duration actions when those tools are available.
- Do not repeatedly poll, sleep, or wait in the active session for an action that has no usable result yet.
- If the single check reports captured values, call stacks, metric samples, duration measurements, counters, or other expected action output, retrieve and persist that output before taking any other diagnostic conclusion step.
- If status remains pending or running with no usable result, return with exact trigger instructions, persist the active action, and leave the action active when it is still needed; do not open a PR, implement a local fix, cancel the action, or issue a final diagnosis.
reproduction-required - If the action reaches a terminal no-hit, timeout, failed, canceled, or error state without usable results, record that result, apply the action error mitigation rules, and return a blocker or ; do not open a PR, implement a local fix, or issue a final diagnosis unless the terminal action result itself definitively falsifies the hypothesis.
reproduction-required - Do not treat unrelated traces, logs, stack traces, static code inspection, or outputs from different actions as a substitute for retrieving the created action's expected results.
- Do not cancel an action created for the active leading hypothesis merely because a likely fix is clear.
为某个假设创建 Lightrun 运行时操作后,调查必须在进入诊断或修复交付之前验证预期结果是否可用。验证是在每次调查运行中执行一次状态或结果检查,而不是进行无限轮询。
- 创建操作后立即检查一次状态或结果;恢复具有已持久化操作的已知问题时,再检查一次。
- 使用与所创建操作类型完全匹配且按 MCP 公开形式提供的状态或结果工具。例如,对于 snapshot,应使用 snapshot 状态工具和值或调用栈获取工具;对于 metric,应使用指标结果或状态工具;对于 duration 操作,应使用持续时间或计时结果及状态工具(如果这些工具可用)。
- 不要在活动会话中反复轮询、休眠或等待尚无可用结果的操作。
- 如果单次检查报告已捕获值、调用栈、指标样本、持续时间测量、计数器或其他预期操作输出,请在作出任何其他诊断结论前检索并持久化该输出。
- 如果状态仍为 pending 或 running 且没有可用结果,则返回 ,附上精确的触发说明,持久化活动操作,并在仍有需要时保持操作处于活动状态;不要开启 PR、实施本地修复、取消操作或给出最终诊断。
reproduction-required - 如果操作进入终态无命中、超时、失败、取消或错误状态且没有可用结果,则记录该结果,应用操作错误缓解规则,并返回阻塞项或 ;除非终态操作结果本身明确证伪了假设,否则不要开启 PR、实施本地修复或给出最终诊断。
reproduction-required - 不要将无关的 traces、日志、堆栈跟踪、静态代码检查或来自其他操作的输出,替代为所创建操作的预期结果。
- 不要仅因为可能的修复已经明确,就取消为当前主要假设创建的活动操作。
Runtime Action Cleanup
运行时操作清理
- Treat every asynchronous Lightrun action created by this skill as owned by the current investigation and persist its action ID, hypothesis ID, purpose, creation time, last known status, and cleanup status.
- Before ending any run, review all actions created by this skill for the active problem and cancel actions that are no longer required.
- Cancel an action when:
- its hypothesis has been ruled out,
- a final diagnosis has been reached and the action is not needed for handoff evidence,
- the action is duplicate, stale, mistargeted, or replaced by a newer action,
- the investigation is blocked before reproduction and the action would otherwise remain active without a clear retry path.
- Do not cancel actions created by another investigation, another user, or an unknown owner.
- Do not cancel active actions that are still required to collect an expected reproduction signal; leave them active only when the handoff explicitly states why they remain required and how to continue.
- Before cancelling, retrieve any newly available output when the action status reports unread or uncollected results.
- Use the most specific available Lightrun MCP cancellation tool for the action type, record the cancellation result in persistent state, and include a cleanup summary in the handoff.
- 将此 skill 创建的每个异步 Lightrun 操作都视为当前调查所有,并持久化其操作 ID、假设 ID、用途、创建时间、最后已知状态和清理状态。
- 结束任何运行前,检查为当前问题由此 skill 创建的所有操作,并取消不再需要的操作。
- 在以下情况下取消操作:
- 对应假设已被排除;
- 已得出最终诊断,且该操作对交接证据不再需要;
- 该操作重复、过期、目标错误或已被更新的操作替代;
- 调查在复现前受阻,且该操作在没有明确重试路径的情况下会继续保持活动状态。
- 不要取消由其他调查、其他用户或未知所有者创建的操作。
- 不要取消仍需收集预期复现信号的活动操作;仅当交接明确说明为何必须保留以及如何继续时,才将其保留。
- 取消前,如果操作状态显示存在未读取或未收集的结果,应先检索任何新可用的输出。
- 使用 MCP 提供且与操作类型最匹配的 Lightrun MCP 取消工具,将取消结果记录到持久化状态中,并在交接中包含清理摘要。
Action Error Mitigation
操作错误缓解
- If a runtime action returns no output, no hits, no samples, no measurements, or a timeout-related failure:
- verify whether a custom timeout/window was set,
- increase the active collection window when the scenario needs more trigger time,
- return with the updated action window and explicit retry condition.
reproduction-required
- Re-check source targeting after timeout/no-hit outcomes:
- confirm selected source target(s) still match the suspected execution path,
- For other action errors, consult the Lightrun troubleshooting guide and apply the most relevant remediation:
- https://docs.lightrun.com/troubleshooting/overview/
- summarize which troubleshooting path was used and why it fits the observed error.
- Log mitigation decisions in the handoff (what changed and why).
- 如果运行时操作没有输出、没有命中、没有样本、没有测量值或出现超时相关失败:
- 验证是否设置了自定义超时或时间窗口;
- 当场景需要更多触发时间时,延长当前收集窗口;
- 返回 ,附上更新后的操作时间窗口和明确的重试条件。
reproduction-required
- 超时或无命中后重新检查源代码目标:
- 确认所选源代码目标仍与疑似执行路径匹配;
- 对于其他操作错误,查阅 Lightrun 故障排除指南并应用最相关的缓解措施:
- https://docs.lightrun.com/troubleshooting/overview/
- 总结采用了哪条故障排除路径,以及它为何适合观察到的错误。
- 在交接中记录缓解决策,包括更改了什么以及为什么更改。
Bug Explanation and Fix Proposal Standard
缺陷解释与修复方案标准
- Explain the bug as a concrete execution path:
- trigger conditions
- key state values observed at runtime
- exact code path or branch that produces the failure
- visible impact for users or system behavior
- Tie each diagnosis claim to runtime evidence and code location.
- Propose a concrete fix at code level:
- file/module to change
- behavioral change to implement
- why this change addresses the observed mechanism
- risk notes and validation checks
- Use clear, specific language and avoid generic filler.
- 将缺陷解释为一条具体执行路径:
- 触发条件;
- 运行时观察到的关键状态值;
- 导致失败的准确代码路径或分支;
- 对用户或系统行为造成的可见影响。
- 将每项诊断主张与运行时证据及代码位置关联。
- 在代码层面提出具体修复:
- 要修改的文件或模块;
- 要实现的行为变更;
- 此变更为何能够解决观察到的机制;
- 风险说明和验证检查。
- 使用清晰、具体的语言,避免泛泛而谈的填充内容。
Fix Proposal Delivery Policy
修复方案交付策略
- Prefer opening a PR with the fix proposal whenever the final diagnosis is conclusive and repository/source-management access makes PR creation possible.
- A final diagnosis is not conclusive while any required runtime action for the active leading hypothesis is still pending, running, or has unread results.
- Treat PR creation as possible when the target repository is identified, source-management tools or MCPs are available and authorized, a branch/commit or equivalent proposal can be created, and the fix can be represented as a patch.
- Before making local source-code edits, check available source-management tools or MCPs for a way to create a PR, pull request, merge request, or repository-native change proposal.
- Do not implement local source-code changes as the primary output when a PR can be opened.
- Implement local source-code changes only as a fallback when PR creation is blocked by missing or unauthorized source-management tools, missing repository/remote information, branch or PR permission failures, or an offline environment.
- When using the local fallback, keep edits limited to source-code files directly required for the fix; do not modify documentation, generated files, build metadata, workflows, or unrelated repository files unless the user explicitly asks.
- Record the delivery mode in the handoff:
- PR mode: PR URL or identifier, branch name, fix summary, and validation checks.
- Local fallback mode: PR blocker reason, modified source-code paths, fix summary, and validation checks.
- 当最终诊断具有结论性且能够访问仓库或源码管理时,优先开启包含修复方案的 PR。
- 只要当前主要假设所需的任何运行时操作仍处于 pending、running 状态或存在未读取结果,最终诊断就不具有结论性。
- 如果目标仓库已确定、源码管理工具或 MCP 可用且已授权、能够创建 branch、commit 或等效 proposal,并且修复可以表示为 patch,则视为可以创建 PR。
- 对本地源代码进行编辑前,检查可用的源码管理工具或 MCP,寻找创建 PR、pull request、merge request 或仓库原生变更建议的方式。
- 当可以开启 PR 时,不要将实施本地源代码变更作为主要输出。
- 仅在以下情况下将本地源代码变更作为回退方案:缺少或未授权源码管理工具、缺少仓库或远程信息、分支或 PR 权限失败,或者处于离线环境。
- 使用本地回退方案时,将编辑范围限制在修复直接需要的源代码文件;除非用户明确要求,否则不要修改文档、生成文件、构建元数据、工作流或无关的仓库文件。
- 在交接中记录交付模式:
- PR 模式:PR URL 或标识符、分支名称、修复摘要和验证检查。
- 本地回退模式:PR 阻塞原因、修改的源代码路径、修复摘要和验证检查。
Quick Use Guide
快速使用指南
Use this skill in the following sequence:
- Define the investigation question in one sentence.
- Verify whether the problem is new or known using the persistent storage.
- If the problem is known according to the persistent storage,
3.1. Read hypothesis and runtime action identifiers from persistent storage.
3.2. Verify related Lightrun action statuses/results using action IDs or result identifiers from persistent storage.
3.3. If any related runtime actions are in progress and still required, check status/results once; retrieve results when available, otherwise return with the action retained. 3.4. If all related Lightrun actions failed and no further hypothesis investigation is possible from them, cancel these actions, quit the known-problem logical branch, and continue as if there were no actions at all; add new actions only after generating a new hypothesis. 3.5. Cancel any related Lightrun actions created by this skill that are no longer required. 3.6. Update hypothesis statuses after verification of signals using action IDs or result identifiers from persistent storage. 3.7. Summarize final diagnosis based on hypothesis statuses. 3.8. Open a PR with the fix proposal when possible; implement a minimal local source-code fallback only if PR creation is blocked. 3.9. Finish the current investigation run and stop the chat immediately
reproduction-required - List top hypotheses and the signal expected for each.
- Run preflight and pick runtime source target.
- Request focused runtime signals with the minimal useful tool set.
- Save the unique problem ID, hypotheses, action IDs or result identifiers, and action cleanup status to the selected persistent state storage.
- For every created runtime action, check status/results once using the mandatory runtime action result gate before diagnosis or fix delivery.
- If an action needs external reproduction and has no usable result yet, return with the active action ID, reproduction steps, and retry condition, then stop.
reproduction-required - Finish the current investigation run only after retrieved runtime action results, blocker, or reproduction-required handoff has been persisted.
Investigation template:
- Question:
- Impact:
- Hypotheses:
- H1:
- Confirms when:
- Weakens when:
- H2:
- Confirms when:
- Weakens when:
- H1:
- Selected runtime target:
- Signals collected:
- Leading diagnosis:
- Confidence:
- Next action:
按以下顺序使用此 skill:
- 用一句话定义调查问题。
- 使用持久化存储验证问题是新问题还是已知问题。
- 如果持久化存储表明这是已知问题:
3.1. 从持久化存储中读取假设 ID 和运行时操作 ID。
3.2. 使用操作 ID 或结果标识符验证相关 Lightrun 操作的状态和结果。
3.3. 如果任何相关运行时操作仍在进行且仍然需要,检查一次状态或结果;如果结果可用则检索,否则返回 并保留该操作。 3.4. 如果所有相关 Lightrun 操作均失败,且无法继续根据这些操作调查假设,则取消这些操作,退出已知问题逻辑分支,并像不存在任何操作一样继续;仅在生成新假设后才添加新操作。 3.5. 取消此 skill 创建且不再需要的任何相关 Lightrun 操作。 3.6. 使用操作 ID 或结果标识符验证信号后,更新假设状态。 3.7. 根据假设状态总结最终诊断。 3.8. 可以时开启包含修复方案的 PR;仅在 PR 创建受阻时实施最小化的本地源代码回退方案。 3.9. 完成当前调查运行并立即停止对话。
reproduction-required - 列出主要假设以及每个假设对应的预期信号。
- 执行预检并选择运行时源代码目标。
- 使用最小有效工具集合请求聚焦的运行时信号。
- 将唯一问题 ID、假设、操作 ID 或结果标识符以及操作清理状态保存到选定的持久化状态存储。
- 对每个创建的运行时操作,按照强制运行时操作结果门控,在诊断或修复交付前检查一次状态或结果。
- 如果操作需要外部复现且尚无可用结果,则返回 ,附上活动操作 ID、复现步骤和重试条件,然后停止。
reproduction-required - 仅在检索到的运行时操作结果、阻塞项或 交接均已持久化后,才完成当前调查运行。
reproduction-required
调查模板:
- 问题:
- 影响:
- 假设:
- H1:
- 确认条件:
- 削弱条件:
- H2:
- 确认条件:
- 削弱条件:
- H1:
- 所选运行时目标:
- 已收集信号:
- 当前主要诊断:
- 置信度:
- 下一步操作:
Flow
流程
- Frame the investigation problem.
- Tools: none
- Success: symptom, impact, expected behavior, and investigation question are explicit.
- Verify whether the problem is new or known using the persistent storage.
- Tools: choose from currently available persistent storage tools/facilities based on their descriptions and fit to the problem's description.
- Success: the problem is verified against the list of known problems in the persistent storage.
- If the problem is known according to the persistent storage,
3.1. Read hypothesis and runtime action identifiers from persistent storage.
- Tools: choose from currently available persistent storage tools/facilities based on their descriptions and fit to the problem's description.
- Success: hypothesis and runtime action identifiers that correspond to the problem description are found in persistent storage. 3.2. Verify related Lightrun action statuses/results using action IDs or result identifiers from persistent storage.
- Tools: choose from currently available Lightrun MCP runtime tools based on their descriptions and fit to the task of getting information about completed actions by action ID or result identifier.
- Success: related Lightrun action statuses are known. 3.3. If any related runtime actions are in progress and still required, check their status/results once according to the mandatory runtime action result gate.
- Tools: choose from currently available Lightrun MCP runtime tools based on their descriptions and fit to checking the action type and retrieving its output.
- Success: runtime action results are retrieved, or a blocker/reproduction-required handoff is produced without fix delivery. 3.4. If all related Lightrun actions failed and no further hypothesis investigation is possible from them, cancel these actions, quit the known-problem logical branch, and continue as if there were no actions at all; add new actions only after generating a new hypothesis.
- Tools: choose from currently available Lightrun MCP runtime tools based on their descriptions and fit to the task of cancelling actions by action ID.
- Success: failed actions are cancelled when cancellation is available, and the investigation returns to new hypothesis generation without treating prior actions as usable evidence. 3.5. Cancel any related Lightrun actions created by this skill that are no longer required.
- Tools: choose from currently available Lightrun MCP runtime tools based on their descriptions and fit to the task of cancelling active actions by action ID.
- Success: unneeded skill-owned actions are canceled or explicitly retained with a current purpose, and cleanup status is saved. 3.6. Update hypothesis statuses after verification of signals using action IDs or result identifiers from persistent storage.
- Tools: choose from currently available Lightrun MCP runtime tools based on their descriptions and fit to the task of getting information about completed actions by action ID or result identifier.
- Success: hypothesis statuses are updated according to the runtime tool results.
3.7. Summarize final diagnosis based on hypothesis statuses. - Tools: none
- Success: final diagnosis is summarized based on hypothesis statuses.
3.8. If the final diagnosis is conclusive.
3.9. Open a PR with the fix proposal when possible.
- Tools: choose from currently available MCPs or CLIs for source code management based on their descriptions.
- Success: PR is created with the fix proposal, and the PR URL or identifier is recorded. 3.10. If PR creation is not possible, implement a minimal local source-code fallback.
- Tools: local source-code editing tools only.
- Success: local edits are limited to source-code files directly required for the fix, and the PR blocker reason is recorded. 3.11. Produce decision-ready handoff.
- Tools: none
- Success: output contract is fully populated with diagnosis quality fields and concrete fix proposal details. 3.12. Finish the current investigation run and stop the chat immediately.
- Tools: none
- Success: The conversation has finished.
- Create a hypothesis matrix.
- Tools: none
- Success: at least 2 plausible hypotheses are listed, each with a planned confirming and falsifying signal.
- Run preflight and select a target source.
- Tools: source-discovery capabilities (see MCP Tool Discovery)
- Success: one or multiple source targets are selected and justified by agent reasoning without interactive clarification, or is returned with an explicit retry condition.
runtime-source-ambiguous
- Map full codepath and choose triggerable evidence points.
- Tools: none
- Success: full assumed bug codepath is explored, and action points are placed on executable lines likely to trigger in reproduction.
- Execute focused evidence steps per hypothesis, saving action IDs or result identifiers to the selected persistent state storage.
- Tools: choose from currently available Lightrun MCP runtime tools based on their descriptions and fit to the active hypothesis.
- Typical tool categories include expression capture, call path capture, execution frequency, duration, and numeric metric sampling.
- Success: each evidence step is mapped to one hypothesis, and every created action has a persisted cleanup status.
- Check every runtime action required by the active hypotheses once.
- Tools: choose from currently available Lightrun MCP runtime tools based on their descriptions and fit to checking each action type and retrieving captured output.
- Success: expected action output is retrieved and persisted, or a blocker/reproduction-required handoff is returned without fix delivery.
- Finish the current investigation run only after the mandatory runtime action result gate has been satisfied by retrieved results, or a blocker/reproduction-required handoff has been persisted.
- Tools: none
- Success: The conversation has finished.
- 界定调查问题。
- 工具:无
- 成功标准:症状、影响、预期行为和调查问题均已明确。
- 使用持久化存储验证问题是新问题还是已知问题。
- 工具:根据当前可用的持久化存储工具或设施的说明及其与问题描述的匹配程度进行选择。
- 成功标准:已根据持久化存储中的已知问题列表验证该问题。
- 如果持久化存储表明这是已知问题:
3.1. 从持久化存储中读取假设 ID 和运行时操作 ID。
- 工具:根据当前可用的持久化存储工具或设施的说明及其与任务描述的匹配程度进行选择。
- 成功标准:已找到与问题描述对应的假设 ID 和运行时操作 ID。 3.2. 使用操作 ID 或结果标识符验证相关 Lightrun 操作的状态和结果。
- 工具:根据当前可用的 Lightrun MCP 运行时工具的说明及其与通过操作 ID 或结果标识符获取已完成操作信息这一任务的匹配程度进行选择。
- 成功标准:相关 Lightrun 操作的状态已明确。 3.3. 如果任何相关运行时操作仍在进行且仍然需要,按照强制运行时操作结果门控检查一次状态或结果。
- 工具:根据当前可用的 Lightrun MCP 运行时工具的说明及其与检查操作类型和检索输出这一任务的匹配程度进行选择。
- 成功标准:已检索运行时操作结果,或者已生成阻塞项或 交接,且未交付修复。 3.4. 如果所有相关 Lightrun 操作均失败,且无法继续根据这些操作调查假设,则取消这些操作,退出已知问题逻辑分支,并像不存在任何操作一样继续;仅在生成新假设后才添加新操作。
reproduction-required - 工具:根据当前可用的 Lightrun MCP 运行时工具的说明及其与通过操作 ID 取消操作这一任务的匹配程度进行选择。
- 成功标准:在取消功能可用时取消失败的操作,并且调查返回到新假设生成阶段,不将这些操作视为可用证据。 3.5. 取消此 skill 创建且不再需要的任何相关 Lightrun 操作。
- 工具:根据当前可用的 Lightrun MCP 运行时工具的说明及其与通过操作 ID 取消活动操作这一任务的匹配程度进行选择。
- 成功标准:不再需要的 skill 所有操作已取消,或已明确保留并记录当前用途,同时已保存清理状态。 3.6. 使用操作 ID 或结果标识符验证信号后,更新假设状态。
- 工具:根据当前可用的 Lightrun MCP 运行时工具的说明及其与通过操作 ID 或结果标识符获取已完成操作信息这一任务的匹配程度进行选择。
- 成功标准:已根据运行时工具结果更新假设状态。 3.7. 根据假设状态总结最终诊断。
- 工具:无
- 成功标准:已根据假设状态总结最终诊断。
3.8. 如果最终诊断具有结论性:
3.9. 可以时开启包含修复方案的 PR。
- 工具:根据说明选择当前可用的源码管理 MCP 或 CLI。
- 成功标准:已创建包含修复方案的 PR,并记录 PR URL 或标识符。 3.10. 如果无法创建 PR,则实施最小化的本地源代码回退方案。
- 工具:仅使用本地源代码编辑工具。
- 成功标准:本地编辑仅限于修复直接需要的源代码文件,并已记录 PR 阻塞原因。 3.11. 生成可直接用于决策的交接。
- 工具:无
- 成功标准:输出契约已完整填入诊断质量字段和具体修复方案详情。 3.12. 完成当前调查运行并立即停止对话。
- 工具:无
- 成功标准:对话已结束。
- 创建假设矩阵。
- 工具:无
- 成功标准:至少列出 2 个合理假设,并为每个假设规划确认信号和证伪信号。
- 执行预检并选择源代码目标。
- 工具:源代码发现能力(参见 MCP 工具发现)
- 成功标准:已通过 Agent 的合理推理选择一个或多个源代码目标并说明理由,且无需交互式澄清;或者返回 并附上明确的重试条件。
runtime-source-ambiguous
- 映射完整代码路径并选择可触发的证据点。
- 工具:无
- 成功标准:已探索完整的假定缺陷代码路径,并将操作点放置在复现时可能触发的可执行行上。
- 按假设执行聚焦的证据步骤,并将操作 ID 或结果标识符保存到选定的持久化状态存储。
- 工具:根据当前可用的 Lightrun MCP 运行时工具的说明及其与当前假设的匹配程度进行选择。
- 典型工具类别包括表达式捕获、调用路径捕获、执行频率、持续时间和数值指标采样。
- 成功标准:每个证据步骤均映射到一个假设,并且每个已创建操作都具有已持久化的清理状态。
- 对当前假设所需的每个运行时操作检查一次。
- 工具:根据当前可用的 Lightrun MCP 运行时工具的说明及其与检查每种操作类型和检索捕获输出这一任务的匹配程度进行选择。
- 成功标准:已检索并持久化预期操作输出,或者已返回阻塞项或 交接且未交付修复。
reproduction-required
- 仅在强制运行时操作结果门控已由检索到的结果满足,或者阻塞项或 交接已持久化后,才完成当前调查运行。
reproduction-required- 工具:无
- 成功标准:对话已结束。
Output Contract
输出契约
- Preflight pass:
- selected source target(s) (+ selector mode(s))
agentPoolName - source-selection reasoning and pagination/filter note (if used)
- next runtime action (first evidence tool and why)
- selected source target(s) (
- Preflight fail:
- blocker category
- exact remediation required
- explicit retry condition
- Runtime blocker:
- blocker reason, including when safe state persistence cannot be selected
state-storage-unavailable - failed Lightrun MCP tool, when applicable
- reason/error class
- mitigation applied (timeout/window update and/or source revalidation)
- troubleshooting reference used (when applicable)
- immediate next action
- blocker reason, including
- Reproduction required:
- active runtime action ID(s), grouped by action type
- selected source target(s)
- exact reproduction instruction
- action time window used
- expected captured output, such as values, call stack, metric sample, counter, or duration
- retry condition
- persisted state record identifier, storage location, or MCP location
- Final handoff:
- selected source target(s) and source-selection note, or when no defensible target was selected
runtime-source-ambiguous - reproduction instruction + action time window used
- investigation question
- hypothesis matrix result (leading, ruled out, inconclusive)
- evidence summary (facts first)
- runtime action cleanup summary (cancelled actions, retained actions, and reasons)
- bug mechanism summary (trigger, path, failure point, impact)
- diagnosis statement with confidence level
- disconfirming evidence considered
- remaining unknowns and why they matter
- concrete code-fix proposal (target files/modules, behavior change, validation plan)
- fix delivery artifact (PR URL or identifier when opened; otherwise PR blocker reason and local source-code paths changed)
- recommended next step
- artifact identifier, storage location, or MCP location + checklist status
- selected source target(s) and source-selection note, or
- 预检通过:
- 所选源代码目标(+ selector mode);
agentPoolName - 源代码选择理由及分页或筛选说明(如使用);
- 下一个运行时操作(首个证据工具及其原因)。
- 所选源代码目标(
- 预检失败:
- 阻塞项类别;
- 所需的确切修复措施;
- 明确的重试条件。
- 运行时阻塞项:
- 阻塞原因,包括无法安全选择状态持久化时的 ;
state-storage-unavailable - 失败的 Lightrun MCP 工具(如适用);
- 原因或错误类别;
- 已采用的缓解措施(超时或时间窗口更新和/或源代码重新验证);
- 使用的故障排除参考(如适用);
- 立即下一步操作。
- 阻塞原因,包括无法安全选择状态持久化时的
- 需要复现:
- 按操作类型分组的活动运行时操作 ID;
- 所选源代码目标;
- 精确的复现说明;
- 使用的操作时间窗口;
- 预期捕获输出,例如值、调用栈、指标样本、计数器或持续时间;
- 重试条件;
- 已持久化状态记录标识符、存储位置或 MCP 位置。
- 最终交接:
- 所选源代码目标及源代码选择说明;如果未选择合理目标,则提供 ;
runtime-source-ambiguous - 复现说明及使用的操作时间窗口;
- 调查问题;
- 假设矩阵结果(主要假设、已排除假设、无法确定项);
- 证据摘要(优先列出事实);
- 运行时操作清理摘要(已取消操作、保留操作及原因);
- 缺陷机制摘要(触发条件、执行路径、失败点、影响);
- 带有置信度等级的诊断陈述;
- 已考虑的反证证据;
- 剩余未知项及其重要性;
- 具体代码修复方案(目标文件或模块、行为变更、验证计划);
- 修复交付产物(已开启时提供 PR URL 或标识符;否则提供 PR 阻塞原因和修改的本地源代码路径);
- 推荐的下一步操作;
- 产物标识符、存储位置或 MCP 位置及检查清单状态。
- 所选源代码目标及源代码选择说明;如果未选择合理目标,则提供
Runtime Quality Checklist
运行时质量检查清单
- Source discovery completed before any runtime evidence tool.
- Discovery followed tool-description usage flow and pagination when needed.
- Preflight produced plus selector required by the first evidence tool.
agentPoolName - For each selected runtime tool, the identifier matches the MCP-exposed name exactly.
- Evidence tool selection references MCP tool descriptions and hypothesis fit.
- Missing-MCP recovery includes MCP install + OAuth authorization + retry.
- Resume criteria explicitly gates evidence tools on preflight success.
- Source selection is attempted by the agent first using explicit fit reasoning.
- Source selection supports one or multiple targets when multi-source coverage improves confidence.
- Investigation starts with explicit hypotheses before tool selection.
- Investigation explores full assumed codepath before placing runtime actions.
- Runtime actions are placed on triggerable executable locations linked to the hypothesis.
- Every created runtime action is checked exactly once per investigation run; results are retrieved when available, otherwise blocker/reproduction-required handoff is produced without fix delivery.
- No PR, local fix, final diagnosis, or cancellation occurs while a required runtime action is still pending/running or has unread results.
- Runtime actions created by this skill are cancelled when no longer required, or explicitly retained with a current purpose.
- Action cleanup status is persisted before the run ends.
- Non-timeout action errors trigger consultation of the Lightrun troubleshooting guide before concluding.
- Evidence collection stays aligned with hypothesis-required tools.
- Runtime evidence is collected whenever feasible, including when the likely cause appears clear.
- Each evidence step explicitly confirms or falsifies at least one hypothesis.
- Output contract includes explicit pass/fail/blocker/handoff states.
- Findings separate direct runtime facts from inferred conclusions.
- Final handoff includes a diagnosis statement, confidence, and ruled-out hypotheses.
- Final handoff explains bug mechanism with concrete runtime-to-code traceability.
- Final handoff includes a concrete code-fix proposal with validation checks.
- A PR with the fix proposal is opened whenever possible.
- Local source-code changes are implemented only as a fallback after recording why PR creation was not possible.
- 在使用任何运行时证据工具前已完成源代码发现。
- 工具发现遵循基于工具说明的使用流程,并在需要时进行分页。
- 预检已生成首个证据工具所需的 和 selector。
agentPoolName - 每个所选运行时工具的标识符与 MCP 公开的名称完全一致。
- 证据工具选择参考了 MCP 工具说明及其与假设的匹配程度。
- MCP 缺失恢复流程包含 MCP 安装、OAuth 授权和重试。
- 续跑标准明确以预检成功作为启用证据工具的门控条件。
- Agent 首先使用明确的匹配理由尝试选择源代码目标。
- 当多源代码覆盖能够提升置信度时,源代码选择支持一个或多个目标。
- 调查在选择工具前从明确假设开始。
- 调查在放置运行时操作前探索完整的假定代码路径。
- 运行时操作放置在与假设关联且可触发的可执行位置。
- 每个已创建的运行时操作在每次调查运行中恰好检查一次;结果可用时予以检索,否则生成阻塞项或 交接且不交付修复。
reproduction-required - 当所需运行时操作仍处于 pending、running 状态或存在未读取结果时,不开启 PR、不实施本地修复、不给出最终诊断,也不取消操作。
- 此 skill 创建的运行时操作在不再需要时会被取消,或者明确保留并记录当前用途。
- 运行结束前持久化操作清理状态。
- 非超时操作错误在得出结论前会查阅 Lightrun 故障排除指南。
- 证据收集始终与假设所需工具保持一致。
- 只要可行就会收集运行时证据,即使可能原因已经显而易见。
- 每个证据步骤都明确确认或证伪至少一个假设。
- 输出契约包含明确的通过、失败、阻塞和交接状态。
- 结论区分直接运行时事实与推断结论。
- 最终交接包括诊断陈述、置信度和已排除的假设。
- 最终交接通过具体的运行时到代码可追溯关系解释缺陷机制。
- 最终交接包含带有验证检查的具体代码修复方案。
- 只要可能,就会开启包含修复方案的 PR。
- 仅在记录 PR 无法创建的原因后,才实施本地源代码变更作为回退方案。