From 84cb0cf2a90215d9e3c42e9e428437632b63443e Mon Sep 17 00:00:00 2001
From: Origami404 <Origami404@foxmail.com>
Date: Thu, 9 Apr 2026 15:28:26 +0800
Subject: [PATCH] feat: build in organized-feedback validation script and
 update docs

---
 AGENTS.md                                     |  2 ++
 skills/organized-feedback/SKILL.md            | 15 +++++++------
 .../validate_organized_feedback_skill.sh      | 22 +++++++++----------
 3 files changed, 21 insertions(+), 18 deletions(-)
 rename {scripts => skills/organized-feedback/scripts}/validate_organized_feedback_skill.sh (88%)

diff --git a/AGENTS.md b/AGENTS.md
index 6eb11f0..c7dfa12 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,3 +3,5 @@ refs/ 里有 gitea API 的 spec
 版本号规则：
 - 当前输出文档版本号固定为 `v1`
 - 如果用户没有明确要求 bump 版本号，禁止修改版本号
+
+默认在工作到合适的时候就自己进行提交即可.
diff --git a/skills/organized-feedback/SKILL.md b/skills/organized-feedback/SKILL.md
index b57ec87..a218616 100644
--- a/skills/organized-feedback/SKILL.md
+++ b/skills/organized-feedback/SKILL.md
@@ -27,14 +27,14 @@ Use this skill to turn a single PR review document into organized feedback.
 ## RFC Subfields
 When a review item is classified as `request-for-change`, annotate it with:
 - `Change-Scope`: how broad the requested change is.
-  - `local`
-  - `implement`
-  - `api-change`
-  - `requirement-change`
+  - `local`: Small, local edits that can usually be finished quickly (for example: rename identifiers, syntax sugar swap, blank-line/order cleanup, light module structure cleanup).
+  - `implement`: Implementation-flow changes that affect business logic behavior (for example: sync points, transaction handling, feature implementation strategy). These typically need tests that demonstrate why the old behavior is insufficient.
+  - `api-change`: API contract changes for widely used internal interfaces or external interfaces. These usually require updating dependent tests and call sites.
+  - `requirement-change`: Requirement-level correction where the solved requirement itself is considered unreasonable and must be re-evaluated.
 - `Necessity`: how strongly the change is required.
-  - `nice-to-have`
-  - `should-fix`
-  - `must-fix`
+  - `nice-to-have`: Optional improvement after higher-priority requests are resolved (for example: vague polish suggestions, minor wrappers/helpers).
+  - `should-fix`: Should be fixed unless there is a defensible reason to defer (for example: proven not triggerable, known low impact, or deferred to next PR with explicit note).
+  - `must-fix`: Mandatory blocker. The PR should not be merged until this is resolved.
 
 ## Processing Flow
 1. Read the PR markdown and identify each review comment or feedback unit.
@@ -81,3 +81,4 @@ Do not write the coverage audit into the final output file.
 - Preserve the user-specified output path.
 - Keep the final file limited to the agreed format.
 - Do not add extra audit notes, scratch work, or intermediate classification logs to the final file.
+- If terminal access is available, run `bash skills/organized-feedback/scripts/validate_organized_feedback_skill.sh` after updating this skill to verify contract and example integrity.
diff --git a/scripts/validate_organized_feedback_skill.sh b/skills/organized-feedback/scripts/validate_organized_feedback_skill.sh
similarity index 88%
rename from scripts/validate_organized_feedback_skill.sh
rename to skills/organized-feedback/scripts/validate_organized_feedback_skill.sh
index 6b5cd75..aa7ee64 100755
--- a/scripts/validate_organized_feedback_skill.sh
+++ b/skills/organized-feedback/scripts/validate_organized_feedback_skill.sh
@@ -2,10 +2,10 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-SKILL_FILE="$REPO_ROOT/skills/organized-feedback/SKILL.md"
-INPUT_EXAMPLE="$REPO_ROOT/skills/organized-feedback/examples/input-pr-review.md"
-OUTPUT_EXAMPLE="$REPO_ROOT/skills/organized-feedback/examples/output-organized-feedback.md"
+SKILL_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SKILL_FILE="$SKILL_ROOT/SKILL.md"
+INPUT_EXAMPLE="$SKILL_ROOT/examples/input-pr-review.md"
+OUTPUT_EXAMPLE="$SKILL_ROOT/examples/output-organized-feedback.md"
 
 if ! command -v rg >/dev/null 2>&1; then
   echo "FAIL: rg is required but was not found in PATH"
@@ -35,14 +35,14 @@ anchored_patterns=(
   '^## Final File Format$'
   '^## Output Discipline$'
   '^- `Change-Scope`: how broad the requested change is\.$'
-  '^  - `local`$'
-  '^  - `implement`$'
-  '^  - `api-change`$'
-  '^  - `requirement-change`$'
+  '^  - `local`: .+$'
+  '^  - `implement`: .+$'
+  '^  - `api-change`: .+$'
+  '^  - `requirement-change`: .+$'
   '^- `Necessity`: how strongly the change is required\.$'
-  '^  - `nice-to-have`$'
-  '^  - `should-fix`$'
-  '^  - `must-fix`$'
+  '^  - `nice-to-have`: .+$'
+  '^  - `should-fix`: .+$'
+  '^  - `must-fix`: .+$'
   '^- `All-Source-Refs`: every source reference found in the interaction$'
   '^- `Covered-Source-Refs`: refs that are represented in the organized output$'
   '^- `Missing-Source-Refs`: refs that are present in the interaction but not yet covered$'