git:20260908.d184cd7 to git:20260929.208b428

154 added, 154 removed. Audit A to A.

---

name: create-pull-request

- description: 'Guides developers and agents through creating a pull request: pre-PR validation, branching conventions, template usage, CI checks, review expectations, and post-merge documentation closeout. Use when opening or preparing a PR. Do not use for writing the implementation being merged.'

+ description: 'Opens or updates a pull request on GitHub or Azure DevOps: selects the provider from the git remote, resolves the target branch from evidence, writes the title and description from the host conventions and template, creates or updates the PR through the provider MCP server or CLI, verifies it, and follows CI and review through merge. Use when asked to create, open, submit, or update a PR. Do not use for addressing review comments on an existing PR (use pr-review-fix-comments) or for writing the implementation being merged.'

license: MIT

---

# Create Pull Request

- Use this skill when preparing or creating a pull request in the host repository. It describes the checks and workflow that PR authors must follow. For the mechanical steps of creating the PR via GitHub or the `gh` CLI, consult the `create-pull-request-github` skill.

- ---

- ## 1. Pre-PR checklist

- Before opening a PR, verify all of the following:

- - [ ] **Branch from the correct base.** PRs target `main` (production) or `develop` (integration). Feature and bugfix branches branch from `develop` unless the change is a hotfix targeting `main`. Confirm the parent branch conclusively — consult the `create-pull-request-github` skill.

- - [ ] **All local tests pass.** Run the host test suites. For .NET, `dotnet test -c Release` unless **<csharp-coding-standard>** names a different command. For other stacks, use the matching coding-standard document.

