gitea-pr-review/skills/organized-feedback/SKILL.md

name, description

name	description
organized-feedback	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
  • implement
  • api-change
  • requirement-change
• Necessity: how strongly the change is required.
  • nice-to-have
  • should-fix
  • must-fix

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.