Skip to content

huangwb8/skills / skills/beta/bensz-rmd-rules

bensz-rmd-rules

Verified

当需要用 R 做可复现的深度研究分析并交付完整 R Markdown/HTML 报告,或维护这类报告的正式计算与结果时使用。统一用 targets 管理计算,用 renv 锁定环境。只渲染现成 Rmd 用 knit-rmd-html;主要交付可复用的 R API 或包用 bensz-r-developer。

bensz-rmd-rules

目标

围绕一个或多个有价值的科学问题写成完整的论证。每份新分析都交付论文式报告,充分展开分析、科学质控与讨论。正文让非专业读者理解关键概念与发现,也让专业读者查清数学口径、证据强度和结论边界。关键判断应能追到真实数据、公式、代码和重建入口。

流程

输入

明确读者、待做的决定、研究设计、输入和授权范围;盘点现有项目的入口、环境、结果和报告,先读足以判断的资料。区分用户决定、研究方案和探索性选择。信息不足时先推进可检验的部分;只有缺口改变关键口径或授权时才询问。

执行步骤

  1. 从问题下手。 先说明问题为什么值得回答,什么观察或比较会改变现有判断。交代人群、分析单位、对照和效应尺度;区分主要、次要和探索性问题。按研究设计处理分母、缺失、依赖结构和不确定性。证据不足时收窄结论。详见推断与报告。
  2. 用 targets 计算,用 renv 锁定环境。 把正式的清洗、样本定义、统计估计、诊断和稳健性分析交给 targets;声明真实输入、参数、函数和影响结果的环境依赖,按可复用的科学阶段组织。在 renv 锁定的环境内构建,Rmd 读取经核验的结果。新项目用骨架脚本起步,有该框架的既有项目沿用原入口与目录;缺少框架需新交付时,在独立目录接入授权输入。详见计算、环境与重建。
  3. 把每份分析写到足以复核。 交付结构式摘要、引言、数据与方法、按科学问题组织的结果、质量控制与数字核对、讨论和可复现性说明。撰写或改写摘要时,按背景、方法、结果、结论的顺序分成四个有明确标签的部分。先做主要分析,再按风险补上会改变结论的诊断、对照或稳健性分析;把未解决的问题留到讨论交代。计算量可以小,报告仍应讲清完整论证。已有报告的局部修改遵守用户指定范围。详见完整报告的写法。
  4. 先讲为什么,再给代码,最后解释结果。 主要代码块前说明本次数据、方法选择和输出能回答什么;分析与图表代码默认展开,长实现可折叠。用正式脚本的实际代码说明计算;报告执行取数、核对、绘图和排版。在 Rmd 的 Markdown 正文直接撰写结果解读、讨论和摘要结论,结合证据交代量级、不确定性和反例。内联 R 只带入数字、组名和分析状态等事实。难懂的概念可先用标明是假设的例子,再给出与实际算法一致的公式。详见代码与数字和主题与图表规范。新建 HTML 默认用 Liquid Glass,已有报告沿用项目主题。
  5. 用实际交付验收。 从核心主张回查实际数据、分析代码、图表和数字;检查质控写清观察结果、异常的影响与处置,并确认讨论处理了能动摇结论的缺口。打开 HTML 检查公式、代码、图表、窄屏和链接。新建或改动计算流程时,用合成输入或授权子集在隔离副本跑同一正式入口;按变更风险验证复用、失效、恢复和重建。详见测试与交付。

输出

按任务交付 Rmd 和渲染后的 HTML(默认与源文件同目录同名),以及支撑结论的分析代码、锁定环境、需要保留的科学结果和明细。提供可执行的环境恢复、正式重建和适用的单独渲染命令,说明从哪里启动、结果读取什么和哪些场景实际验证过。

报告叙述采用用户指定的语言,未指定时沿用用户提出任务时所用的语言。图和表默认用英文,便于直接复用于英文论文。用户明确指定图表语言时按其要求制作。详见图表语言。

输出管理

raw/ 是受保护的输入;products/ 放需要审阅或复用的计算结果;reports/ 放图、表和补充交付;_targets/ 是可再生的计算存储。仅在需要时创建目录。临时项目副本使用独立的测试目录,草稿、审阅和运行日志进当前任务工作区。

同次交付有多份独立报告时,新报告默认以 01.01.01- 形式加三级阅读编号,同一报告的 Rmd 和 HTML 保持同名,在 README 顶部按编号链接 HTML 并标明先读和选读。先确定主报告,再按科学问题、证据线和展开深度组织其余报告。单报告无需编号;既有文件可先用索引指路。详见多报告的阅读顺序。

校验

对照实际结果逐项验算关键结论。核对主要代码前有分析理由,HTML 打开时可直接看到关键代码,正文关键数字与图表一致且可追到正式结果。改动报告计算或引用时,在隔离副本改变一个会影响结果的输入,确认正文和图表一起更新。对复杂项目,报告文字改动应保持原有估计。区分预检、轻量运行、全量运行和真实浏览器审阅;渲染成功或缓存存在不能替代科学与交付验收。

失败与恢复

缺依赖时指出恢复步骤;缺失或已失效的计算结果由正式入口补齐。报告专用入口不能隐式安装、拟合或吞掉错误。若只取得固定汇总,把快照及来源纳入流水线输入,说明验证范围、回到原分析的办法及无法核实的条件;不可估计或未运行的比较注明理由。

约束

公共硬约束

本块由 docs/templates/skill-common-constraints.md 统一维护;每个 SKILL.md 的 ## 约束 必须逐字同步本块,不得在副本中改写公共规则。

  • 任务需要落盘时,使用唯一的 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ 根目录;共享材料放入 shared/,Skill 专属材料放入该 Skill 的 input/、output/、log/。
  • 正式交付物、源代码和正式计划按项目约定保存,不写入任务工作区;未经授权不覆盖、删除、迁移或远程写入。
  • 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要;BAC 只做过程审计,不替代署名、责任或合规判断。
  • 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
  • 文件路径必须规范化并限制在授权项目范围内;外部 URL、子进程和网络访问遵循最小权限,防止路径遍历、SSRF 和命令注入。
  • Skill 版本唯一记录在自身 config.yaml:skill_info.version;公开 API、协议、目录或配置变更同步文档与 CHANGELOG.md。
  • bensz-collect-bugs 是一个 Agent Skill;仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 ~/.bensz-skills/bugs/,当前任务不中断,只有用户明确要求才公开上报,禁止直接修改用户已安装的 Skill 源码。

Skill 专属约束

  • 原始数据、不可再生标注和唯一外部快照保持只读。保护输入、计算状态和正式交付相互独立;测试在隔离副本运行,不能清理正式 store 或用测试开关替换估计算法。
  • Rmd 报告只要展示表格,正文摘要和附录明细都必须由 DT::datatable() 渲染。短表可以关闭搜索、排序和分页。见报告表格规范。
  • 同意展示读数或汇总不等于同意公开个体数据。可交付的 HTML、widget 和附件都需要检查数据授权;分页不能隐藏客户端已经收到的记录。
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall