feat(aidd-vcs): make pull requests easier to review and keep current

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,21 +8,26 @@
 
 <!-- One or two sentences: what this changes and the problem it solves. -->
 
+## 📌 Main changes
+
+<!-- Concise bullet points describing the main changes; reuse them in the final summary. -->
+
+-
+
 ## 🛠️ How it works
 
 <!--
 Walk a reviewer through the technical resolution: the approach you took, why
 this way over the alternatives, and anything non-obvious (trade-offs, edge
-cases, follow-ups). This narrative is the point of the PR. The conventional
-title and pre-commit hooks are already enforced by CI, so don't
-re-assert them here. Spend your words on the *how*.
+cases, follow-ups). Keep it brief. Use numbered steps for an ordered process
+and bold the opening words of each step.
 -->
 
 ## 🧪 How to verify
 
-<!-- Concrete steps, commands, or screenshots a reviewer can run to see it work. -->
+<!-- One unchecked checkbox per acceptance criterion, phrased as an observable result; group related conditions or verification steps in nested bullets. -->
 
--
+- [ ]
 
 ## ⚠️ Heads-up
 
@@ -33,9 +38,3 @@ re-assert them here. Spend your words on the *how*.
 <!-- "Closes #N" auto-closes the issue on merge; "Refs #N" links without closing. Delete this whole section if there is no issue. -->
 
 Closes #
-
-## ✅ I certify
-
-<!-- The author ticks these on GitHub before merge. Not for the AI to fill or delete - these are the checks no CI job can make. -->
-
-- [ ] **I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.**

AGENTS.md

@@ -19,6 +19,7 @@
 
 ## Action
 
+- **Framework behavior first:** when a request exposes a framework behavior to change, fix the owning framework component; documentation, tests, and one-off corrections support that change, not replace it.
 - **Surgical changes:** ship the minimum that solves the problem; touch only what the task needs, and leave the code cleaner than you found it.
 - **Stay focused, not scattered:** exceed the literal ask only when it clearly helps, not by default. When you spot an unrelated issue, note it in one line and keep going; detour only if it blocks the task.
 - **Solve your own issues first:** genuinely try to resolve it yourself before escalating to the human.

plugins/aidd-vcs/CATALOG.md

@@ -51,9 +51,10 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [01-collect.md](skills/02-pull-request/actions/01-collect.md) | - |
 | `actions` | [02-draft.md](skills/02-pull-request/actions/02-draft.md) | - |
 | `actions` | [03-create.md](skills/02-pull-request/actions/03-create.md) | - |
+| `actions` | [04-update.md](skills/02-pull-request/actions/04-update.md) | - |
 | `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` |
 | `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` |
-| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use when the user wants to open a pull or merge request. Not for committing, pushing, or merging a branch.` |
+| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request, or update an existing request to reflect its current changes. Use when the user wants to open or update a pull or merge request. Not for committing, pushing, or merging a branch.` |
 
 #### `skills/03-release-tag`
 

plugins/aidd-vcs/skills/01-commit/actions/03-commit.md

@@ -15,11 +15,13 @@ The commit sha, branch, correction count, and push outcome.
 1. **Commit.** Run `git commit` with the message.
 2. **Retry.** On hook rejection, re-stage and retry only a deterministic correction within the current commit's files. Stop and report the hook and error when it needs judgment, leaves scope, makes no progress, or fails three times.
 3. **Push.** When asked, push the branch. Use `--force-with-lease` only when explicitly required, never `--force`.
-4. **Report.** Return the short sha, subject, file count, correction count, and push outcome.
+4. **Update request.** After a successful push, find any open pull or merge request for the branch. If one exists, use `aidd-vcs:02-pull-request` to update its title and body from the full diff. If lookup or update fails, report the failure separately; do not claim the push failed.
+5. **Report.** Return the short sha, subject, file count, correction count, push outcome, and request update outcome when applicable.
 
 ## Test
 
 - `git rev-parse HEAD` returns the new sha and its message matches the project convention.
 - Every correction and re-staged file belongs to the current commit's staged files.
 - An ambiguous, out-of-scope, no-progress, or third failed correction leaves no commit and reports the blocker.
 - When pushed, the remote branch shows the final sha.
+- After a push, an existing request reflects the full diff; no request is created when none exists.

plugins/aidd-vcs/skills/02-pull-request/SKILL.md

@@ -1,28 +1,29 @@
 ---
 name: 02-pull-request
-description: Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use when the user wants to open a pull or merge request. Not for committing, pushing, or merging a branch.
+description: Create a draft pull or merge request, or update an existing request to reflect its current changes. Use when the user wants to open or update a pull or merge request. Not for committing, pushing, or merging a branch.
 argument-hint: base | title
 ---
 
 # Pull Request
 
-Collect the change, draft the request, create it as a draft. `01 → 02 → 03`.
+For a new request, run `01 → 02 → 03`. For an existing request, run `04`.
 
 ## Actions
 
 | #   | Action    | Step                                                        |
 | --- | --------- | ----------------------------------------------------------- |
 | 01  | `collect` | Resolve the base and gather the commits since it             |
 | 02  | `draft`   | Write the title and body from the template                   |
