From d6c4ea44b19cf18a4b4899fd9e407e12c6fd8742 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 2 Nov 2026 02:20:34 +0000 Subject: [PATCH 1/5] feat(aidd-dev): answer pull request review comments from the review skill Answer each review comment in one line, resolve the settled threads, ask the user's calls in their own thread, and propose the feedback worth keeping as learnings. --- docs/CATALOG.md | 2 +- plugins/aidd-dev/CATALOG.md | 5 ++- plugins/aidd-dev/skills/05-review/SKILL.md | 8 +++- .../05-review/actions/06-answer-comments.md | 39 +++++++++++++++++++ .../05-review/actions/07-propose-learnings.md | 25 ++++++++++++ .../assets/comments-summary-template.md | 17 ++++++++ 6 files changed, 92 insertions(+), 4 deletions(-) create mode 100644 plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md create mode 100644 plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md create mode 100644 plugins/aidd-dev/skills/05-review/assets/comments-summary-template.md diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 80102c8dd..fd5cac245 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -55,7 +55,7 @@ Code transformation: plan, implement, assert, audit, review, test, refactor, deb | `02-implement` | Execute a plan phase by phase until 100% complete | `01-implement` | | `03-assert` | Assert the work against the project's coding assertions | `01-assert` | | `04-audit` | Read-only codebase audit across quality pillars | `01-code-quality`, `02-architecture`, `03-security`, `04-dependencies`, `05-performance`, `06-tests`, `07-ui` | -| `05-review` | Read-only review of a diff - code quality and feature behavior | `01-review-code`, `02-review-functional` | +| `05-review` | Read-only review of a diff, or answers to a pull request's review comments | `01-prepare`, `02-review-code`, `03-review-functional`, `04-review-relevancy`, `05-finalize`, `06-answer-comments`, `07-propose-learnings` | | `06-test` | Write and iterate developer-side tests, validate journeys in the browser during implementation - not independent acceptance QA or reviewer evidence | `01-test`, `02-test-journey` | | `07-refactor` | Improve code without changing behavior across four axes | `01-performance`, `02-security`, `03-cleanup`, `04-architecture` | | `08-debug` | Reproduce and fix bugs with a test-driven workflow | `01-reproduce`, `02-debug`, `03-reflect-issue` | diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index dd07f4af3..46a4d3575 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -86,10 +86,13 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-review-functional.md](skills/05-review/actions/03-review-functional.md) | - | | `actions` | [04-review-relevancy.md](skills/05-review/actions/04-review-relevancy.md) | - | | `actions` | [05-finalize.md](skills/05-review/actions/05-finalize.md) | - | +| `actions` | [06-answer-comments.md](skills/05-review/actions/06-answer-comments.md) | - | +| `actions` | [07-propose-learnings.md](skills/05-review/actions/07-propose-learnings.md) | - | +| `assets` | [comments-summary-template.md](skills/05-review/assets/comments-summary-template.md) | - | | `assets` | [review-template.md](skills/05-review/assets/review-template.md) | - | | `references` | [report-contract.md](skills/05-review/references/report-contract.md) | - | | `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Reviews a change or a diff and says whether it is ready to ship, naming every problem with its fix. Use when the user wants a change checked before it ships. Not for fixing what the review finds, and not for auditing a whole codebase.` | +| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Reviews a diff and says whether it is ready to ship, or answers a pull request's review comments. Use when the user wants a change checked before it ships, or its review comments answered. Not for fixing what the review finds.` | #### `skills/06-test` diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 746ab25e0..c75900785 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,7 +1,7 @@ --- name: 05-review -description: Reviews a change or a diff and says whether it is ready to ship, naming every problem with its fix. Use when the user wants a change checked before it ships. Not for fixing what the review finds, and not for auditing a whole codebase. -argument-hint: diff | plan +description: Reviews a diff and says whether it is ready to ship, or answers a pull request's review comments. Use when the user wants a change checked before it ships, or its review comments answered. Not for fixing what the review finds. +argument-hint: diff | plan | pull request --- # Review @@ -16,6 +16,8 @@ flowchart LR finalize --> blocked([blocked]) changes -.->|a later run| all blocked -.->|a later run| all + pr([pull request comments]) --> answer-comments --> propose-learnings --> summary([summary posted]) + summary -.->|the user answers in a thread| pr ``` ## Actions @@ -29,6 +31,8 @@ Run the flow above, reading only the next action file. | review-functional | trace the diff against the plan's criteria | | review-relevancy | judge whether the change belongs | | finalize | judge the round and check its shape | +| answer-comments | reply to each open comment in one line, resolve the settled ones | +| propose-learnings | propose the feedback worth keeping, and post the summary | ## Transversal rules diff --git a/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md b/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md new file mode 100644 index 000000000..0f3fb7b99 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md @@ -0,0 +1,39 @@ +# 06 - Answer Comments + +Reply to each open review comment on a pull request, and resolve the ones settled. + +## Input + +The pull request, and the commits pushed since its comments. + +## Output + +Each open thread replied to, the settled ones resolved, and the comments left to the user or to a fix. + +## Process + +1. **Collect.** Read the open review threads with `gh api graphql`. + - Skip a thread whose last comment ends `Answer here.` or `To fix.`: it still waits on the user, whatever account posted it. +2. **Sort.** Give each comment one kind: + - `done`: a change it asked for is in a commit pushed after it. + - `answer`: a question the code, docs, tests or history answer. + - `user-call`: a choice only the user can settle (intent, trade-off, scope, taste). Between `answer` and `user-call`, pick `user-call`: a guessed answer reads as decided. + - `to-fix`: a change asked for and not made yet. + - A user's reply in a `user-call` thread settles it: sort that thread again with the decision as its answer. +3. **Reply.** In the thread, one or two lines, never quoting the comment back, with `gh api -X POST repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`: + - `done`: what changed and the short commit sha. + - `answer`: the answer and the file or commit it rests on; for a settled `user-call`, `Decision: .` + - `user-call`: the question in one sentence and its options, ending `Answer here.` + - `to-fix`: what the change is, ending `To fix.` +4. **Resolve.** Resolve `done` and `answer` threads with the `resolveReviewThread` mutation. Leave `user-call` and `to-fix` open. +5. **Hand over.** Name the `user-call` and `to-fix` comments with their thread links. + +## Test + +| Case | Pass | +| --- | --- | +| A rename asked, then pushed | a one-line reply naming the sha, the thread resolved | +| "Keep both commands or one?" | the question and its options in the thread, ending `Answer here.`, the thread open | +| The user answered "keep both" in that thread, from the account the run posts with | the thread is read, `Decision: keep both.` replied, the thread resolved | +| A thread still ending `Answer here.` | skipped, no second reply | +| A change asked and not pushed | `To fix.` replied, the thread open, the comment handed over | diff --git a/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md b/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md new file mode 100644 index 000000000..fbd474356 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md @@ -0,0 +1,25 @@ +# 07 - Propose Learnings + +Propose the feedback that should outlive the pull request, and post the summary. + +## Input + +The comments answered and settled, and the ones handed over. + +## Output + +One summary comment on the pull request, shaped by [comments-summary-template.md](../assets/comments-summary-template.md). No rule, memory or skill written. + +## Process + +1. **Keep.** Keep a comment only when it holds beyond this diff: a preference stated as a general one ("docs too long"), the same remark on several files, or a decision another change would face again. Drop one-off changes. +2. **Check.** When a project rule or memory already says it, name that rule as not followed instead of proposing it again. +3. **Post.** Fill `comments-summary-template.md` and post it with `gh pr comment`. + +## Test + +| Case | Pass | +| --- | --- | +| "Too long, nobody reads this" on two docs, and one rename | one learning on doc length linking both threads, none for the rename | +| A rule already asking for short docs | named as not followed, no new learning | +| No `user-call` left | the summary has no FAQ section | diff --git a/plugins/aidd-dev/skills/05-review/assets/comments-summary-template.md b/plugins/aidd-dev/skills/05-review/assets/comments-summary-template.md new file mode 100644 index 000000000..41d2cc7b2 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/assets/comments-summary-template.md @@ -0,0 +1,17 @@ +## Review comments + +Done: {{n}} ({{short shas}}). Answered: {{n}}. + +### FAQ: your call + +1. **{{question}}** ([thread]({{url}})): {{option a}} / {{option b}} + +### To fix + +- {{change}} ([thread]({{url}})) + +### Learnings to keep + +- {{lesson}} ([thread]({{url}})): rule, memory or skill, to record with the skill that captures project learnings once you approve + + From b309633c95188fb3e4d6e3c4426540e5f524076f Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 2 Nov 2026 03:35:05 +0000 Subject: [PATCH 2/5] fix(aidd-dev): reread a todo thread once its change is pushed, and keep one review summary --- .../05-review/actions/06-answer-comments.md | 15 ++++++++------- .../05-review/actions/07-propose-learnings.md | 5 +++-- .../05-review/assets/comments-summary-template.md | 4 ++-- 3 files changed, 13 insertions(+), 11 deletions(-) diff --git a/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md b/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md index 0f3fb7b99..0d0523ad2 100644 --- a/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md +++ b/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md @@ -13,20 +13,20 @@ Each open thread replied to, the settled ones resolved, and the comments left to ## Process 1. **Collect.** Read the open review threads with `gh api graphql`. - - Skip a thread whose last comment ends `Answer here.` or `To fix.`: it still waits on the user, whatever account posted it. + - Skip a thread whose last comment ends `Answer here.`, or ends `To do.` with no commit pushed since: it still waits, whatever account posted it. 2. **Sort.** Give each comment one kind: - `done`: a change it asked for is in a commit pushed after it. - `answer`: a question the code, docs, tests or history answer. - `user-call`: a choice only the user can settle (intent, trade-off, scope, taste). Between `answer` and `user-call`, pick `user-call`: a guessed answer reads as decided. - - `to-fix`: a change asked for and not made yet. + - `todo`: a change asked for and not made yet. - A user's reply in a `user-call` thread settles it: sort that thread again with the decision as its answer. -3. **Reply.** In the thread, one or two lines, never quoting the comment back, with `gh api -X POST repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`: +3. **Reply.** In the thread, one or two lines in the comment's language, never quoting the comment back, with `gh api -X POST repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`. Keep the endings below verbatim: a later run reads them. - `done`: what changed and the short commit sha. - `answer`: the answer and the file or commit it rests on; for a settled `user-call`, `Decision: .` - `user-call`: the question in one sentence and its options, ending `Answer here.` - - `to-fix`: what the change is, ending `To fix.` -4. **Resolve.** Resolve `done` and `answer` threads with the `resolveReviewThread` mutation. Leave `user-call` and `to-fix` open. -5. **Hand over.** Name the `user-call` and `to-fix` comments with their thread links. + - `todo`: what the change is, ending `To do.` +4. **Resolve.** Resolve `done` and `answer` threads with the `resolveReviewThread` mutation. Leave `user-call` and `todo` open. +5. **Hand over.** Name the `user-call` and `todo` comments with their thread links. ## Test @@ -36,4 +36,5 @@ Each open thread replied to, the settled ones resolved, and the comments left to | "Keep both commands or one?" | the question and its options in the thread, ending `Answer here.`, the thread open | | The user answered "keep both" in that thread, from the account the run posts with | the thread is read, `Decision: keep both.` replied, the thread resolved | | A thread still ending `Answer here.` | skipped, no second reply | -| A change asked and not pushed | `To fix.` replied, the thread open, the comment handed over | +| A change asked and not pushed | `To do.` replied, the thread open, the comment handed over | +| A thread ending `To do.`, then the change pushed | read again, the sha replied, the thread resolved | diff --git a/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md b/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md index fbd474356..46b4a4ff9 100644 --- a/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md +++ b/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md @@ -8,13 +8,13 @@ The comments answered and settled, and the ones handed over. ## Output -One summary comment on the pull request, shaped by [comments-summary-template.md](../assets/comments-summary-template.md). No rule, memory or skill written. +One summary comment on the pull request, kept up to date across runs, shaped by [comments-summary-template.md](../assets/comments-summary-template.md). No rule, memory or skill written. ## Process 1. **Keep.** Keep a comment only when it holds beyond this diff: a preference stated as a general one ("docs too long"), the same remark on several files, or a decision another change would face again. Drop one-off changes. 2. **Check.** When a project rule or memory already says it, name that rule as not followed instead of proposing it again. -3. **Post.** Fill `comments-summary-template.md` and post it with `gh pr comment`. +3. **Post.** Fill `comments-summary-template.md`. Post it with `gh pr comment` on the first run; on a later one, edit the comment opening with `## Review comments` with `gh api -X PATCH repos/{owner}/{repo}/issues/comments/{id}`. ## Test @@ -23,3 +23,4 @@ One summary comment on the pull request, shaped by [comments-summary-template.md | "Too long, nobody reads this" on two docs, and one rename | one learning on doc length linking both threads, none for the rename | | A rule already asking for short docs | named as not followed, no new learning | | No `user-call` left | the summary has no FAQ section | +| A second run | the first summary edited, no second one posted | diff --git a/plugins/aidd-dev/skills/05-review/assets/comments-summary-template.md b/plugins/aidd-dev/skills/05-review/assets/comments-summary-template.md index 41d2cc7b2..1fdc381a7 100644 --- a/plugins/aidd-dev/skills/05-review/assets/comments-summary-template.md +++ b/plugins/aidd-dev/skills/05-review/assets/comments-summary-template.md @@ -1,12 +1,12 @@ ## Review comments -Done: {{n}} ({{short shas}}). Answered: {{n}}. +Done: {{n}}{{ (short shas), when there are any}}. Answered: {{n}}. ### FAQ: your call 1. **{{question}}** ([thread]({{url}})): {{option a}} / {{option b}} -### To fix +### To do - {{change}} ([thread]({{url}})) From 9edc6a2cbc3c6723d8072dc45d2ec1065684e41c Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 2 Nov 2026 05:45:53 +0000 Subject: [PATCH 3/5] refactor(aidd-dev): keep review comments VCS-agnostic, with their kinds in references --- plugins/aidd-dev/CATALOG.md | 2 ++ plugins/aidd-dev/skills/05-review/SKILL.md | 1 + .../05-review/actions/06-answer-comments.md | 35 ++++--------------- .../05-review/actions/07-propose-learnings.md | 19 +++------- .../05-review/references/comment-kinds.md | 22 ++++++++++++ .../skills/05-review/references/learnings.md | 11 ++++++ ...-a-round-and-scores-the-whole-plan.test.js | 8 +++-- 7 files changed, 53 insertions(+), 45 deletions(-) create mode 100644 plugins/aidd-dev/skills/05-review/references/comment-kinds.md create mode 100644 plugins/aidd-dev/skills/05-review/references/learnings.md diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 46a4d3575..b54350f17 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -90,6 +90,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [07-propose-learnings.md](skills/05-review/actions/07-propose-learnings.md) | - | | `assets` | [comments-summary-template.md](skills/05-review/assets/comments-summary-template.md) | - | | `assets` | [review-template.md](skills/05-review/assets/review-template.md) | - | +| `references` | [comment-kinds.md](skills/05-review/references/comment-kinds.md) | - | +| `references` | [learnings.md](skills/05-review/references/learnings.md) | - | | `references` | [report-contract.md](skills/05-review/references/report-contract.md) | - | | `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | | `-` | [SKILL.md](skills/05-review/SKILL.md) | `Reviews a diff and says whether it is ready to ship, or answers a pull request's review comments. Use when the user wants a change checked before it ships, or its review comments answered. Not for fixing what the review finds.` | diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index c75900785..9af27e8e3 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -38,3 +38,4 @@ Run the flow above, reading only the next action file. - Ask which entry the caller wants when the request does not say. - Review statically: never run the app. +- Reach a pull request through the VCS tool `aidd_docs/memory/vcs.md` names, else the one the remote points to. diff --git a/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md b/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md index 0d0523ad2..3052ef022 100644 --- a/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md +++ b/plugins/aidd-dev/skills/05-review/actions/06-answer-comments.md @@ -1,6 +1,6 @@ # 06 - Answer Comments -Reply to each open review comment on a pull request, and resolve the ones settled. +Reply to each open review comment on a pull request, and resolve the settled ones. ## Input @@ -8,33 +8,12 @@ The pull request, and the commits pushed since its comments. ## Output -Each open thread replied to, the settled ones resolved, and the comments left to the user or to a fix. +Each open thread replied to, resolved or left open per its kind, and the `user-call` and `todo` threads named. ## Process -1. **Collect.** Read the open review threads with `gh api graphql`. - - Skip a thread whose last comment ends `Answer here.`, or ends `To do.` with no commit pushed since: it still waits, whatever account posted it. -2. **Sort.** Give each comment one kind: - - `done`: a change it asked for is in a commit pushed after it. - - `answer`: a question the code, docs, tests or history answer. - - `user-call`: a choice only the user can settle (intent, trade-off, scope, taste). Between `answer` and `user-call`, pick `user-call`: a guessed answer reads as decided. - - `todo`: a change asked for and not made yet. - - A user's reply in a `user-call` thread settles it: sort that thread again with the decision as its answer. -3. **Reply.** In the thread, one or two lines in the comment's language, never quoting the comment back, with `gh api -X POST repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`. Keep the endings below verbatim: a later run reads them. - - `done`: what changed and the short commit sha. - - `answer`: the answer and the file or commit it rests on; for a settled `user-call`, `Decision: .` - - `user-call`: the question in one sentence and its options, ending `Answer here.` - - `todo`: what the change is, ending `To do.` -4. **Resolve.** Resolve `done` and `answer` threads with the `resolveReviewThread` mutation. Leave `user-call` and `todo` open. -5. **Hand over.** Name the `user-call` and `todo` comments with their thread links. - -## Test - -| Case | Pass | -| --- | --- | -| A rename asked, then pushed | a one-line reply naming the sha, the thread resolved | -| "Keep both commands or one?" | the question and its options in the thread, ending `Answer here.`, the thread open | -| The user answered "keep both" in that thread, from the account the run posts with | the thread is read, `Decision: keep both.` replied, the thread resolved | -| A thread still ending `Answer here.` | skipped, no second reply | -| A change asked and not pushed | `To do.` replied, the thread open, the comment handed over | -| A thread ending `To do.`, then the change pushed | read again, the sha replied, the thread resolved | +1. **Collect.** Read the open review threads, skipping those still waiting per [comment-kinds.md](../references/comment-kinds.md). +2. **Sort.** Give each comment one kind per `comment-kinds.md`. +3. **Reply.** Reply in each thread as its kind says. +4. **Resolve.** Resolve or leave open each thread as its kind says. +5. **Hand over.** Name the `user-call` and `todo` threads with their links. diff --git a/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md b/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md index 46b4a4ff9..72acbefef 100644 --- a/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md +++ b/plugins/aidd-dev/skills/05-review/actions/07-propose-learnings.md @@ -4,23 +4,14 @@ Propose the feedback that should outlive the pull request, and post the summary. ## Input -The comments answered and settled, and the ones handed over. +The threads answer-comments replied to, and the ones it handed over. ## Output -One summary comment on the pull request, kept up to date across runs, shaped by [comments-summary-template.md](../assets/comments-summary-template.md). No rule, memory or skill written. +One summary comment on the pull request, shaped by [comments-summary-template.md](../assets/comments-summary-template.md) and kept up to date across runs. No rule, memory or skill written. ## Process -1. **Keep.** Keep a comment only when it holds beyond this diff: a preference stated as a general one ("docs too long"), the same remark on several files, or a decision another change would face again. Drop one-off changes. -2. **Check.** When a project rule or memory already says it, name that rule as not followed instead of proposing it again. -3. **Post.** Fill `comments-summary-template.md`. Post it with `gh pr comment` on the first run; on a later one, edit the comment opening with `## Review comments` with `gh api -X PATCH repos/{owner}/{repo}/issues/comments/{id}`. - -## Test - -| Case | Pass | -| --- | --- | -| "Too long, nobody reads this" on two docs, and one rename | one learning on doc length linking both threads, none for the rename | -| A rule already asking for short docs | named as not followed, no new learning | -| No `user-call` left | the summary has no FAQ section | -| A second run | the first summary edited, no second one posted | +1. **Keep.** Sort the feedback per [learnings.md](../references/learnings.md). +2. **Fill.** Fill `comments-summary-template.md`. +3. **Post.** Post it on the first run; on a later one, edit the comment opening with `## Review comments` instead. diff --git a/plugins/aidd-dev/skills/05-review/references/comment-kinds.md b/plugins/aidd-dev/skills/05-review/references/comment-kinds.md new file mode 100644 index 000000000..c82f2a9a9 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/references/comment-kinds.md @@ -0,0 +1,22 @@ +# Comment kinds + +The kind each review comment gets, and what its thread receives. + +## Kinds + +| Kind | When | Reply | Thread | +| --- | --- | --- | --- | +| `done` | a change it asked for is in a commit pushed after it | what changed, and the short commit sha | resolved | +| `answer` | a question the code, docs, tests or history answer | the answer, and the file or commit it rests on | resolved | +| `user-call` | a choice only the user can settle: intent, trade-off, scope, taste | the question in one sentence and its options, ending `Answer here.` | open | +| `user-call`, answered | the user replied in a `user-call` thread | `Decision:` and the user's choice | resolved | +| `todo` | a change asked for, not pushed yet | the change, ending `To do.` | open | + +## Rules + +| Rule | Why | +| --- | --- | +| Between `answer` and `user-call`, pick `user-call` | a guessed answer reads as decided | +| Reply in one or two lines, in the comment's language, never quoting it back | the thread stays readable | +| Keep `Answer here.` and `To do.` verbatim, in English | a later run reads them to know which threads still wait | +| Skip a thread ending `Answer here.`, or `To do.` with no commit pushed since | it still waits, whatever account posted it | diff --git a/plugins/aidd-dev/skills/05-review/references/learnings.md b/plugins/aidd-dev/skills/05-review/references/learnings.md new file mode 100644 index 000000000..2d6957054 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/references/learnings.md @@ -0,0 +1,11 @@ +# Learnings + +Which review feedback outlives its pull request. + +| Feedback | Becomes | +| --- | --- | +| a preference stated as a general one, such as "docs too long" | a learning | +| the same remark on several files | one learning, linking every thread | +| a decision another change would face again | a learning | +| what a project rule or memory already says | that rule named as not followed, no new learning | +| a one-off change | nothing | diff --git a/scripts/__tests__/a-review-appends-a-round-and-scores-the-whole-plan.test.js b/scripts/__tests__/a-review-appends-a-round-and-scores-the-whole-plan.test.js index 22252f852..27093018c 100644 --- a/scripts/__tests__/a-review-appends-a-round-and-scores-the-whole-plan.test.js +++ b/scripts/__tests__/a-review-appends-a-round-and-scores-the-whole-plan.test.js @@ -322,12 +322,14 @@ describe("a review appends a round and scores the whole plan", () => { } }); - it("every action carries the contract's sections, and its test is a table", () => { + it("every action carries the contract's sections, and a test it keeps is a table", () => { for (const action of fs.readdirSync(path.join(SKILL, "actions"))) { const body = read(path.join("actions", action)); const headings = [...body.matchAll(/^## (.+)$/gmu)].map((match) => match[1]); - assert.deepEqual(headings, ["Input", "Output", "Process", "Test"], action); - assert.match(body.slice(body.indexOf("## Test")), /^\| Case \| Pass \|$/mu, action); + assert.deepEqual(headings.filter((heading) => heading !== "Test"), ["Input", "Output", "Process"], action); + if (headings.includes("Test")) { + assert.match(body.slice(body.indexOf("## Test")), /^\| Case \| Pass \|$/mu, action); + } } }); From bc22e21e11b5f759b63b2c40dbbccd3316b09a5b Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Tue, 3 Nov 2026 09:15:28 +0800 Subject: [PATCH 4/5] fix(aidd-vcs): cover merge requests and replace test tables with rules --- plugins/aidd-vcs/CATALOG.md | 2 +- .../aidd-vcs/skills/06-answer-comments/SKILL.md | 8 ++++---- .../actions/01-answer-comments.md | 16 +++++----------- .../actions/02-propose-learnings.md | 12 ++++-------- .../06-answer-comments/references/learnings.md | 2 +- 5 files changed, 15 insertions(+), 25 deletions(-) diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index b15719b33..136841e0d 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -90,5 +90,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [comments-summary-template.md](skills/06-answer-comments/assets/comments-summary-template.md) | - | | `references` | [comment-kinds.md](skills/06-answer-comments/references/comment-kinds.md) | - | | `references` | [learnings.md](skills/06-answer-comments/references/learnings.md) | - | -| `-` | [SKILL.md](skills/06-answer-comments/SKILL.md) | `Answers pull request review comments, resolves settled threads, and proposes learnings. Use when the user wants review feedback answered or pending decisions summarized. Not for reviewing a diff or fixing code.` | +| `-` | [SKILL.md](skills/06-answer-comments/SKILL.md) | `Answers pull or merge request review comments, resolves settled threads, and proposes learnings. Use when the user wants review feedback answered or pending decisions summarized. Not for reviewing a diff or fixing code.` | diff --git a/plugins/aidd-vcs/skills/06-answer-comments/SKILL.md b/plugins/aidd-vcs/skills/06-answer-comments/SKILL.md index 846f1cc81..3fd0a389b 100644 --- a/plugins/aidd-vcs/skills/06-answer-comments/SKILL.md +++ b/plugins/aidd-vcs/skills/06-answer-comments/SKILL.md @@ -1,15 +1,15 @@ --- name: 06-answer-comments -description: Answers pull request review comments, resolves settled threads, and proposes learnings. Use when the user wants review feedback answered or pending decisions summarized. Not for reviewing a diff or fixing code. -argument-hint: pull request +description: Answers pull or merge request review comments, resolves settled threads, and proposes learnings. Use when the user wants review feedback answered or pending decisions summarized. Not for reviewing a diff or fixing code. +argument-hint: pull request | merge request --- # Answer Comments ```mermaid flowchart LR - pr([pull request]) --> answer-comments --> propose-learnings --> summary([summary updated]) - summary -.->|new reply or pushed commit| pr + request([pull or merge request]) --> answer-comments --> propose-learnings --> summary([summary updated]) + summary -.->|new reply or pushed commit| request ``` ## Actions diff --git a/plugins/aidd-vcs/skills/06-answer-comments/actions/01-answer-comments.md b/plugins/aidd-vcs/skills/06-answer-comments/actions/01-answer-comments.md index 683baa8a2..dd54659e4 100644 --- a/plugins/aidd-vcs/skills/06-answer-comments/actions/01-answer-comments.md +++ b/plugins/aidd-vcs/skills/06-answer-comments/actions/01-answer-comments.md @@ -1,10 +1,10 @@ # 01 - Answer Comments -Reply to each open review comment on a pull request, and resolve the settled ones. +Reply to each open review comment on a pull or merge request, and resolve the settled ones. ## Input -The pull request, and the commits pushed since its comments. +The pull or merge request, and the commits pushed since its comments. ## Output @@ -16,14 +16,8 @@ Each open thread replied to, resolved or left open per its kind, and the `user-c 2. **Sort.** Give each comment one kind per `comment-kinds.md`. 3. **Reply.** Reply in each thread as its kind says. 4. **Resolve.** Resolve or leave open each thread as its kind says. -5. **Hand over.** Name all remaining `user-call` and `todo` threads with their links, including those skipped. +5. **Hand over.** Name all remaining `user-call` and `todo` threads with their links. -## Test +## Rules -| Case | Pass | -| --- | --- | -| A pushed commit addresses a review comment | the reply cites that commit and the thread is resolved | -| A question has an answer in the code or history | the reply cites its evidence and the thread is resolved | -| A choice needs the user's decision | the thread stays open until the user answers | -| A run finds only waiting threads | it adds no duplicate replies and hands over every pending thread | -| A commit is pushed after a pending change request | the thread is assessed again against that commit | +- Include skipped waiting threads in the handover, even when no reply was posted. diff --git a/plugins/aidd-vcs/skills/06-answer-comments/actions/02-propose-learnings.md b/plugins/aidd-vcs/skills/06-answer-comments/actions/02-propose-learnings.md index 0bb67909d..217bf6c86 100644 --- a/plugins/aidd-vcs/skills/06-answer-comments/actions/02-propose-learnings.md +++ b/plugins/aidd-vcs/skills/06-answer-comments/actions/02-propose-learnings.md @@ -1,6 +1,6 @@ # 02 - Propose Learnings -Propose the feedback that should outlive the pull request, and post the summary. +Propose the feedback that should outlive the pull or merge request, and post the summary. ## Input @@ -8,7 +8,7 @@ The threads answer-comments replied to, and the ones it handed over. ## Output -One summary comment on the pull request, shaped by [comments-summary-template.md](../assets/comments-summary-template.md) and kept up to date across runs. No rule, memory or skill written. +One summary comment on the pull or merge request, shaped by [comments-summary-template.md](../assets/comments-summary-template.md) and kept up to date across runs. ## Process @@ -16,10 +16,6 @@ One summary comment on the pull request, shaped by [comments-summary-template.md 2. **Fill.** Fill `comments-summary-template.md`. 3. **Post.** Post it on the first run; on a later one, edit the comment opening with `## Review comments` instead. -## Test +## Rules -| Case | Pass | -| --- | --- | -| The skill runs again on the same request | it updates the existing summary and retains still-pending threads | -| Feedback repeats a project rule | the summary names the existing rule instead of proposing a duplicate | -| Feedback is worth retaining | the summary proposes a learning without writing project knowledge | +- Keep learnings as proposals; write no rule, memory or skill. diff --git a/plugins/aidd-vcs/skills/06-answer-comments/references/learnings.md b/plugins/aidd-vcs/skills/06-answer-comments/references/learnings.md index 2d6957054..1d74487ae 100644 --- a/plugins/aidd-vcs/skills/06-answer-comments/references/learnings.md +++ b/plugins/aidd-vcs/skills/06-answer-comments/references/learnings.md @@ -1,6 +1,6 @@ # Learnings -Which review feedback outlives its pull request. +Which review feedback outlives its pull or merge request. | Feedback | Becomes | | --- | --- | From 1916b5d77e02de09dd80ee9211aadb1b0b1887f2 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Tue, 3 Nov 2026 09:33:31 +0800 Subject: [PATCH 5/5] fix(aidd-vcs): clarify learning handoff and user decisions --- .../skills/06-answer-comments/actions/02-propose-learnings.md | 1 + .../06-answer-comments/assets/comments-summary-template.md | 2 +- .../skills/06-answer-comments/references/comment-kinds.md | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-vcs/skills/06-answer-comments/actions/02-propose-learnings.md b/plugins/aidd-vcs/skills/06-answer-comments/actions/02-propose-learnings.md index 217bf6c86..946ea0a1b 100644 --- a/plugins/aidd-vcs/skills/06-answer-comments/actions/02-propose-learnings.md +++ b/plugins/aidd-vcs/skills/06-answer-comments/actions/02-propose-learnings.md @@ -15,6 +15,7 @@ One summary comment on the pull or merge request, shaped by [comments-summary-te 1. **Keep.** Sort the feedback per [learnings.md](../references/learnings.md). 2. **Fill.** Fill `comments-summary-template.md`. 3. **Post.** Post it on the first run; on a later one, edit the comment opening with `## Review comments` instead. +4. **Offer.** If there are learnings, propose running the skill that captures durable project learnings with this summary as input. ## Rules diff --git a/plugins/aidd-vcs/skills/06-answer-comments/assets/comments-summary-template.md b/plugins/aidd-vcs/skills/06-answer-comments/assets/comments-summary-template.md index 1fdc381a7..4e7cab93a 100644 --- a/plugins/aidd-vcs/skills/06-answer-comments/assets/comments-summary-template.md +++ b/plugins/aidd-vcs/skills/06-answer-comments/assets/comments-summary-template.md @@ -12,6 +12,6 @@ Done: {{n}}{{ (short shas), when there are any}}. Answered: {{n}}. ### Learnings to keep -- {{lesson}} ([thread]({{url}})): rule, memory or skill, to record with the skill that captures project learnings once you approve +- {{lesson}} ([thread]({{url}})) diff --git a/plugins/aidd-vcs/skills/06-answer-comments/references/comment-kinds.md b/plugins/aidd-vcs/skills/06-answer-comments/references/comment-kinds.md index c82f2a9a9..50062e288 100644 --- a/plugins/aidd-vcs/skills/06-answer-comments/references/comment-kinds.md +++ b/plugins/aidd-vcs/skills/06-answer-comments/references/comment-kinds.md @@ -9,7 +9,7 @@ The kind each review comment gets, and what its thread receives. | `done` | a change it asked for is in a commit pushed after it | what changed, and the short commit sha | resolved | | `answer` | a question the code, docs, tests or history answer | the answer, and the file or commit it rests on | resolved | | `user-call` | a choice only the user can settle: intent, trade-off, scope, taste | the question in one sentence and its options, ending `Answer here.` | open | -| `user-call`, answered | the user replied in a `user-call` thread | `Decision:` and the user's choice | resolved | +| `user-call`, answered | the user has stated their decision, even if implementation remains | `Decision:` and the user's choice | resolved | | `todo` | a change asked for, not pushed yet | the change, ending `To do.` | open | ## Rules