From 06bd81f4293a24e12cde1f0e466596b41095e8f4 Mon Sep 17 00:00:00 2001 From: Scott Haug Date: Sun, 19 Jul 2026 16:29:50 -0700 Subject: [PATCH] feat: add epic sequence implementation skill - Add an end-to-end workflow for implementing GitHub and Linear epics - Encode bounded adversarial and connector review gates - Preserve current-candidate validation, safe merge, and cleanup requirements - Make the established ticket implementation workflow reusable across projects - Keep dependency ordering, review evidence, and mutation authority explicit --- CHANGELOG.md | 4 +- README.md | 2 + skills/implement-epic-sequence/SKILL.md | 309 ++++++++++++++++++ .../agents/openai.yaml | 4 + .../references/closeout-and-cleanup.md | 100 ++++++ .../references/github.md | 199 +++++++++++ .../references/linear.md | 54 +++ .../references/review-and-merge-gates.md | 133 ++++++++ 8 files changed, 804 insertions(+), 1 deletion(-) create mode 100644 skills/implement-epic-sequence/SKILL.md create mode 100644 skills/implement-epic-sequence/agents/openai.yaml create mode 100644 skills/implement-epic-sequence/references/closeout-and-cleanup.md create mode 100644 skills/implement-epic-sequence/references/github.md create mode 100644 skills/implement-epic-sequence/references/linear.md create mode 100644 skills/implement-epic-sequence/references/review-and-merge-gates.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 50194ef..d567b4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,9 +4,11 @@ summary: Chronological history of repository and skill changes. # Changelog -## 2026-07-19 — Remove incomplete modular review contract +## 2026-07-19 — Epic workflow and review contract cleanup +- feat: add epic sequence implementation skill - revert: remove modular code review contract + (b889fe4dc313dc50320dcb20f98980b993062c9a) ## 2026-02-24 — Modular code review contract specification diff --git a/README.md b/README.md index e3f3f6a..c64796e 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ A personal monorepo for agent skills and supporting scripts. Current skills: +- `skills/implement-epic-sequence` — execute GitHub or Linear epics through + dependency-aware implementation, review, merge, cleanup, and closeout - `skills/prepare-changesets` — decompose a large, review-ready branch into a deterministic chain of smaller, reviewable changesets and GitHub PRs diff --git a/skills/implement-epic-sequence/SKILL.md b/skills/implement-epic-sequence/SKILL.md new file mode 100644 index 0000000..8aec80f --- /dev/null +++ b/skills/implement-epic-sequence/SKILL.md @@ -0,0 +1,309 @@ +--- +name: implement-epic-sequence +description: Execute one or more GitHub or Linear epics end to end through their live dependency graphs. Use when Codex should select unblocked PR-sized children, implement each in an isolated branch or worktree, run repository validation and bounded review loops, wait for current-head review and CI gates, merge and clean up safely, refresh the graph after every merge, and close epics only after resulting behavior and acceptance criteria are verified. +--- + +# Implement Epic Sequence + +Execute the live work graph, one independently mergeable child at a time. Treat +tracker state and repository evidence as the source of truth; do not turn an old +plan or conversation summary into execution state. + +## Load the relevant references + +- Resolve the issue tracker and the code/PR host independently. +- Read `references/github.md` whenever GitHub owns issue state or hosts the + repository and PRs. This includes Linear-owned epics implemented through + GitHub PRs. +- Read `references/linear.md` whenever Linear owns parent, child, dependency, or + status state. +- Always read `references/review-and-merge-gates.md` before publishing the first + PR in a run. +- Always read `references/closeout-and-cleanup.md` before merging the first PR + or closing an epic. + +For cross-system work, load every applicable adapter and record which system +owns issue status, dependency state, source code, PR state, checks, review, and +merge. Do not assume the issue tracker also hosts the PR. + +## Resolve the operating contract + +Before changing code, resolve: + +- repository and tracker; +- epic identifiers and any named child subset; +- base branch; +- completion policy: ready PRs only, merge after gates, or merge plus epic + closeout; +- execution mode: serial by default, parallel only when explicitly requested; +- required review mechanism; +- mutation authority for tracker edits, status or dependency changes, follow-up + creation, review replies and resolution, merge, parent closeout, remote-branch + deletion, and deployment; +- named architecture, design, contract, or rollout documents. + +Unless the user or repository contract states otherwise, apply this authority +matrix: + +- `ready PRs only` authorizes isolated implementation, commits, feature-branch + pushes, PR creation or updates, evidence-based review replies, and resolution + of fully addressed review threads; +- `merge after gates` additionally authorizes merging the in-scope PR and safely + deleting its verified merged feature branch; +- `merge plus epic closeout` additionally authorizes evidence comments and + manual status or close transitions for the in-scope children and parents; +- issue-body edits, dependency-graph mutations, and follow-up-ticket creation + require explicit ticket-management authority; and +- deployment, production mutation, and destructive data operations always + require explicit authority. + +Do not infer merge or issue-close authority from words such as `finish`, +`complete`, or `execute end to end`; treat them as persistence within the +selected completion policy. Merge PRs or close issues only when the user +explicitly selects a merge-inclusive policy or unambiguously asks for those +actions. When merge authority is unclear, stop at a ready PR and request it. +Never infer deployment or production mutation from merge authorization. + +If a required input cannot be discovered safely and materially changes the +outcome, stop and ask. Otherwise use repository conventions. + +## Establish source-of-truth precedence + +Use this order within the task: + +1. Current user instructions. +2. Live parent, child, dependency, and PR state. +3. Repository `AGENTS.md` and equivalent local instructions. +4. Named architecture, design, contract, and rollout documents. +5. Current code and tests. +6. Prior summaries or memory as orientation only. + +Stop on material conflicts between the live dependency graph, ticket body, and +repository contract. Do not choose the most convenient interpretation. + +## Run the epic loop + +Repeat the following procedure until the requested scope reaches its completion +policy or a genuine blocker requires user input. + +### 1. Refresh live state + +- Read every in-scope epic and its open children. +- Read native parent, blocking, and blocked-by relationships. +- Read the dispositions and delivered outcomes of closed blockers for candidate + children. +- Inspect existing branches and open or merged PRs for candidate children. +- Recompute ready work after every merge; never reuse yesterday's order. +- Separate the serial critical-path recommendation from parallel-ready work. + +When multiple children are ready, prefer the child that unlocks the most +downstream work without widening scope. Prefer contracts and additive +foundations before consumers and cutovers. + +### 2. Apply the readiness gate + +Select a child only when it: + +- is open and belongs to an in-scope epic; +- has no unresolved native blocker; +- has every required closed-blocker outcome verified in its authoritative + repository, artifact registry, tracker, or environment; for a cross-repository + or operational prerequisite, also verifies that the consumer uses the required + contract, version, configuration, approval, or environment state; +- is not already implemented, superseded, or represented by another PR; +- delivers one coherent outcome through one PR; +- states goals, non-goals, acceptance criteria, and verification; +- contains no unresolved product, data, authorization, migration, destructive, + or architecture decision; +- identifies existing behavior that must be preserved; +- can merge without exposing misleading or incomplete behavior. + +Treat a canceled or not-planned blocker with an unmet required outcome as +unresolved even when the tracker marks it closed. Do not absorb that missing +prerequisite into the selected child. Do not improvise missing requirements. +When ticket editing is authorized, make the ticket implementation-ready and +re-read it. Otherwise select another ready child or report the missing decision. + +### 3. Create isolated implementation state + +- Confirm the primary checkout, current worktree, and all registered worktrees. +- Fetch and prune the remote. +- Start a fresh feature branch and disposable worktree from the current remote + base unless the repository directs otherwise. +- Use one ticket per branch and one ticket-closing PR. +- Verify the new worktree is clean before editing. +- Install dependencies and start documented local services before diagnosing + missing-tool or missing-service failures as feature failures. + +Preserve unrelated worktrees, branches, and local changes. Never reuse a dirty +or ambiguous checkout merely to save setup time. + +### 4. Implement the ticket contract + +- Read nearby implementation and tests before editing. +- Keep the live child and named source documents as the scope boundary. +- Preserve explicit non-goals and existing behavior named by the ticket. +- Follow existing architecture and extension points. +- Add focused behavior tests with the implementation. +- Update contract or contributor documentation when executable behavior changes. +- Keep exported-symbol documentation aligned with repository rules. +- Avoid speculative backfills, compatibility layers, or abstractions for + nonexistent conditions. + +Apply incidental changes only for a demonstrated correctness, security, +acceptance, architecture, or validation need, or for an obvious low-cost +correctness or safety improvement with demonstrated current risk. Refactor to +reduce cognitive load only when the user explicitly requests it or when the +ticket's correctness cannot otherwise be made evident. Defer polish, broad +refactors, hypothetical hardening, and adjacent epic work. + +### 5. Validate in layers + +Discover validation from repository instructions and tooling. Run: + +1. focused tests for changed behavior; +2. relevant static checks; +3. the complete required repository gate; +4. integration tests with documented real dependencies; +5. build, packaging, or manual checks required by the ticket. + +Report exact outcomes. Distinguish bootstrap/environment failures from feature +failures. Do not claim completion when required validation is unavailable or +failing. + +### 6. Publish one focused PR + +- Confirm no existing PR already owns the ticket. +- Commit using repository conventions. +- Push only the feature branch. +- Summarize the whole branch, observable outcome, important non-goals, and + actual validation. +- Include the tracker-closing reference required by the repository. +- Open the PR as draft or ready according to the operating contract. + +Do not combine independently useful tickets in one PR, even when they touch the +same files. + +### 7. Run bounded review + +Follow `references/review-and-merge-gates.md`. + +- Implement directly in the primary execution context. +- After local validation, require one fresh, read-only adversarial + `code-review-pro` pass in a separate review-only subagent or equivalent + isolated context unless the user explicitly waives it or independent review + tooling is unavailable. +- Use a fresh or minimally inherited context. Give the reviewer only raw task + artifacts: repository instructions, the live ticket, named specifications, the + complete `base...HEAD` diff for the captured head/base SHA pair, and + validation evidence. Do not provide the implementation transcript, intended + answer, prior conclusions, or suspected findings. +- Before review, require every intended ticket change to be committed and the + implementation worktree to be clean. If unrelated user artifacts prevent a + clean state, classify and preserve them and prove they are irrelevant to the + candidate. +- Before delegation, capture HEAD, commit history, and tracked, untracked, and + ignored worktree state. After review, verify that all remain unchanged. Treat + any reviewer mutation as an integrity failure and inspect it without + discarding user work. +- Review correctness, acceptance criteria, regressions, failure paths, security, + authorization, architecture, public surface area, tests, documentation, and + scope. +- Apply only material, tractable, in-scope findings. +- Re-run affected and required validation after fixes. +- Run a fresh pass after material fixes and invalidate prior remote review + signals after every head or base change. +- Use at most three adversarial passes by default. If the final pass still has a + material finding, do not merge; report the unresolved finding and request + direction. + +Do not silently count an unavailable independent reviewer as a passed gate. +Record the limitation, perform a fresh adversarial self-review, and proceed only +when repository policy does not require independence and the user has accepted +or already authorized the unavailable-tool fallback. + +Create a follow-up ticket only when ticket management is authorized and the gap +is real, evidenced, and intentionally outside the current PR. Otherwise report a +pasteable follow-up proposal. + +### 8. Merge only through current-candidate gates + +Follow both bundled gate references. Merge only when: + +- every intended ticket change is committed and represented by the candidate + diff, with any unrelated artifacts classified, preserved, and proven + irrelevant; +- required local validation passed; +- required CI passed or the repository explicitly has no such checks; +- every applicable required adversarial, human, and connector review has a clean + or approving verdict explicitly tied to the exact current head and base SHA + pair; +- no undispositioned actionable conversation comment, formal review, connector + feedback, or review thread remains; +- the PR still matches its ticket and base; +- no other PR superseded it. + +Treat every head change, including a push, rebase, conflict resolution, or +update-branch operation, and every base-branch advance as invalidating older +merge-candidate evidence. Rebuild and revalidate the current head/base candidate +before merge. + +After merge, verify the remote state and base-branch result before cleanup. + +### 9. Clean up and refresh + +- Confirm merge or patch equivalence before deleting branch state. +- Confirm the disposable worktree is clean and contains no untracked or ignored + user files. +- Confirm the local branch has no commit absent from its pushed PR branch, the + pushed branch when it still exists has not advanced beyond the PR's recorded + merged head, and that merged-head result is fully represented on the verified + base by ancestry or patch equivalence. Never force cleanup past a failed + precondition. +- Remove only the merged feature branch and disposable worktree. +- Preserve unrelated worktrees and edits. +- Verify the ticket closed as intended. +- Re-read the live graph before selecting another child. + +## Close an epic conservatively + +Use `references/closeout-and-cleanup.md`. Close an epic only when: + +- every required child is closed; +- no unresolved blocker remains; +- every required PR is represented on the base branch; +- epic acceptance criteria are verified against resulting behavior; +- required documentation, compatibility, migration, rollout, and cleanup work is + complete; +- no child closed as not planned leaves an unsatisfied outcome; +- the mandatory late-feedback sweep for every merged PR is complete and every + finding has a recorded disposition; +- required clean-main and candidate checks passed. + +For a series, validate each epic separately, then validate any umbrella parent. +Keep the parent open when any required outcome remains unsatisfied. + +## Stop conditions + +Stop and request direction when: + +- graph and ticket scope conflict materially; +- implementation requires an unresolved product or architecture choice; +- a destructive migration, production cutover, or deployment lacks authority; +- credentials, external approval, or unavailable infrastructure are required; +- correctness would materially exceed ticket scope; +- review feedback requires redesigning the ticket; +- required validation remains unavailable after documented bootstrap attempts. + +Difficulty, a long test suite, or ordinary CI wait time are not blockers. + +## Final reporting + +For each child, report the ticket, PR, merge result, validation, review state, +and cleanup result. At epic completion, report: + +- closed and intentionally deferred children; +- final dependency-graph state; +- mainline and acceptance-criteria evidence; +- remaining parallel-ready work outside the requested scope; +- any limitation that prevented full closeout. diff --git a/skills/implement-epic-sequence/agents/openai.yaml b/skills/implement-epic-sequence/agents/openai.yaml new file mode 100644 index 0000000..480b794 --- /dev/null +++ b/skills/implement-epic-sequence/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Implement Epic Sequence" + short_description: "Execute epics safely from ticket to merge" + default_prompt: "Use $implement-epic-sequence to implement the remaining ready children of this epic through review, merge, cleanup, and closeout." diff --git a/skills/implement-epic-sequence/references/closeout-and-cleanup.md b/skills/implement-epic-sequence/references/closeout-and-cleanup.md new file mode 100644 index 0000000..76e4f67 --- /dev/null +++ b/skills/implement-epic-sequence/references/closeout-and-cleanup.md @@ -0,0 +1,100 @@ +# Closeout and cleanup + +Verify remote and mainline state before deleting anything or closing a parent. + +## Per-PR cleanup + +01. Confirm the PR is merged remotely. +02. Fetch and prune the remote. +03. Confirm the branch's result is represented on the base branch. +04. Use ancestry first; use patch equivalence after squash or rebase when + ancestry is unavailable. +05. Map the exact disposable worktree, local branch, upstream branch, PR branch, + and base branch. Do not rely on the current directory or a branch-name + guess. +06. Inspect tracked, staged, unstaged, untracked, and ignored state in that + exact worktree. Always inventory ignored files, even when ordinary status is + clean. Classify ignored and untracked paths as reproducible generated output + or non-reproducible/user-created data. Stop or preserve `.env` files, + credentials, local databases, and every other non-reproducible artifact. +07. Confirm the local branch has no commits absent from its pushed PR branch. + When the remote branch no longer exists, compare the local tip with the PR's + recorded merged head. +08. When the pushed PR branch still exists, confirm it did not advance beyond + the recorded merged head. Confirm the merged-head result is fully + represented on the verified base by ancestry or patch equivalence. Stop if + either branch check fails. +09. If the local branch is checked out, remove the clean disposable worktree or + detach it before deleting the branch. Never force worktree removal. +10. Delete only the verified local feature branch, then its remote feature + branch when it still exists and repository policy permits deletion. +11. Prune worktree metadata and verify that the old path, local branch, and + remote branch are gone. +12. Preserve unrelated worktrees, branches, ignored and untracked files, and + user edits. + +If another worktree owns the base branch, update or merge from that checkout or +use the remote API. Do not force branch ownership changes. If cleanup +preconditions fail, report the exact dirty, ignored, or untracked paths or +unique commits and leave the worktree and branches intact. + +## Mainline verification + +After every merge, verify: + +- the remote base advanced as expected; +- the merged behavior and tests exist on the base; +- the child ticket closed or transitioned correctly; +- no required check or review state changed after merge; +- the next dependency graph read uses current remote state. + +Separate environment failures from regressions when validating a clean mainline. +Bootstrap documented dependencies and services before modifying code. + +## Late-feedback sweep + +Before closing an epic, inspect every merged PR in scope again. Read ordinary +conversation comments and thread-aware review state, including connector +comments or threads posted after merge. + +Classify late findings with the same rules used during active review and record +the disposition of each one. When a late finding exposes a required correctness, +security, acceptance, architecture, or validation gap: + +- keep the epic open; +- create or use an in-scope follow-up ticket when ticket mutation is authorized; +- implement the fix from a fresh branch based on the current remote base; +- never reopen, reuse, or edit the merged feature branch as the implementation + path; and +- pass the normal validation, review, merge, and cleanup gates. + +Do not close the epic until every late comment and review thread has a recorded +disposition and every blocking finding is resolved on the base branch. + +## Epic closeout + +Before closing an epic: + +- read the live child and blocker graph; +- confirm every required child disposition; +- confirm every required PR is merged and represented on the base; +- verify epic acceptance criteria against resulting behavior; +- run required clean-main validation; +- complete the mandatory late-feedback sweep for every merged PR; +- perform any required candidate smoke check, migration, documentation, + compatibility, or cleanup work; +- confirm no not-planned child leaves an unsatisfied outcome. + +Close each epic separately. For a series, close the umbrella only after every +required epic passes the same check. A nearly complete graph is not complete. + +## Final report + +Record: + +- merged PRs and their tickets; +- validation and current-head review evidence; +- branch and worktree cleanup results; +- closed, deferred, canceled, or blocked children; +- remaining critical-path and parallel-ready work; +- the exact reason any epic remains open. diff --git a/skills/implement-epic-sequence/references/github.md b/skills/implement-epic-sequence/references/github.md new file mode 100644 index 0000000..82a4686 --- /dev/null +++ b/skills/implement-epic-sequence/references/github.md @@ -0,0 +1,199 @@ +# GitHub execution adapter + +Use GitHub independently as an issue tracker, a PR host, or both. Apply only the +sections owned by its role in the current run. + +## Contents + +- [Ownership boundary](#ownership-boundary) +- [PR-host preflight](#pr-host-preflight) +- [GitHub-tracker preflight](#github-tracker-preflight) +- [Selecting work when GitHub owns issue state](#selecting-work-when-github-owns-issue-state) +- [PR contract](#pr-contract) +- [Review state](#review-state) +- [Checks and merge](#checks-and-merge) +- [Epic closeout when GitHub owns issue state](#epic-closeout-when-github-owns-issue-state) + +## Ownership boundary + +- When GitHub owns issue state, use the GitHub-tracker preflight, selection, + issue-closing syntax, dependency refresh, and epic closeout sections. +- Whenever GitHub hosts PRs, use the PR-host preflight, PR contract, review, + checks, merge, and branch-handling sections. +- When Linear owns issue state and GitHub hosts PRs, route all parent, child, + blocker, status, and closeout decisions through `linear.md`. Do not inspect or + mutate same-numbered GitHub issues as substitutes. + +## PR-host preflight + +- Resolve the repository from the request or current checkout. +- Confirm GitHub authentication. +- Inspect open and merged PRs that reference the candidate tracker ticket. +- Confirm local branch and worktree topology before creating implementation + state. +- When connector review is required, record the connector identity, automatic or + request-driven mode, exact initiation action, per-push policy, expected + run-start evidence, and accepted clean signal. Derive this contract from + repository instructions, configuration, or verified recent PR behavior. + +Fail closed before connector polling when its identity, initiation contract, or +required current-candidate signal cannot be discovered. + +## GitHub-tracker preflight + +Run this section only when GitHub owns issue state. + +- Read the epic body, labels, state, and comments when they affect scope. +- Read native `parent`, `subIssues`, `blockedBy`, and `blocking` relationships + through GraphQL or an equivalent structured GitHub tool. + +Do not derive ownership or ordering from issue title, issue number, Markdown +task lists, or prose dependency notes when native relationships exist. + +## Selecting work when GitHub owns issue state + +Choose an open child whose native `blockedBy` set contains no open issue. Verify +every required closed-blocker outcome in its authoritative repository, artifact +registry, tracker, or environment. For same-repository code, verify the result +on the base. For cross-repository or operational prerequisites, also verify that +the consumer uses the required contract, version, configuration, approval, or +environment state. Treat a canceled or not-planned blocker with an unmet outcome +as unresolved. + +Check that no open or merged PR already represents the child. When duplicate +branches or PRs exist, compare their actual patches or resulting trees and +retain one canonical path. + +Read the graph again after every merge because closing one child can unblock +work in another epic. + +## PR contract + +- Use one tracker child per branch and PR. +- When GitHub owns issue state, use the repository's closing syntax, normally + `Fixes #`. +- When another tracker owns issue state, use its required reference and avoid + GitHub issue-closing syntax unless a real GitHub issue is intentionally in + scope. +- Describe the branch as a whole rather than the latest commit. +- Preserve explicit ticket non-goals in the PR when scope pressure is likely. +- Confirm the PR base and head match the intended worktree. + +Use file-based PR bodies when shell interpolation could alter Markdown. + +## Review state + +Capture the exact PR head and base SHAs before evaluating review state. Read +ordinary PR conversation, formal reviews, and inline review threads; use GraphQL +or an equivalent thread-aware API when flat PR output does not expose thread +resolution. + +For required human review, record the reviewer, review state, reviewed commit +OID, submission time, and base SHA observed when the review arrives. Accept the +approval for the captured candidate only when its reviewed commit and observed +base equal the captured head/base pair. After a base advance, request fresh +approval after capturing the new pair. When the host cannot bind fresh approval +to an unchanged head plus a new base, update the branch so the candidate has a +new reviewable head and require approval on it. + +When the repository uses a connector bot, use the identity, initiation mode, and +clean signal recorded during PR-host preflight. Accept a clean result only when +all of these conditions hold: + +- the evidence comes from that configured connector identity; +- it is an explicit clean verdict represented by one of these forms: + - a formal review whose commit OID equals the captured SHA; + - a conversation comment that names the captured SHA; + - the configured clean reaction on a request or result that names the captured + SHA; or + - a configured PR-object thumbs-up from the connector bot that appeared as the + completion signal for the connector run on the captured SHA; +- the PR head still equals the captured SHA; and +- the current base-branch head still equals the captured base SHA; and +- there are zero unresolved connector-authored review threads. + +For a PR-object thumbs-up, require repository evidence that this is the +configured completion signal, capture the reaction identity and timestamp or +equivalent run evidence, and prove it appeared after the connector request or +run began for the captured SHA. Never reuse a PR-object reaction that predates +the captured head or cannot be tied to its connector run. + +Do not infer current-head approval from timing, comment order, a generic bot +message, CI success, or a verdict on an earlier commit. A push, rebase, conflict +resolution, or update-branch operation changes the head and invalidates all +older current-head evidence. + +For every actionable conversation comment, formal review, and inline thread: + +1. Verify the claim against the current code and ticket. +2. Fix it or reject it with concrete evidence. +3. Run affected and required validation. +4. Push when the code changed. +5. Reply publicly on the originating surface when possible and record the item + identifier, disposition, and evidence. +6. Resolve an inline thread only after its disposition is complete. + +Require zero undispositioned actionable items across conversation comments, +formal reviews, connector feedback, and inline threads before merge. + +After any head or base change, capture the new head/base pair and wait for a +fresh connector verdict tied to that candidate. Trigger the repository's +configured connector when review is request-driven. When review is automatic, +record evidence that a run began for the captured candidate after it was pushed +or rebuilt. Do not accept a verdict until its review request or automatic run is +tied to that candidate. + +Resolve the connector polling window and interval from repository instructions. +When none is configured, state and use a 30-minute window with a 30-to-60-second +polling interval. Start the window when the review request is sent or, for an +automatic connector, when the head is pushed. During every poll, re-read the +head and base SHAs, run-start evidence, required checks, conversation comments, +formal reviews, reactions, and review threads. + +If no automatic run begins or no valid current-head signal arrives within the +window, stop and report the missing gate. Keep the PR and epic open; never infer +approval from green CI or zero unresolved threads. Re-read the conversation, +formal reviews, review threads, reactions, head and base SHAs, and checks +immediately before merge. + +Use at most three connector feedback passes per PR by default, including the +initial review and re-reviews after fixes. A review repeated only because the +candidate identity changed without producing feedback does not consume this +feedback budget. If the final allowed pass still reports a material in-scope +finding, keep the PR and epic open, report the remaining finding, and request +direction. Do not spend connector passes on feedback already classified as +incorrect, outside scope, polish, or hypothetical hardening. + +## Checks and merge + +- Read required GitHub Actions checks directly. +- Continue monitoring pending required checks; ordinary check execution is not a + blocker requiring user input. +- Inspect failed required checks and their logs. Distinguish an in-scope + regression from an infrastructure, dependency, or external-service failure. +- Fix only demonstrated in-scope failures, rerun affected and required local + validation, push the fix, and restart every current-head connector and check + gate. +- Report unavailable external checks without weakening or bypassing the gate. +- If the repository has no branch checks, state that explicitly and use the + documented local and review gates. +- Immediately before merge, re-read the base SHA. If it differs from the base + used for validation or review, build an up-to-date merge candidate and rerun + applicable local validation, CI, adversarial review, human review, connector + review, and feedback disposition. When a review system cannot bind evidence to + an unchanged head plus a new base, update the branch so the new candidate has + a reviewable head SHA. +- Use the repository's approved merge method. +- If local worktree ownership prevents the CLI from switching to the base + branch, merge through GitHub's API and perform local cleanup separately. + +After merge, verify PR state, merge commit or squash result, and base-branch +content before deleting the branch. Verify issue transition or closure through +the adapter for the owning tracker; do not assume GitHub owns it. + +## Epic closeout when GitHub owns issue state + +Read back native relationships. Close the epic only when required sub-issues are +closed, no blocker remains, every required closed-blocker outcome is satisfied, +and epic-level behavior is verified. Do not infer completion solely from merged +PR count or a canceled/not-planned issue state. diff --git a/skills/implement-epic-sequence/references/linear.md b/skills/implement-epic-sequence/references/linear.md new file mode 100644 index 0000000..200f78b --- /dev/null +++ b/skills/implement-epic-sequence/references/linear.md @@ -0,0 +1,54 @@ +# Linear execution adapter + +Use live Linear issue relationships and current repository evidence to execute +epics whose planning source lives in Linear. + +## Preflight + +- Read the parent or epic and its current project context. +- List current children and inspect explicit blocking relationships. +- Read linked design documents, comments, and prior implementation PRs when they + affect scope. +- Search for completed, canceled, duplicate, or superseding issues before + selecting work. +- Resolve the code repository and its local instructions independently from + Linear. + +Do not use list order, priority labels, or an old prompt as dependency order +when explicit relations are available. + +## Selecting work + +Select an open child with no unresolved blocker and one PR-sized outcome. Verify +every required outcome from a completed, canceled, or superseded blocker in its +authoritative repository, artifact registry, tracker, or environment. For +same-repository code, verify the result on the base. For cross-repository or +operational prerequisites, also verify that the consumer uses the required +contract, version, configuration, approval, or environment state. Treat a +canceled or not-planned blocker with an unmet outcome as unresolved. Confirm +that the child is not already represented by a merged or open PR. Re-read the +parent after every merge or status transition because sibling readiness may have +changed. + +If Linear's relationship model cannot express a required dependency, record the +limitation in the issue and execution report. Do not silently treat prose as +equivalent to a native blocker. + +## Scope and PR linkage + +- Treat the live Linear issue body as the child scope contract. +- Preserve exact product rules such as timing, timezone, idempotency, skip, + unavailable, and migration behavior. +- Use the repository's required Linear reference in the branch, commit, and PR + body. +- Keep one child per PR unless the user explicitly changes the decomposition. +- Update Linear status only when the corresponding workflow state has actually + been reached. + +## Closeout + +After merge, verify the code is represented on the base branch and update the +child according to the team's Linear workflow. Close the parent only after all +required children, required closed-blocker outcomes, and parent-level acceptance +criteria are satisfied. Preserve explicitly deferred or canceled scope in the +final report; do not count an unmet canceled outcome as complete. diff --git a/skills/implement-epic-sequence/references/review-and-merge-gates.md b/skills/implement-epic-sequence/references/review-and-merge-gates.md new file mode 100644 index 0000000..570e9df --- /dev/null +++ b/skills/implement-epic-sequence/references/review-and-merge-gates.md @@ -0,0 +1,133 @@ +# Review and merge gates + +Use these gates for every implementation PR. Repository instructions may add +stricter requirements but must not silently weaken them. + +## Contents + +- [Bounded review loop](#bounded-review-loop) +- [Revalidation](#revalidation) +- [Base-drift gate](#base-drift-gate) +- [Merge gate](#merge-gate) +- [Feedback that should not expand the PR](#feedback-that-should-not-expand-the-pr) + +## Bounded review loop + +After implementation and required local validation, require one fresh, read-only +adversarial review using `code-review-pro` in a separate review-only subagent or +equivalent isolated context unless the user explicitly waives independent review +or independent review tooling is unavailable. Use a fresh or minimally inherited +context containing only raw task artifacts. Exclude the implementation +transcript, intended answer, prior conclusions, and suspected findings. Do not +silently treat unavailability as a passed independent-review gate. + +Before review, require every intended ticket change to be committed and the +implementation worktree to be clean. If unrelated user artifacts prevent a clean +state, classify and preserve them and prove they are irrelevant to the +candidate. + +Before delegation, capture HEAD, commit history, and tracked, untracked, and +ignored worktree state. After the reviewer returns, verify that all remain +unchanged. Treat any mutation as an integrity failure, inspect it, and preserve +user work rather than resetting or deleting it. + +Give the reviewer: + +- the live ticket and acceptance criteria; +- every named architecture, design, contract, migration, and rollout document; +- the exact captured head and base SHAs and their complete `base...HEAD` diff, + not only the latest commit; and +- exact focused and full validation evidence, including unavailable checks. + +Require the reviewer to inspect correctness, acceptance coverage, regressions, +failure paths, security, authorization boundaries, architecture, public surface +area, tests, documentation, and scope. Classify each finding as: + +- must fix now: correctness, security, acceptance, architecture, or validation + failure; +- obvious low-cost correctness or safety improvement: addresses demonstrated + current risk without widening scope; +- already satisfied or incorrect; +- valid but outside the ticket; +- blocked by a missing product decision. + +Apply only the first two categories. Reply with evidence for rejected findings. +When authorized, create a focused follow-up only for a real, evidenced gap. +Apply cognitive-load refactoring only when the user explicitly requests it or +when it is necessary to make the ticket's correctness evident. Do not use +reviewer convenience alone to expand the active PR. + +Run a fresh pass after material fixes so the review covers the resulting diff. +Use at most three adversarial passes by default. A clean pass ends the loop. If +the third pass still reports a material finding, do not merge; report the +remaining issue and request direction. Do not spend passes on style, polish, +hypothetical hardening, or future compatibility. + +When independent review tooling is unavailable, record why, perform a fresh +adversarial self-review using the same inputs and coverage, and proceed only if +repository policy does not require independence and the user has accepted or +already authorized this fallback. + +## Revalidation + +After every fix cycle: + +- run affected focused tests; +- rerun the repository-required gate; +- commit every intended ticket change and confirm that no uncommitted ticket + work is absent from `base...HEAD`; +- push the updated head; +- capture the current head and base SHAs; +- re-read current-candidate review and check state. + +Do not carry an older clean review signal across any head change, including a +push, rebase, conflict resolution, or update-branch operation, or across a base +advance that changes the merge candidate. + +## Base-drift gate + +Bind validation, CI, adversarial review, required human approval, connector +review, and feedback disposition evidence to the captured head and base SHA +pair. Immediately before merge, re-read both SHAs. + +When the base changed, build an up-to-date merge candidate and rerun applicable +local validation, CI, adversarial review, human review, connector review, and +feedback disposition. For required human approval, require proof that it was +submitted for the captured pair or request fresh approval after capturing the +new pair. When rebasing, merging, conflict resolution, or update-branch changes +the head, restart every current-head gate. When a review system cannot bind a +fresh verdict to an unchanged head plus a new base, update the branch so the +candidate receives a new reviewable head SHA. + +## Merge gate + +Require all applicable conditions: + +- every intended ticket change is committed and represented by the candidate + diff, with any unrelated artifacts classified, preserved, and proven + irrelevant; +- local focused and full validation passed; +- required remote checks passed; +- no undispositioned actionable conversation comment, formal review, connector + feedback, or review thread remains; +- every applicable required adversarial, human, and connector review has a clean + or approving verdict explicitly tied to the exact current head and base SHA + pair; +- no merge conflict or superseding PR exists; +- the diff still satisfies one ticket and its non-goals; +- rollout or migration prerequisites required before merge are complete. + +CI success alone is not a clean review. A stale approval alone is not a clean +review. If the repository has no CI, record that fact and require its documented +local and review signals. + +## Feedback that should not expand the PR + +Keep these out unless the live ticket requires them: + +- speculative pre-release backfills; +- support for nonexistent legacy data; +- broad refactors unrelated to correctness; +- defensive abstraction without demonstrated duplication; +- product polish or future-hardening suggestions; +- changes owned by another epic.