-| 03  | `create`  | Open the draft request, label it, return the URL             |
+| 03  | `create`  | Open the draft request, label it, and summarize it           |
+| 04  | `update`  | Update an existing request within the requested scope       |
 
 Before running an action, read its file in `actions/`, not only the table or assets.
 
 ## Transversal rules
 
 - Follow the project's request practices in `aidd_docs/memory/vcs.md` and the repo's own request template when set, else the bundled `assets/pull_request.md`.
 - Resolve the base from the branch's prefix per the project's convention (`vcs.md`), else the repo's default branch. Never assume `main`.
-- The request is always a draft; the user promotes it.
+- Create new requests as drafts; the user promotes them.
 - Apply only the triage label the branch prefix maps to, when it exists. Labels never change the base.
 - Read the VCS tool from project memory, else infer it from the remote URL.
 - Never commit, push, or branch here.

plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md

@@ -8,20 +8,24 @@ The collected base, commits, and changed files from `01-collect`, and optional t
 
 ## Output
 
-The proposed title, body, and base, approved by the user.
+The title, body, and base ready to create.
 
 ## Process
 
 1. **Template.** Load the request template, the project's own when set, else the bundled [pull_request.md](../assets/pull_request.md).
 2. **Write.** Draft a concise title and a body following the template from the change summary. Link every changed `**/qa/*.webm` under the template's testing or verification section.
+   - Title the outcome. Explain the problem and why it matters without repeating the title.
+   - Reserve the approach for non-obvious details, not a repeat of the main changes.
+   - List the main changes as concise bullets in the relevant section.
+   - Keep the approach brief. Number ordered steps and bold their opening words.
    - Give the fewest concrete verification steps needed for the changed behavior.
-     - State the expected result for each step.
-     - Omit generic CI summaries.
-     - Label scenarios that were not run.
-3. **Confirm.** Show the title, body, and base, apply any overrides, and wait for approval.
+     - Use one unchecked checkbox per observable outcome.
+     - Group related conditions or steps in nested bullets, without extra checkboxes.
+     - Omit generic test commands and CI summaries. Record material verification gaps without implying they passed.
+3. **Proceed.** Apply any supplied overrides and pass the result to `03-create` without an approval round.
 
 ## Test
 
 - The body follows the project's template sections when one exists.
 - Every changed `**/qa/*.webm` is linked in the body.
-- The user approved the title, body, and base before creation.
+- The title, body, and base are ready for creation without another approval.

plugins/aidd-vcs/skills/02-pull-request/actions/03-create.md

@@ -1,23 +1,26 @@
 # 03 - Create
 
-Open the approved draft request and label it.
+Open the draft request and label it.
 
 ## Input
 
-The approved title, body, and base from `02-draft`.
+The title, body, and base from `02-draft`.
 
 ## Output
 
-The draft request's URL and number, with its head and base.
+The draft request, its title, link, and main changes.
 
 ## Process
 
 1. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body.
 2. **Label.** When the head prefix maps to a triage label that exists, apply it; skip silently otherwise.
-3. **Return.** Surface the URL, number, head, and base.
+3. **Return.** Verify the draft, base, title, and body.
+   Return a table with its title, link, and main-change bullets from the body.
+   Include the head and base when useful.
 
 ## Test
 
 - The request exists as a draft with its base equal to the resolved base.
 - A mapped, existing triage label is applied; an absent one is skipped without error.
 - The request is reachable at its URL with the head branch as its source.
+- The response table contains the title, request link, and the same main-change bullets as the body.

plugins/aidd-vcs/skills/02-pull-request/actions/04-update.md

@@ -0,0 +1,23 @@
+# 04 - Update
+
+Update an existing request within the requested scope.
+
+## Input
+
+The request and the requested edit or change in scope.
+
+## Output
+
+The updated request, its title, link, and main changes.
+
+## Process
+
+1. **Read.** Read the request's title and body. For a change in scope, read its full diff against its actual base.
+2. **Write.** Make only the requested edit, or update the title and body for the changed scope. Apply the writing guidance in [02-draft](02-draft.md); preserve author-owned checkboxes and relevant context.
+3. **Update.** Save the changes and return a table with the title, link, and main-change bullets.
+
+## Test
+
+- A targeted edit leaves unrelated content unchanged.
+- A scope update reflects the full diff and preserves author-owned checkboxes.
+- The returned table uses the request's main-change bullets.

plugins/aidd-vcs/skills/02-pull-request/assets/pull_request.md

@@ -15,7 +15,6 @@ argument-hint: N/A
 <!--
 Instructions:
   - At least one of these must be checked.
-  - If you do not know which one to pick, pick "Feature".
   - Base yourself on commit history.
 -->
 
@@ -34,21 +33,23 @@ Instructions:
 - put important details here if necessary, in **bold**.
 -->
 
-## 🚶‍➡️ Behavior
+## 📌 Main changes
 
 <!--
 Instructions:
-- Summarize the behavior changes in a few sentences.
-- Use bullet points.
+- List the main changes as concise bullet points; reuse them in the final summary.
 - Focus on the user experience.
 - Be precise, not vague.
 -->
 
+## 🛠️ How it works
+
+<!-- Keep the approach brief; use numbered steps for an ordered process and bold the opening words of each step. -->
+
 ## 🧪 Steps to test
 
 <!--
 Instructions:
-- Give a list of steps to test the PR, using UI or not.
-- Use checkboxes.
+- Use one unchecked checkbox per acceptance criterion, phrased as an observable result; group related conditions or verification steps in nested bullets.
 - Do not include installation process, focus on functional testing.
 -->