Immutable. This exact content is served forever at /api/v1/blob/b29e5f0dcf69e974.
---
name: goal-to-release
description: Orchestrate issue-backed goals from ambiguous request to shipped release with ledgers, adaptive PR graphs, preflight gates, review loops, deploy evidence, closeout audits, and retrospectives. Use for multi-issue/product/platform/maintenance goals, GitHub issue/PR planning, stacked or parallel branches, release babysitting, or goal handoff. Skip isolated fixes unless they need release planning.
---
# Goal to Release
Turn broad goals into issue-backed, reviewable, verified releases. Own
sequencing, evidence, review hygiene, and closeout. Route concrete domain work
to narrower skills instead of duplicating their mechanics.
## Operating Model
Use live evidence first: repo instructions, worktree, branch, open issues, PRs,
review threads, CI, deploy state, docs, scripts, and recent reviewer feedback.
Treat memory and prompt history as leads to verify when facts can drift.
Keep a working goal ledger. Use working notes for short, single-PR work. Use a
durable ledger by default when the goal spans multiple issues/PRs, stacked or
parallel branches, repo-wide modernization, dependency upgrades, release
orchestration, cross-session execution, or any user-requested handoff. Then use
`scripts/new_goal_ledger.py` to create an isolated untracked goal directory.
Read [goal-ledger-lifecycle.md](references/goal-ledger-lifecycle.md) before
creating, auditing, distilling, or handing off durable ledgers.
If live inspection is forbidden, produce a provisional ledger and mark
unverified live facts as `TBD` or `UNVERIFIED`.
Modes:
- `plan-only`: issue/PR/release plan only.
- `preflight`: discover repo surfaces, gates, risks, and PR-readiness before
implementation or publication.
- `implement`: build one or more lanes.
- `monitor`: babysit hosted CI/reviews/deploys.
- `closeout`: prove issues, PRs, docs, deploys, evidence, and summaries are
complete.
- `retrospective`: extract reusable workflow lessons.
## Core Workflow
1. **Ground**
- Read repo instructions and relevant docs/code first.
- Inspect worktree and branch state; preserve unrelated dirty work.
- If user edits are unrelated, keep them out of staging and commits. If they
overlap files you must touch, inspect the exact diff and adapt around it;
use a separate branch/worktree when that is the cleanest safe path. Never
stash, discard, reset, or rewrite user work without explicit approval.
- Identify existing issues, branches, PRs, reviews, checks, deployments, and
goal ledgers before creating new ones.
2. **Charter**
- State objective, non-goals, success criteria, release/deploy boundary, and
user steering.
- If the goal is larger than one reviewable PR, create or update one issue
per coherent lane.
- Reorder lanes when evidence shows a force multiplier; record the rationale
in the ledger and issue/PR text.
3. **Preflight**
- For nontrivial lanes, run or reason through `scripts/goal_preflight.py`.
- Build a repo-adapted gate plan from discovered surfaces, not a generic
checklist.
- Read [preflight-gates.md](references/preflight-gates.md) for conditional
gates and evidence expectations.
4. **Plan the PR graph**
- Default to serial PRs for coupled work.
- Use parallel or stacked PRs only when lanes are independent or explicitly
ordered.
- Every stack records base branch, dependency, retarget plan, validation
scope, and merge order.
- For stacked work, open each PR against its immediate base branch. Merge the
root PR first, then retarget or rebase the next PR onto the new target
branch, refresh hosted checks/reviews, and only then merge the next stack
layer.
5. **Research and decide**
- Use current official docs, source, package repos, or deployed behavior for
dependency, platform, API, deploy, security, and architecture choices.
- Score meaningful choices when the decision is not obvious.
- Encode durable decisions in issues, PR bodies, ADRs, specs, or docs.
6. **Implement lanes**
- Keep the active branch narrow and semantic.
- Hard-cut obsolete paths when the goal requires entropy reduction.
- Update tests, docs, fixtures, generated metadata, and runbooks that are
part of the changed contract.
- Do not absorb adjacent redesigns silently; split them into follow-up
issues or lanes.
7. **Verify before PR publication**
- Run focused checks while iterating.
- Before opening a nontrivial PR, run repo-native gates required by touched
surfaces and mandatory bounded subagent review.
- Record exact local command outcomes separately from hosted CI and deploy
proof.
8. **Ship and monitor**
- Commit by semantic intent; do not stage unrelated files.
- PR bodies include linked issue, summary, validation, docs impact,
deploy/provider notes, screenshots when relevant, and residual risks.
- Read [review-and-merge-loop.md](references/review-and-merge-loop.md) when
opening, updating, or merging PRs.
- Refetch live hosted review threads after every push. Fix valid comments,
rebut stale or suboptimal comments with evidence, resolve addressed
threads, and wait for fresh checks/reviews.
9. **Close out**
- Verify issues, PRs, branches, docs, deploys, review decisions, unresolved
review threads, and follow-ups from live sources.
- If deploy evidence is not applicable, record the exact reason instead of
leaving deploy state blank.
- Run `scripts/audit_goal_ledger.py --strict` for durable ledgers.
- When a durable goal is achieved, run `scripts/distill_goal_summary.py` so
future agents can load `summary.md` or `summary.json` before raw ledgers.
10. **Retrospect**
- Summarize shipped changes, decisions, user steering, validation, deploy
evidence, and reusable workflow lessons.
- Generalize only repeated cross-repo patterns into skills. Repo-specific
lessons belong in repo docs, issues, PRs, or AGENTS guidance.
## Skill Routing
Use narrower skills just in time:
- `$dependency-upgrade` plus package-manager/Turborepo skills for dependency
modernization, release notes, lockfiles, and package graph risk.
- `$subspawn` for bounded independent sidecars and pre-PR expert review.
- `$commit` for semantic staging and commits.
- `$babysit-pr` for hosted PR monitoring.
- `$repo-docs-align` for source-of-truth docs reconciliation.
- `$hard-cut`, `$reducing-entropy`, `$clean-code`, security, web, Rust, Vercel,
or repo-specific skills when the active lane touches those domains.
Do not load or restate those skills before their lane needs them.
## Stop Conditions
Stop and ask only when proceeding risks data loss, secrets exposure, production
impact without approval, destructive git history, or an ambiguous public/API
contract break. Otherwise make a reasonable decision, document evidence, and
continue.
## Failure Modes To Guard
- **Review-reactive churn**: run preflight and subagent review before PRs.
- **Scope ballooning**: split adjacent redesigns into follow-up lanes.
- **Stale hosted state**: refetch reviews/checks after every push.
- **False closeout**: audit the ledger and live sources before claiming done.
- **Ledger archaeology**: distill achieved goals into `summary.md` and
`summary.json`.
- **Over-delegation**: keep critical path and final synthesis local.
- **Plan fossilization**: update issues, PRs, and docs when reality changes.