---
name: organized-feedback
description: Organize PR review comments into structured feedback with coverage auditing and unknown-item handling. Use when converting gitea-pr-review Markdown into a user-specified output document.
---

# Organized Feedback

## Overview
Use this skill to turn a single PR review document into organized feedback.

## Inputs
- PR markdown
- output path

## Hard Gates
- Do not write final output until user provides output path.
- Coverage audit must run in interaction.
- Coverage audit content must not be written to final document.
- If unknown count is greater than 3, pause and request user permission.

## Classification Taxonomy
- `question`: a review item that asks for clarification, confirmation, or intent.
- `supplement`: a review item that adds missing context, examples, or supporting detail without changing the requested behavior.
- `request-for-change`: a review item that asks for a code, behavior, or design change.
- `unknown`: a review item that cannot be classified confidently after one reflection pass.

## RFC Subfields
When a review item is classified as `request-for-change`, annotate it with:
- `Change-Scope`: how broad the requested change is.
  - `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`: 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.
2. Classify each unit as `question`, `supplement`, `request-for-change`, or `unknown`.
3. If a unit clearly contains multiple intents, split it into separate items before grouping.
4. If multiple units express the same intent, merge them into one grouped item.
5. For each `request-for-change`, assign `Change-Scope` and `Necessity`.
6. Run an interaction-only coverage audit using `All-Source-Refs`, `Covered-Source-Refs`, and `Missing-Source-Refs`.
7. Re-audit until `Missing-Source-Refs` is empty.
8. Apply the unknown reflection rule once before finalizing any `unknown` item.
9. If the count of `unknown` items is greater than 3, stop and request user permission before proceeding.

## Interaction-Only Coverage Audit
The coverage audit must be performed only against the interaction content, not the final document.

Track these lists explicitly:
- `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

Source reference format rule:
- Use `R` + PR numbering path from the source markdown.
- Example mapping: `Comment 42.1.1` -> `R42.1.1`, `Reply 42.1.1.1` -> `R42.1.1.1`.

Audit rules:
- Compare only against interaction content.
- Re-audit after every grouping pass until `Missing-Source-Refs` is empty.
- Do not treat the final document as an audit source.

## Unknown Handling
- unknown（>=1），必须执行一次反思复判
- Use one reflection pass to decide whether an item can be reclassified into `question`, `supplement`, or `request-for-change`.
- If it remains `unknown`, keep it in the `Unknown Items` section.
- If the number of `unknown` items is greater than 3, request user permission before continuing.

## Final File Format
Write only the organized output content:
- `Organized Feedback`
- optional `Unknown Items`

Do not write the coverage audit into the final output file.

## Output Discipline
- 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, validate generated output with `bash skills/organized-feedback/scripts/validate_organized_feedback_skill.sh --output "<organized-feedback.md>"`.
- For maintainers, run `bash skills/organized-feedback/scripts/validate_organized_feedback_skill.sh --output "skills/organized-feedback/examples/output-organized-feedback.md" --self-check` to validate both output format and bundled skill contract.