From 3c2c530c65908057f87e438a43dff63131382a0e Mon Sep 17 00:00:00 2001 From: Jz0ojiang Date: Mon, 31 Aug 2026 15:46:13 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8E=A5=E5=85=A5=20why-here=20Release=20?= =?UTF-8?q?=E5=90=8C=E6=AD=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/marketplace.json | 7 ++ .dist-sync/sources.json | 5 + .dist-sync/versions.json | 3 +- .gitea/workflows/sync-releases.yml | 1 + README.md | 11 ++ skills/why-here/SKILL.md | 159 +++++++++++++++++++++++++++++ 6 files changed, 185 insertions(+), 1 deletion(-) create mode 100644 skills/why-here/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 83e2bf3..a35fb4d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -26,6 +26,13 @@ "skills": [ "./skills/baimiao-table-ocr" ] + }, + { + "name": "delivery-review", + "description": "Review a change before delivery: keep what the finished result needs, drop what only the making of it needed.", + "skills": [ + "./skills/why-here" + ] } ] } diff --git a/.dist-sync/sources.json b/.dist-sync/sources.json index 3a6a5d6..29654fb 100644 --- a/.dist-sync/sources.json +++ b/.dist-sync/sources.json @@ -24,6 +24,11 @@ "name": "disk-master", "repository": "agent-skills/disk-master-skill", "asset": "disk-master.zip" + }, + { + "name": "why-here", + "repository": "agent-skills/why-here", + "asset": "why-here.zip" } ] } diff --git a/.dist-sync/versions.json b/.dist-sync/versions.json index 4b36026..915ad05 100644 --- a/.dist-sync/versions.json +++ b/.dist-sync/versions.json @@ -3,5 +3,6 @@ "disk-master": "v1", "everything-file-search": "v1", "teach-me": "v2", - "think-twice": "v3.1" + "think-twice": "v3.1", + "why-here": "v1" } diff --git a/.gitea/workflows/sync-releases.yml b/.gitea/workflows/sync-releases.yml index 1e9d0ce..9c53701 100644 --- a/.gitea/workflows/sync-releases.yml +++ b/.gitea/workflows/sync-releases.yml @@ -52,6 +52,7 @@ jobs: "everything-file-search", "teach-me", "think-twice", + "why-here", } output = Path("/tmp/skills-list.txt").read_text(encoding="utf-8") lines = {line.strip(" │└├─") for line in output.splitlines()} diff --git a/README.md b/README.md index cee06ad..1d903c8 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,16 @@ npx skills update `think-twice` 负责把一份文字写得独立、准确；`teach-me` 负责通过来回交流把一件事真正讲懂。两者可以单独安装，也可以一起使用。 +### 交付前审查 + +#### [`why-here`](./skills/why-here/SKILL.md) + +在交付前对改动里每个可疑的部分问同一个问题：它现在为什么还在这里。完成后的结果仍然需要的留下，只因为做的过程走过某条路才存在的删掉，例如回应旧误解的说明、放弃方案留下的分支、迁移完成后仍在的临时字段。 + +它默认只审查和报告。文字按删掉后读者的理解会不会改变判断；代码、接口和数据结构要先查当前调用方、契约、已有数据和外部约束。公开接口、持久化数据和仍在使用的兼容路径需要你明确授权才会动。 + +`think-twice` 负责把文字写得独立可读；`why-here` 负责判断哪些内容还属于完成后的结果，范围同时包括文字和代码。 + ### Windows 工具 #### [`disk-master`](./skills/disk-master/SKILL.md) @@ -79,3 +89,4 @@ npx skills update - “分析一下 `C:` 盘为什么满了，只做只读扫描，并生成 HTML 报告。” - “帮我找出这台 Windows 电脑上所有叫 `settings.json` 的文件。” - “把这张表格截图转成 Markdown 表格。” +- “这次改动中途换过方案，提交前用 `why-here` 看看还有没有只属于旧方案的内容。” diff --git a/skills/why-here/SKILL.md b/skills/why-here/SKILL.md new file mode 100644 index 0000000..82bd6cc --- /dev/null +++ b/skills/why-here/SKILL.md @@ -0,0 +1,159 @@ +--- +name: why-here +description: > + Review a change before delivery after the work involved an abandoned attempt, + corrected misunderstanding, completed transition, or superseded implementation, + or when the user asks what no longer belongs in the finished result. Keep + current requirements and unproven cases unchanged. Do not use for ordinary + prose editing, general refactoring, or a repository-wide simplification review. +--- + +# Why Here + +Review what is about to be delivered by asking of each questionable part: +**Why is this here now?** + +Keep it when the finished result still needs it. Remove it when it exists only +because of an abandoned attempt, an earlier misunderstanding, a completed +transition, or an old implementation that no current requirement preserves. +This is not a general simplification pass and less is not automatically better. + +## Scope + +Start with the current diff, user-named files, and any text or artifact being +delivered with this change. Treat the task as review-only unless the user +explicitly asks to edit, clean up, remove, or otherwise change the artifact. +Loading or naming this skill alone does not grant permission to modify files. Do +not turn the review into repository-wide cleanup. Note an adjacent problem only +when it would materially affect this delivery. + +Preserve unrelated user work. Inspect first; do not assume that an unfamiliar +field, branch, comment, test, or document is unnecessary. + +## Process + +### 1. Establish the finished result + +Derive the required behavior, structure, contract, and documentation from the +user's request, acceptance criteria, owning documentation, current contracts, and +real consumers. Identify any public interface, stored data, external system, or +compatibility promise in scope. When the sources are missing or conflict, mark the +corresponding target as unproven instead of inferring it from the current +implementation. Candidates whose required result is unproven remain **Unproven**; +do not classify them as **Keep**, **Confine**, or **Remove**. + +**Complete when:** the required result and the boundaries that can constrain +cleanup are explicit. + +### 2. Find parts whose reason may have expired + +Inspect the scoped change for parts that appear to exist only because work took +a particular route: + +- explanations, denials, or comments that answer an earlier misunderstanding or + abandoned implementation rather than a likely question or current constraint + raised by the finished result; +- narration of attempts, reversals, or investigation instead of the conclusion + and its evidence; +- temporary fields, states, flags, branches, adapters, or documentation left by + a completed internal transition; +- tests for behavior that was intentionally removed or whose coverage has been + replaced; +- old and new representations both retained after the old one has lost its + purpose. + +Use the counterfactual only to find candidates: if the work had begun from the +finished design, would this part still have been introduced? A “no” is a reason +to investigate, not permission to delete. + +**Complete when:** every candidate has a location and a concrete reason it may +no longer belong. + +### 3. Prove what still earns a place + +For prose and comments, judge from the finished artifact. The reader is the +person who will receive, use, or maintain that artifact after this conversation, +without access to the conversation. Would removing the candidate create a +reasonable misunderstanding or change that reader's current understanding, +decision, or action? Check any source or requirement the statement claims to +preserve. + +For code, interfaces, configuration, tests, and data structures, check current +callers, clients, configuration, stored data, documented contracts, and external +constraints. History may explain why a candidate appeared, but current evidence +decides whether it stays. + +Classify the result: + +- **Keep:** current understanding or action, behavior, a real consumer, a + contract, stored data, or an external constraint still requires it. +- **Confine:** a temporary compatibility need remains, but keeping it at the + conversion, migration, or version boundary would prevent it from spreading + through the maintained model. This classification does not by itself authorize + the move. +- **Remove prose:** removing it changes no intended reader's understanding, + decision, or action, and no current requirement calls for it. +- **Remove structure:** no current behavior or obligation depends on it, and + available validation can show that removal is safe. +- **Unproven:** evidence is insufficient. Keep it unchanged and state what would + settle the question. + +Do not treat an awkward external requirement as residue merely because a clean +redesign would prefer not to have it. + +**Complete when:** no removal rests only on taste, age, or the counterfactual. + +### 4. Clean only within the proven boundary + +If the current request authorizes edits, remove prose and comments when their +absence changes no current understanding, decision, or action. Otherwise, +classify and report them without editing. Keep a reason, constraint, or +invalidation condition that a future maintainer needs and cannot recover from +the artifact itself. Treat safety, security, privacy, recovery, legal, generated, +and tool-read notices as behavior or constraints; remove them only after proving +they no longer apply and checking the system or tool that consumes them. + +If the current request authorizes edits, remove a test only when its protected +behavior was intentionally removed or its purpose is covered elsewhere. Otherwise, +classify and report it without editing. Read the assertions and confirm the +remaining coverage; absence of a runtime caller is not evidence that a test is +obsolete. + +If the current request authorizes edits, remove internal code or structure only +after consumer and contract checks support it and relevant validation is +available. A **Confine** change may be made under that authorization only when it +is internal, preserves supported behavior, and does not affect a public +interface, durable data, wire format, migration history, or a still-used +compatibility path. + +Before changing a public interface, durable data, wire format, migration history, +or still-used compatibility path, present the evidence and proposed finished +state, then obtain explicit authorization. + +**Complete when:** every authorized edit is supported by the classification +above, every review-only candidate remains unchanged, and no unrelated cleanup +entered the diff. + +### 5. Validate the result + +If edits were made, run the focused checks that can detect a changed behavior, +broken consumer, or invalid contract. Repeat relevant searches after removal and +inspect the final diff for newly orphaned code, tests, configuration, or +documentation. For a review-only run, report the evidence checks performed and +which validation would be required before an edit. + +**Complete when:** edited results are supported by concrete checks; review-only +findings name the evidence still required; and every unresolved boundary remains +unchanged and is reported. + +## Delivery + +Report the finished state, material constraints that remain, checks actually +run, and any candidate left unchanged for lack of evidence or authorization. +Do not recreate the discarded path as a removal diary unless the user explicitly +asks for an audit record. + +Finish by accounting for every reviewed candidate: a retained candidate has a +current reason to stay; an unproven candidate remains unchanged with the missing +evidence or authorization named; and a removed candidate has supporting evidence +and validation.