84 lines
4.8 KiB
Markdown
84 lines
4.8 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`: 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>"`.
|