84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
---
|
||
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`
|
||
- `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.
|