decision: organization procedures live once, as public runbooks that thin skills route to

[ss-o]

Problem

Organization tasks (triaging an issue, taking a pull request from branch to merge, updating Project 28) run differently depending on the agent runtime and the repository, so outcomes vary and lessons have nowhere shared to land.

The procedures mostly exist, as runbooks (triage.md, project-tracker.md, release.md, org-review.md, learning-capture.md, and more). But none of the ten skills here covers triage, pull requests, the tracker, or releases, and only code-review and zi-install are vendored downstream (lib/approved-skills.json).

A review of one agent session working through the z-shell/zsh-lint backlog on 2026-09-26 found:

• The agent worked from runtime-private skills that restated rules from this repository (the ADR-0026 fallback, branch names, the issue form, tracker fields). Those copies had drifted, and context compaction pruned them mid-session.
• Its runtime did not load the organization skills at all: project skills needed a per-worktree trust step that had not been taken.
• The outcomes that varied were exactly the unwritten ones:
  • ci(corpus): guard F-Sy-H and the Zsh Completion tree against regressions (#470) zsh-lint#486 said Closes #470 although it met only part of ci(labels): run the labels-sync test suite on tooling changes #470's acceptance criteria (follow-up Promote F-Sy-H to the strict corpus and correct the regression-corpus survey record zsh-lint#488);
  • fix(parse): read a line continuation as trivia before a redundant separator (#467) zsh-lint#489 merged after a post-review rebase with no new review;
  • fallback reviews carried the ADR-0026 marker without the code-review checklist having run;
  • a scope question referred to a plan the maintainer was never shown.
• The branch name docs-488 failed the required branch-name check (docs(corpus): verify the Zsh 5.9 false accepts in the regression survey record (#488) zsh-lint#490, reopened as fix(ci): stop profile deploys overwriting wiki #491). The rule existed, but only in CI, where the agent first met it.
• Rules enforced before the pull request opened, such as the issue link and PR title, were followed.

Proposal

Draft ADR-0032 (PROPOSED):

1. Organization procedures are public and live once, as runbooks. The private maintainer workspace holds only environment bindings.
2. An organization skill is a thin router: trigger-rich description, checklist, gates and checks, then "read the runbook". This is the pattern review-project-learning already follows.
3. Few skills with strong triggers. This adopts chore(skills): remove git-commit and gh-cli, which only restate AGENTS.md policy #623 (remove git-commit and gh-cli).
4. Anything checkable before merge becomes a check.
5. Runtime-private skills hold runtime mechanics only.
6. Delivery is verified per runtime.

Follow-ups (after the ADR)

• runbooks/pull-requests.md: branch naming, Closes only when every acceptance criterion is met, the review gate and ADR-0026 fallback executed under code-review, a push voiding an earlier review, merge, post-merge. Depends on decision: amend ADR-0026 for maintainer-elected fallback reviews #664; the maintainer's position there is to allow a maintainer-elected fallback with its own marker, still running the checklist.
• An investigation and evidence standard for triage.md, and a duplicate search that covers closed issues.
• Thin issue-triage, pull-request and project-tracker skills, then delivery and reference-integrity checks.

[ss-o]

The runbooks/pull-requests.md follow-up landed in #670 (squash ca7f6b2), routed from .github/instruction-surfaces.json as runbook-pull-requests. It went through five fallback reviews; the fifth found nothing in the files.

Still open under this issue:

• An investigation and evidence standard for triage.md, and a duplicate search that covers closed issues.
• Thin issue-triage, pull-request and project-tracker skills, then delivery and reference-integrity checks.

Related work tracked elsewhere: the ADR-0026 amendment for the interim rulings on #664 (up-front fallback election, push voiding a fallback review, review of record where the base branch has no Copilot review), and the policy drift found in review, #671.