This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new fec3031 docs(pairing): add Pairing family README and link from
modes.md (#578)
fec3031 is described below
commit fec3031ced9dd9f8cbd9af21ab558c3ab9a22cbd
Author: Justin Mclean <[email protected]>
AuthorDate: Sat Jun 27 20:10:37 2026 +1000
docs(pairing): add Pairing family README and link from modes.md (#578)
Add docs/pairing/README.md — the human-facing family overview for the
Pairing mode, following the same pattern as docs/issue-management/,
docs/pr-management/, and docs/mentoring/. Covers the two shipped skills
(pairing-self-review, pairing-multi-agent-review), when to use each,
the relationship to pr-management-code-review, and the minimal adopter
contract (no config files; only <upstream> and <default-branch>
placeholders). Update docs/modes.md § Pairing to add a "Docs" reference
table pointing to the new file.
Generated-by: Claude (Opus 4.7)
---
docs/modes.md | 4 ++
docs/pairing/README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 111 insertions(+)
diff --git a/docs/modes.md b/docs/modes.md
index 726b4c5..d8a963c 100644
--- a/docs/modes.md
+++ b/docs/modes.md
@@ -228,6 +228,10 @@ follows only after Pairing has established that human
reasoning
and relationships, not implementation chatter, are the
load-bearing parts of the workflow.
+| Doc | Purpose |
+|---|---|
+| [`docs/pairing/README.md`](pairing/README.md) | Family overview: skills,
when to use each, adopter contract. |
+
## Auto-merge
**Status: off. Deliberately not implemented.**
diff --git a/docs/pairing/README.md b/docs/pairing/README.md
new file mode 100644
index 0000000..6650f58
--- /dev/null
+++ b/docs/pairing/README.md
@@ -0,0 +1,107 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update
-->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with
[DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pairing skill family](#pairing-skill-family)
+ - [Skills](#skills)
+ - [When to use which](#when-to-use-which)
+ - [Relationship to
`pr-management-code-review`](#relationship-to-pr-management-code-review)
+ - [Adopter contract](#adopter-contract)
+ - [Status](#status)
+ - [Cross-references](#cross-references)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Pairing skill family
+
+Developer-side pre-flight review skills that run in the maintainer's or
+contributor's **own** dev loop — after local changes are ready but before
+opening a PR. The family absorbs mechanical implementation-detail review
+so the eventual human-to-human conversation between contributor and
+maintainer stays on design, reasoning, and the trade-offs the project
+cares about.
+
+**Mentorship is intrinsic.** Pairing skills are not a replacement for
+human code review; they are a pre-flight filter that separates
+implementation-detail nits (formatting, convention violations, obvious
+logical gaps) from the design-level conversation the project's
+contributor-to-committer path is built on.
+
+**No state changes.** Every skill in this family reads local git state
+and returns a structured report. No PR is opened, no GitHub write
+happens, no comment is posted, and the working tree is never mutated.
+
+---
+
+## Skills
+
+| Skill | Purpose | Status |
+|---|---|---|
+| [`pairing-self-review`](../../skills/pairing-self-review/SKILL.md) |
Structured pre-flight self-review of local changes against a configurable base.
Single-pass: correctness, security, and conventions in one report. |
experimental |
+|
[`pairing-multi-agent-review`](../../skills/pairing-multi-agent-review/SKILL.md)
| Fan the same diff through three independent axis-focused passes
(correctness, security, conventions); merge findings with deduplication and
severity ranking. Higher confidence than a single pass; each axis is isolated
so findings cannot cross-contaminate. | experimental |
+
+### When to use which
+
+- **`pairing-self-review`** — the default quick check. Fast, single
+ context, covers correctness + security + conventions.
+- **`pairing-multi-agent-review`** — when you want adversarial
+ independence between review axes. Each pass cannot see the others'
+ findings, so a security issue buried in a conventions sweep cannot
+ get lost. Use for changes touching security-sensitive paths or for
+ the final check before a high-stakes PR.
+
+Both skills are read-only / hand-back and produce the same structured
+report format, so you can switch between them without changing your
+workflow.
+
+---
+
+## Relationship to `pr-management-code-review`
+
+`pairing-self-review` and `pairing-multi-agent-review` run **before** a
+PR is open. Once a PR is open and you want a maintainer-side deep code
+review of an incoming contribution, use
+[`pr-management-code-review`](../../skills/pr-management-code-review/SKILL.md)
+instead.
+
+---
+
+## Adopter contract
+
+The Pairing skills have no project-specific config files. They resolve
+two standard placeholders from the adopter's `<project-config>/`:
+
+| Placeholder | Resolved from |
+|---|---|
+| `<upstream>` | `project.md → upstream_repo` (owner/name of the public source
repo) |
+| `<default-branch>` | `project.md → upstream_default_branch` (e.g. `main`) |
+
+No additional config files are required. The skills do not write to the
+project's tracker, label set, or any shared infrastructure.
+
+---
+
+## Status
+
+**Experimental.** Both `pairing-self-review` and
+`pairing-multi-agent-review` are shipped and validate under
+`skill-and-tool-validate`. No adopter-pilot evaluation has run yet;
+shape may change between framework versions.
+
+---
+
+## Cross-references
+
+- [`MISSION.md` § Pairing](../../MISSION.md#technical-scope) — mode
+ rationale, sequencing constraints relative to Auto-merge.
+- [`docs/modes.md` § Pairing](../modes.md#pairing) — implementation
+ status and mode-lifecycle stage.
+- [`docs/modes.md` § Mode lifecycle](../modes.md#mode-lifecycle) — how
+ a mode moves from `experimental` to `stable`.
+- [`projects/_template/README.md`](../../projects/_template/README.md) —
+ adopter scaffold index.
+- [`docs/setup/agentic-overrides.md`](../setup/agentic-overrides.md) —
+ the override mechanism every skill in this family supports.
