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: 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 # + PR numbering path from the source markdown. R for review, C for comment, r for reply.
• Example mapping: Comment 42.1.1 -> #42.R1.C1, Reply 42.1.1.1 -> #42.R1.C1.r1.

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

• if any unknown（>=1）exists，must 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>".