Record Code Review Feedback

Record review findings on AI-generated code that resulted in a fix, analyze why the AI wrote the original code, and derive a rule that prevents the same mistake next time.

User Input

$ARGUMENTS

Consider any context from the user input (PR number, which findings, the review source) before proceeding.

Procedure

Step 1: Read the Rules

Read docs/code-review-feedback/README.md. It defines what to record, the root-cause categories, the template, and the index. Follow it; this skill only describes the workflow.

Step 2: Collect the Findings

Identify the review source:

• GitHub Copilot PR review: determine the PR from the user input or gh pr view --json number -q .number on the current branch, then fetch Copilot's review comments:

  gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate \
    --jq '.[] | select(.user.login == "Copilot") | {id, path, line, html_url, body}'

• Local AI review (/code-review, speckit-review-*, etc.): use the findings reported earlier in the conversation. If they are no longer available (e.g. after /clear or in a new session), ask the user for them instead of reconstructing them.

For each finding, check whether it led to a code change (git diff, git log -p on the affected files, or the conversation). Keep only adopted findings. Skip typo-only and formatting-only fixes.

If nothing remains, stop and tell the user there is nothing to record.

Group the remaining findings by root cause: one entry per root cause.

Step 3: Check Existing Entries

Scan the index in the README and open entries with the same category or touching the same files/area. If an existing entry describes the same pattern, list it under Related.

Step 4: Analyze the Root Cause

Answer concretely:

• What did the AI base the original code on (a nearby pattern, the spec, a guess, a generic idiom)?
• What should it have checked — name the AGENTS.md rule, constitution principle, ADR, existing helper, or Redmine API?
• Why did it not do so (rule not documented, rule documented but not consulted, edge case not considered, tests did not cover it)?

Pick the category from the README table. Use other only with an explanation.

Step 5: Write the Prevention Rule

Write a rule that is concrete and checkable at code-generation time (e.g. "Tools that take a project ID must return the same error for missing and invisible projects" — not "check permissions carefully"). Set Promoted to to Not yet unless the rule is actually added to a durable place.

Step 6: Create the Entry

1. Find the highest existing number in docs/code-review-feedback/ and add one (start at 001).
2. Create docs/code-review-feedback/NNN-short-title.md from the template, in English, with today's date. Include the review comment URL and the fix commit hash when available.
3. Append a row to the README index: | [CRF-NNN](./NNN-short-title.md) | Title | category | source | Not yet |.

Never edit or delete existing entries, except for updating the Promoted to field in Step 7.

Step 7: Propose Promotion When It Recurs

If the new entry has two or more Related entries (the pattern has occurred at least three times), propose to the user where the prevention rule should be promoted (AGENTS.md, the constitution, an ADR, a skill). A pattern that has occurred only twice is not proposed: promoting at two occurrences fills the durable files with rules. The proposal states:

1. The destination: the file and the section the rule goes into.
2. The exact text to add.
3. What the rule requires, explained in the user's language, one item per requirement in the text: what to do, and when it applies.

The proposal is about the rule itself. Do not retell the findings, the entries, or the reasons for promoting it unless the user asks. Do not change those files without the user's approval. After the approved rule is added, update the entry's Promoted to field and the matching index cell to name the destination.

Propose promotion only for a rule that applies across features and areas of the codebase. Do not propose a rule tied to one feature, one component, or one kind of output (for example, only PDF export or only one screen), even when it has recurred: every promoted rule is loaded into every session's context, so a narrow rule costs context in all the sessions where it does not apply. Leave such a rule in the log entry with Promoted to set to Not yet, and do not mention promotion in the report.

Step 8: Report

Tell the user the created files, categories, prevention rules, and any promotion proposal. Do not commit.

Notes

• Write entries in English regardless of the conversation language.
• Keep code excerpts short (the relevant lines only).
• If gh fails (not authenticated, API error), report the error to the user instead of guessing the review content.