- - [ ] **Code builds clean.** `dotnet build -c Release` completes with no errors (or the host's equivalent).

- - [ ] **Lint and formatting pass.** Markdown files pass `markdownlint-cli2`; C# code follows `.editorconfig` and `dotnet format` conventions; Python follows `ruff` rules in `pyproject.toml`.

- - [ ] **Canonical documentation is updated.** If the change affects a component's public interface, configuration, architecture, runtime, operations, or workflow, the corresponding README and detailed documentation have been updated. See the documentation ontology declared as **<documentation-ontology>** in the root `AGENTS.md` for the required shape.

- - [ ] **Catalog entry is current.** If the change introduces, moves, renames, or materially alters a component, update the catalog at the path declared as **<component-catalog>** in the root `AGENTS.md`.

- - [ ] **Scoped instructions are followed.** Every subtree has its own `AGENTS.md` with additional rules. Read the nearest scoped `AGENTS.md` before changing files in that subtree.

- - [ ] **Clean Architecture is preserved.** Inner layers never depend on outer layers. Contracts contains interfaces only; `Contracts.Models` contains shared DTOs only. Business invariants belong in Domain; Application services belong in `Services`. See the architectural rules declared under **<rules-index>** in the root `AGENTS.md`.

- - [ ] **No secrets or credentials.** The change contains no tokens, connection strings, passwords, `.env` files, customer data, or unsafe deployment commands.

- - [ ] **Dev environment is ready.** If setting up from scratch, consult the `setup-dev-environment` skill which covers all tooling.

- ## 2. Branch naming conventions

- Use descriptive branch names that match the following patterns:

- | Branch type | Pattern | Example |

- |---|---|---|

- | Feature | `feature/<short-description>` | `feature/azure-ai-search-index` |

- | Bug fix | `bugfix/<short-description>` | `bugfix/null-ref-on-empty-result` |

- | Hotfix | `hotfix/<short-description>` | `hotfix/cors-header-regression` |

- | Task/chore | `task/<short-description>` | `task/update-dotnet-10` |

- | With issue ID | `<type>/<issue-number>-<description>` | `feature/42-audit-error-service` |

- When the branch name includes a numeric GitHub issue ID as the first token after the type prefix, the PR description should include `Closes #<id>` to auto-link the issue.

- ## 3. PR title and description standards

- ### Title format

- Use a concise, descriptive title in the imperative mood, matching the branch name's intent:

- ```

- [Component] Brief description of the change

- ```

- Examples:

- - `[API] Add Azure AI Search indexer endpoint`

- - `[Admin Desktop] Fix null reference on empty document list`

- - `[Local Processor] Update docling dependency to v2.4`

- Capitalize the first word of the description. Do not end with a period unless the title contains multiple sentences (rare).

- ### Description body

- Fill out the Pull Request template (`.github/PULL_REQUEST_TEMPLATE.md`) completely. Every section matters — see §4 below for detailed guidance on each field.

- ## 4. Using the PR template

- The repository PR template at `.github/PULL_REQUEST_TEMPLATE.md` is a checklist-driven template. Here is how to fill each section:

- ### Summary

+ Use this skill to open or update a pull request in the host repository, on GitHub or Azure

+ DevOps. This file is provider-neutral: it decides the target branch, title, linked work, and

+ description once, the same way on every provider. Every command, tool name, and template path

+ lives in the provider file selected below.

- State the problem being solved and the outcome. Answer "why" more than "how." Be specific enough that a reviewer unfamiliar with the issue context understands the change's purpose.

+ ## Provider Selection

- **Good:** "The Azure AI Search indexer currently blocks on concurrent indexing requests, causing timeout failures for large documents. This change introduces a background queue with configurable concurrency."

- **Avoid:** "Fixed indexing."

+ Resolve the provider before anything else, in this order:

- ### Type of Change

+ 1. Explicit provider in `$ARGUMENTS` (`github` / `gh` / `azdo` / `ado` / `azure-devops`).

+ 2. Remote URL of the current git repo:

+ - contains `dev.azure.com` or `visualstudio.com` -> Azure DevOps

+ - contains `github.com` -> GitHub

+ 3. Only one of the two provider MCP servers is connected -> that provider.

+ 4. Otherwise ask the user which provider and stop.

- Select exactly one. If more than one applies, pick the most impactful category and note additional categories in the summary.

+ Then read the matching provider file and use only its tools:

- ### Component and boundaries

+ | Provider | Provider file |

+ |---|---|

+ | Azure DevOps | [providers/azure-devops.md](providers/azure-devops.md) |

+ | GitHub | [providers/github.md](providers/github.md) |

- - **Component identity:** Look up the owning component at the path declared as **<component-catalog>** in the root `AGENTS.md`. If the change spans components, list all affected.

- - **Scoped instructions:** Check for a `AGENTS.md` in each affected subtree and verify compliance.

- - **Architecture boundaries:** Verify architectural boundaries and layering (see the architectural rules declared under **<rules-index>** in the root `AGENTS.md`).

+ Rules:

- ### Related Issues

+ - Read exactly one provider file per run. Do not mix tools across providers.

+ - Use the provider's MCP tool for a step when the server is connected and the tool is available;

+ otherwise use the CLI fallback the provider file names for that step, for the whole run.

+ - Use local `git` only for local source-control work (branch, commit, fetch, push).

+ - If a step cannot be completed with the named tools, say exactly what is missing and stop.

- Link to the GitHub issue(s) this PR addresses. Use `Closes #<n>` to auto-close an issue on merge. If the PR is one step of a larger issue, use `Part of #<n>`. If no issue exists, state the origin of the requirement (e.g., "Discovered during manual testing of x86 deployment").

+ ## Inputs

- ### Validation

+ All inputs are optional; each has a resolution rule below.

- List focused verification. Do not say "tests pass" generically — be specific:

+ - **Provider**: from Provider Selection.

+ - **Source branch**: the branch to merge; defaults to the current branch.

+ - **Target branch**: see Target branch.

+ - **Title**: see Title.

+ - **Draft**: open the pull request as a draft. Ask when the user has not said and the work is

+ not ready for review.

+ - **Linked work**: the issue or work item the change addresses; see Linked work.

+ - **Extra notes**: free text appended to the description's Notes.

+ - **Repository identity**: overrides for what the provider file reads from the remote (GitHub

+ owner and repository; Azure DevOps organization, project, and repository).

- - Which test suites were run.

- - Whether new tests were added for the change.

- - Any manual verification performed and in what environment.

- - Coverage implications if applicable.

+ ## Before opening

- ### Documentation impact

+ Verify each item, and fix or report anything that fails before creating the pull request:

- This section drives the docs-dev plan-closeout workflow. Be honest:

+ - [ ] **The source branch is pushed** and up to date with its remote.

+ - [ ] **The host's declared gates pass.** Run the commands the root `AGENTS.md` lists, and the

+ build, test, lint, and format commands the declared **<technology>-coding-standard** names for

+ each technology the change touches (for example **<csharp-coding-standard>**). When a standard

+ is undeclared or still a draft, say so and ask whether to proceed; do not substitute commands

+ of your own.

+ - [ ] **Scoped instructions are followed.** Read the nearest `AGENTS.md` to every changed file

+ and confirm the change complies.

+ - [ ] **Architecture rules hold.** Check the change against the rules declared under

+ **<rules-index>** in the root `AGENTS.md`.

+ - [ ] **Canonical documentation is current.** A change to a component's public interface,

+ configuration, architecture, runtime, operations, or workflow updates its documentation in the

+ shape the **<documentation-ontology>** declares.

+ - [ ] **The catalog is current.** A change that adds, moves, renames, or materially alters a

+ component updates the **<component-catalog>**.

+ - [ ] **No secrets or credentials.** The change and the description contain no tokens,

+ connection strings, passwords, `.env` files, customer data, or unsafe deployment commands.

+ - [ ] **The environment is ready.** When tooling is missing, use the `setup-dev-environment`

+ skill.

- - Check "canonical documentation updated" only if you updated it in this PR.

- - If no update was needed, explain why (e.g., "Internal refactor with no public interface change").

- - Documentation updates are required when: public interface, configuration, architecture, runtime, operations, or workflow changes. See the documentation ontology declared as **<documentation-ontology>** in the root `AGENTS.md`.

+ ## Target branch

- ### Security and operations

+ Resolve the target branch in this order:

- - Verify no secrets are committed (tokens, connection strings, passwords, `.env`).

- - If the change introduces a new configuration key or environment variable, document it and update the relevant onboarding or reference documentation.

- - If the change affects deployment or operational procedures, document the impact.

+ 1. The explicit target branch the user gave.

+ 2. Conclusive evidence of the source branch's parent:

+ - the user named it earlier in the conversation;

+ - a branching rule the host declares (the root `AGENTS.md`, a contributing guide, or a rule

+ under **<rules-index>**) that covers this branch's type;

+ - the source branch's upstream or tracking configuration;

+ - an existing pull request for the same source branch.

+ 3. Otherwise, list the repository's long-lived branches (the provider file's "List long-lived

+ branches" step), then ask the user to choose one or name another.

- ## 5. Required CI checks

+ Never assume the default branch is the target, and never assume a branch such as `develop` or

+ `main` exists or is the integration branch. The branching model is host policy, and a pull

+ request into the wrong base merges silently into the wrong place.

- Continuous integration workflows run automatically on PRs targeting `main` or `develop` (or the repository's configured integration branches). Before requesting review or merging, inspect the repository's active workflows in `.github/workflows/` (such as `ci.yml` or the repository's active PR gate) and verify that all configured checks pass.

+ ## Title

- Check status via the GitHub CLI or web UI:

+ 1. The explicit title the user gave.

+ 2. A host convention wins when present: guidance in the host's pull request template, a

+ contributing guide, or a rule under **<rules-index>** (a component prefix, a ticket prefix, a

+ conventional-commit type).

+ 3. Default: a concise imperative summary of what the change does, first word capitalized, no

+ trailing period, about 72 characters at most, with no prefix unless the host uses one.

- ```bash

- gh pr checks <pr-number-or-branch>

- ```

+ Do not build the title by title-casing the branch name: a branch name is an identifier, not a

+ summary of the change.

- ### Common CI check categories

+ ## Linked work

- Depending on the repository's technology stack and configuration, CI pipelines typically enforce the following check phases:

+ A host convention wins: use the host's issue or work-item reference style when it declares one.

+ Otherwise:

- | Phase | Purpose | Common Tools / Commands |

- |---|---|---|

- | Build & Unit Tests | Verifies clean compilation and passing unit tests across supported platforms | `dotnet build`, `dotnet test`, `npm test`, `pytest` |

- | Documentation & Ontology | Verifies documentation schema, link validity, and catalog alignment | `kyber-weave docs validate .`, `docs drift .`, `markdownlint-cli2` |

- | Security & SAST | Identifies vulnerabilities, insecure dependencies, and hardcoded secrets | CodeQL, Trivy, Semgrep, Gitleaks, Checkov |

- | Skill Quality Gates | Validates agent skill schema, description quality, and security policy | `kyber-weave skill validate`, `skill lint`, `skill scan` |

- | Integration & E2E | Executes cross-service, end-to-end, or platform-specific test suites | Host-specific integration / test runner commands |

+ - Detect the item from the branch name only when it carries one unambiguously: a leading number

+ (`42-add-retry`) or a key such as `ABC-123`. Otherwise ask, or omit the section.

+ - When this pull request completes the item, use the provider's closing mechanism, which the

+ provider file describes along with where it takes effect.

+ - When this pull request is one step of a larger item, use a non-closing reference such as

+ `Part of #42`.

+ - Keep an alphanumeric key from another tracker as-is, for example `Ticket: ABC-123`.

- ### Handling check failures

+ Whether to close an item is a statement about intent; the closing syntax and when it takes effect

+ are provider facts.

- 1. **Build or Test failure:** Inspect the failure log from the workflow run or binlog artifact. Reproduce locally using the appropriate build or test command (e.g., `dotnet test --filter "FullyQualifiedName=<test-name>"`).

- 2. **Documentation or Lint failure:** Run the relevant validation tools locally. Fix markdown formatting (`markdownlint-cli2`), repair broken relative links, and ensure catalog/ontology alignment via `kyber-weave docs validate .` (and `docs drift .` if code-refs are used).

- 3. **Security scan failure (CodeQL / Trivy / Semgrep / Gitleaks):** Review the SARIF output in the GitHub Security tab or runner logs. Remediate HIGH or CRITICAL findings. If a finding is a confirmed false positive, follow repository policy to document and suppress it with an explicit rationale.

- 4. **Skill gate failure:** Run Kyber-Weave commands locally: `kyber-weave skill validate <path>`, `kyber-weave skill lint <path>`, or `kyber-weave skill scan <path>`. Address schema violations or findings.

- 5. **Environment or Runner flake:** If a failure is definitively caused by runner infrastructure issues (e.g., transient network timeout, external service outage) unrelated to the PR diff, re-run the failed job or document the issue in a PR comment and tag a maintainer.

+ ## Description

- ## 6. Review process

+ If the host has a pull request template, fill in every section of the host's pull request

+ template; the provider file lists where each provider looks for one. Leave no placeholder text.

+ Otherwise use these sections:

- ### Who reviews

+ - **Summary**: the problem and the outcome, in one to three sentences; why more than how.

+ - **Type of change**: bug fix, feature, breaking change, refactor, or documentation.

+ - **Linked work**: as decided under Linked work; omit when there is none.

+ - **Changes**: a short list of what changed, summarized from the commits and the diff.

+ - **Validation**: which suites ran, which tests were added, and any manual verification and its

+ environment. Never write "tests pass" without naming them.

+ - **Documentation impact**: what documentation changed, or why none was needed.

+ - **Notes**: extra notes, follow-ups, and anything reviewers should know.

- - **Code review:** The `code-reviewer` agent (or a human reviewer) performs a structured review covering correctness, security, performance, maintainability, and architecture compliance.

- - **Security review:** The code-reviewer includes a branch-diff security vulnerability pass. CodeQL, Trivy, Semgrep, and Checkov scans run automatically in CI.

- - **Plan closeout review:** For plan-backed work, the `docs-dev` agent verifies the plan's acceptance criteria against the implementation and updates canonical documentation before the plan is archived.

+ Do not paste raw commit lists or file lists; the provider shows both. Write the description to a

+ UTF-8 file and pass the file wherever the provider's CLI allows; the provider file says how.

- ### What reviewers check

+ ## Create or update

- Reviewers verify:

- - Pre-PR checklist items (see §1).

- - Correctness and functional logic.

- - Adherence to Clean Architecture and scoped instructions.

- - Adequate test coverage.

- - Documentation accuracy and completeness.

- - No secrets or credentials.

- - CI check results.

+ 1. Look for an open pull request from the source branch into the target branch.

+ 2. If one exists, update its title and description. Otherwise create one, as a draft if asked.

+ 3. Read the pull request back and confirm its title and description match what was sent. Retry

+ once on a mismatch, then report it.

+ 4. Report the pull request link.

- ### Responding to review feedback

+ Never create a test pull request unless the user asked for one. Ask before requesting specific

+ reviewers, and before enabling automatic completion or merge.

- - Address all review comments, either by making the requested change or by explaining why the current approach is correct.

- - Re-request review after pushing changes.

- - Do not merge until all conversations are resolved and all required checks pass.

+ ## CI checks

- ## 7. Post-merge steps

+ Checks run on the pull request as the host configured them. Use the provider file's "Check CI

+ status" step and wait for the result before requesting review.

- ### For plan-backed work

+ When a check fails:

- When the PR is merged, the orchestrator follows the plan closeout process defined in the root `AGENTS.md`:

+ 1. **Build or test**: read the log, reproduce locally with the command the host declares, fix the

+ cause, and push.

+ 2. **Documentation or lint**: run the same validation locally and fix what it reports.

+ 3. **Security scan**: read the findings; fix high and critical ones. Suppress a confirmed false

+ positive only the way the host's policy allows, with the reason recorded.

+ 4. **Infrastructure**: when a failure is clearly the runner or an outside service and not the

+ change, re-run the job once, or record it in a comment for a maintainer.

- 1. The orchestrator assigns a `docs-dev` plan-closeout task.

- 2. The documentation specialist verifies the plan's acceptance criteria against the implemented behavior.

- 3. The specialist updates the affected canonical documentation (if not already updated in the PR).

- 4. The specialist maintains the plan index (at the path declared as **<plan-index>** or **<component-catalog>** in the root `AGENTS.md`).

- 5. The plan is archived under `<docs-root>/archive/plans/` with status `Archived`.

+ ## Review

- The PR is not the final step for plan-backed work — documentation verification and archiving are required before the plan is considered complete.

+ - A human reviewer, or the `code-review` skill, reviews correctness, security, performance,

+ maintainability, test coverage, and compliance with the host's rules.

+ - Answer every review comment, with a change or with the reason the current approach stands. Use

+ the `pr-review-fix-comments` skill to work through them.

+ - Request review again after pushing changes. Do not merge while a conversation is unresolved or a

+ required check is failing.

- ### For non-plan work

+ ## After merge

- - Verify that the PR description's "Documentation impact" section reflects the final state.

- - If the change introduced new configuration, runtime dependencies, or operational procedures, ensure the relevant documentation under `<docs-root>` is updated.

- - Delete the feature branch after merge (GitHub offers a "Delete branch" button on merged PRs).

+ - **Plan-backed work**: the pull request is not the last step. A `docs-dev` closeout verifies the

+ plan's acceptance criteria against what was built, updates the canonical documentation, and

+ archives the plan through the index the **<plan-index>** declares.

+ - **Other work**: confirm the description's documentation impact still matches what merged.

+ - Delete the source branch when the host's convention is to delete merged branches; the provider

+ file names the step.

- ## 8. Common pitfalls

+ ## Common pitfalls

| Pitfall | Resolution |

|---|---|

- | PR targets `main` but should target `develop` | Update the base branch in the PR before merging |

- | Template section left blank or as placeholder | Fill it out — reviewers will request changes |

- | Docs-quality check fails on link validation | Run `lychee --offline` against the changed `.md` files |

- | Trivy reports a vulnerability in an indirect dependency | Update the dependency, or add a pinned transitive override in the owning project file with a justification comment |

- | `dotnet build` succeeds locally but fails in CI | Check for platform-specific code, missing SDK workloads, or environment variable assumptions |

- | No issue linked in the PR description | Find or create the tracking issue and add `Closes #n` to the description |

+ | The pull request targets the wrong base branch | Change the target branch on the pull request before merging, then re-run checks |

+ | A template section is left as a placeholder | Fill it in; reviewers will ask for it |

+ | A closing reference did not close the item | Check the provider's rule for where closing takes effect; the target may not be the default branch |

+ | The description lost its line breaks | Pass the description as a file, or as one value per line, as the provider file says |

+ | The MCP server cannot create the pull request | It may be read-only or not connected; use the provider's CLI fallback for the whole run |

+ | A check passes locally but fails in CI | Look for platform differences, missing SDK workloads, or environment assumptions |

- ## See also

+ ## Resources

- - Pull Request template (`.github/PULL_REQUEST_TEMPLATE.md`) — the template every PR must fill out.

- - `create-pull-request-github` skill — mechanical steps for creating the PR via GitHub MCP or `gh` CLI.

- - PR CI workflows (`.github/workflows/`) — the CI workflows that validate PRs (e.g. `ci.yml` or active PR gate).

- - Documentation ontology — declared as **<documentation-ontology>** in the root `AGENTS.md`.

- - Component catalog — declared as **<component-catalog>** in the root `AGENTS.md`.

- - Architecture rules — declared under **<rules-index>** in the root `AGENTS.md`.

- - `AGENTS.md` — repository-wide mandatory instructions.

- - `setup-dev-environment` skill — dev environment setup and validation.

+ - [providers/github.md](providers/github.md): GitHub tools, CLI commands, templates, and closing

+ keywords.

+ - [providers/azure-devops.md](providers/azure-devops.md): Azure DevOps tools, CLI commands,

+ templates, and work-item linking.

+ - [scripts/github-create-pr.sh](scripts/github-create-pr.sh) and

+ [scripts/github-create-pr.ps1](scripts/github-create-pr.ps1): create or update one GitHub pull

+ request with the CLI and verify it.