Skip to content

standardize-repo: draft-PR creation is a phase transition into shepherd, not a stopping point #429

Description

@evanharmon1

Invariant

standardize-repo's Verification section already requires shepherding a draft
PR to the readiness gate. An orchestrator delegating the mode to a subagent must
carry that requirement into the subagent's brief — because the subagent does
exactly what its brief says, and a brief that ends at gh pr create --draft
produces a PR nobody finishes.

Current violation (observed 2026-08-11)

Two subagents were dispatched to run update mode on ponderousdev/omator and
ponderousdev/lawnomator-site. Both briefs said, in effect, "open a draft PR and
stop there; do not run gh pr ready". The second clause was right. The first
collapsed the entire shepherd stage into it, and both agents stopped with red CI
and no Codex cycle — reporting local task verify as the verification result.

The cost was not hypothetical. lawnomator's PR had three checks failing and,
once shepherding actually ran, its Codex cycle found a P1 that a merge-conflict
resolution had introduced
: claude-implement.yml's authorized-sender check was
missing exit 0 on its success arm, so every authorized run failed before
doing any work. That bug was inside the standardization PR and would have shipped
had the stage stayed skipped.

Two secondary failures, both worth naming because both are mechanical:

  1. Local task verify was reported as "green" while CI was red. A brief that
    ends at PR creation makes the local gate the last thing an agent sees, so the
    local result becomes the report.
  2. Both agents lost a cycle by backgrounding gh pr checks --watch and then
    ending their turn.
    Ending the turn discards the watch, so nothing was
    waiting; each agent stopped mid-stage believing it had a poll in flight. One
    reported "I'll report back once CI settles" and simply stopped.

Proposal

Two additions to the skill, both aimed at the delegated case:

  • State that gh pr create --draft returning is a phase transition into
    shepherd
    , not a stopping point, and that a brief handing this mode to a
    subagent must say so explicitly. Stopping at draft creation is a non-success
    stop
    requiring a blocker report — not the deliverable.
  • State that CI must be polled synchronously inside a single tool call
    (a bounded loop with a generous timeout), never by backgrounding a watch and
    ending the turn. Note that waiting on CI is not a shepherd round, so the
    synchronous poll costs nothing against the round cap.

Both are one paragraph each in the Verification section, where the
draft-workbench lifecycle is already described.

Verify

# What the skill says about the draft PR today:
grep -n 'draft' <skill-dir>/SKILL.md | head -20

# What it says about polling:
grep -niE 'poll|watch|bounded' <skill-dir>/SKILL.md

Expected today: the Verification section requires shepherding and the readiness
gate, but says nothing about how a delegated brief must carry that requirement,
and nothing about the backgrounded-watch failure mode.

Acceptance criteria

  • The skill states that draft-PR creation is a phase transition into
    shepherd, and that stopping there is a non-success stop requiring a blocker
    report.
  • The skill states that a brief delegating this mode must carry the shepherd
    requirement explicitly, since a subagent does what its brief says.
  • The skill states that CI is polled synchronously within a single tool call,
    and that a backgrounded watch is discarded when the turn ends.
  • The skill states that a local gate result is never reported as the PR's
    verification status.

Found while running update mode via subagents across ponderousdev/omator and
ponderousdev/lawnomator-site.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationdomain:platformCI, build, test infra, and tooling in this repo

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions