Ship-It: End-to-End Code Preparation & PR Shipping Workflow

This skill guides agents through a rigorous, multi-step checklist before code is shipped out for peer review. It ensures high quality, high test coverage, clean public APIs, well-structured PR segmentation, comprehensive code documentation, up-to-date project documentation (README/CHANGELOG/design docs), and post-PR creation draft tracking.

Procedural Workflow Summary

Execute these 5 phases sequentially. When the a2ui-pane plugin is available (render_a2ui is reachable as a native or lazy MCP tool), read the genui skill and render a progress_board surface (mode: "pane", surfaceId: "ship-it-progress") at the start of Phase 1, updating its status rows ($/items = [...]) at each phase transition; skip silently when a2ui-pane is not installed:

1. Phase 1: PR Segmentation & Stacking Analysis (Pre-flight git status check, diff scope analysis, and stacked worktree proposals)
2. Phase 2: Per-Branch Static Analysis & Test Audit (Linter/analyzer gate, 90%+ coverage enforcement, and test quality audit)
3. Phase 3: Per-Branch Review Homeostasis Loop (Iterative subagent API & code reviews until clean)
4. Phase 4: Per-Branch Documentation Sync & PR Description (Code docs via code-documentation skill, README/CHANGELOG/design doc updates via write-prose skill, and PR description)
5. Phase 5: Post-PR Creation Draft Tracking & Feedback Handling (Prompt user to submit Draft PR, schedule CI/comment checks, handle feedback, and mark ready for review)

Phase 1: PR Segmentation & Stacking Analysis

1. Pre-flight Working Tree Check:
   • Run git status --porcelain to inspect untracked files and uncommitted working tree changes.
   • If uncommitted or untracked changes are found: Explicitly prompt the user (using your interactive question tool if available, or by presenting the options in chat and waiting for their reply, listing your recommended option first with (Recommended)) asking what to do with them (e.g. stage and commit them into the current branch, stash them, or include them in the diff scope calculation).
2. Evaluate Diff Scope:
   • Inspect git branch diff stat against base branch (e.g. git diff --stat main...HEAD), and then inspect the individual diffs in groups or per-file (git diff main...HEAD -- <files...>) for large changesets rather than pulling large raw diffs all at once, but do look at all the diffs.
   • Evaluate if the change should remain a single PR or be split into stacked PRs:
     • Total diff > 500 lines of code (excluding lockfiles/generated files)?
     • Contains distinct logical layers (e.g. refactoring vs. new feature vs. API extension)?
     • Touches unrelated modules requiring different domain reviewers?
3. If segmentation is needed:
   • Refer to pr_segmentation.md for criteria and stacking plan rules.
   • Generate a PR Stacking Plan Proposal artifact (pr_stacking_plan.md) outlining stacked branches, dedicated git worktree locations, and commands.
   • Present the proposed stacking plan to the user using the grill-me skill for alignment before executing worktree creation.
   • When tracking stacked PRs and the a2ui-pane plugin is available, read the genui skill and render a stack_board surface in the pane (surfaceId: "stack-board"). Push live row updates using data-only lines ($/items/N/state, $/items/N/tone, $/items/N/ci, $/items/N/ciTone, and $/items/N/step) as branches advance through static analysis, review, and CI.
4. If single PR is sufficient: Proceed directly to Phase 2 on the current branch.

Phase 2: Per-Branch Static Analysis & Test Audit

Execute on each branch/worktree in the stack:

1. Project & Language Auto-Detection:
   • Identify project type via manifest files (pubspec.yaml -> Dart/Flutter, pyproject.toml/setup.py -> Python, package.json -> Node/TS, Cargo.toml -> Rust, go.mod -> Go).
2. Pre-Test Linter & Analyzer Gate:
   • Run static analyzer / linter before executing tests to catch syntax or type errors early:
     • For Dart/Flutter: Use Dart MCP analyze_files tool.
     • For Python: Run ruff check / flake8 / mypy.
     • For TypeScript/Node: Run tsc --noEmit / npm run lint.
   • Fix all analyzer errors before proceeding to test execution.
3. Run Test Suite with Coverage:
   • For Python: pytest --cov
   • For Dart/Flutter: Dart MCP run_tests or flutter test --coverage
   • For TypeScript/Node: jest --coverage / npm test
4. Enforce 90%+ Coverage Target:
   • Add missing unit tests for uncovered lines or branch conditions until all modified/new files achieve >= 90% line and branch coverage.
5. Audit Test Quality:
   • Refer to test_quality_audit.md for quality dimensions (hermaticity, false positives, assertion precision, timing hygiene).
   • Ensure every bug fix introduced during the conversation has a dedicated, failing-before-fix regression test.
6. Cognitive Complexity Audit:
   • Run the cognitive-complexity analyzer on all modified or newly added source files to check for maintainability hotspots: python3 <skillsDir>/cognitive-complexity/scripts/cognitive_complexity.py <modified_files> --threshold 15 --verbose
   • If any new or modified functions exceed the threshold (score > 15), refactor them (e.g., using Extract Method or Guard Clauses) to reduce cognitive complexity before proceeding to review.

Phase 3: Per-Branch Review Homeostasis Loop

[!NOTE] ORDER DEPENDENCY: Execute the API Review Pass BEFORE deep Code Review. Settle public method signatures, class hierarchies, naming conventions, and parameter types first so internal code review is not wasted on implementation details that change during API refactoring.

Execute iterative review passes on the current branch/worktree:

1. API Review Pass:
   • Launch an isolated subagent (Workspace: "inherit") to perform a review following the api-review skill on modified public interfaces.
   • Implement recommended mitigations for findings across all severity levels (HIGH, MEDIUM, and objective LOW).
   • Commit clean state: git commit -m "refactor(api): apply API review mitigations".
2. Code Review Iterative Loop:
   • Refer to review_homeostasis.md for reviewer prompt templates, oscillation handling rules, and homeostasis criteria.
   • Run the code-review skill from the root session on the working directory diff. On Jetski root sessions (Tier 1), code-review spawns @rev-a via swarm and wakes the warm waiting worker via post_message + swarm_wait across homeostasis passes; when swarm is unavailable, it falls back to a self subagent (Workspace: "inherit").
   • Pin focus themes: On pass 1, let code-review run its focus triage (Step 2d). Record the theme ids it chose from the Summary flags line (--focus <id>), and pass the same --focus <id> flags (or --no-focus when none were chosen) on every later pass, so the theme set does not change between passes and triage runs once.
   • Parse findings (critical, high, medium, and low); Questions are answered, not fixed, and do not block homeostasis.
   • Apply fixes, run unit tests, and commit changes (git commit -m "fix(review): address review comments").
   • Oscillation Detection: If a finding touches lines previously modified in a prior review iteration, present the conflicting recommendations to the user via consequence_cards in genui (when a2ui-pane is available) or via your interactive question tool / chat prompt (waiting for their reply).
   • Homeostasis Reached: Stop looping when a review pass yields zero critical/high/medium/low findings (Questions do not count, or after max 5 iterations). Terminate any active swarm workers (swarm{action: "kill", name: "rev-a"} / "rev-b") and subagents (manage_subagents with Action 'kill_all') before proceeding to Phase 4 (Documentation Sync).

Phase 4: Per-Branch Documentation Sync & PR Description

[!NOTE] ORDER DEPENDENCY: Phase 4 MUST be executed AFTER Phase 3 Homeostasis is reached. Inline docstrings, README updates, and CHANGELOG entries must document finalized, refactored API signatures rather than intermediate or obsolete code.

[!IMPORTANT] PROSE WRITING STANDARDS All written prose (inline docstrings, README updates, CHANGELOG entries, design docs, commit messages, PR descriptions, and user reports) MUST strictly follow the plain language and anti-AI-ism guidelines in the write-prose skill.

1. Comprehensive Code-Level Documentation:
   • Audit 100% of newly added or modified public symbols (classes, methods, functions, types, constants, parameters).
   • Ensure comprehensive, high-quality inline documentation (docstrings / dartdocs / JSDoc / type hints) is written for all public APIs following the code-documentation skill guidelines.
2. Project, README, CHANGELOG & Design Documentation:
   • Check if CLI flags, configuration schemas, installation procedures, breaking changes, or public API usage changed.
   • Audit and update existing project documentation files (README.md, CHANGELOG.md, proposal/design RFC documents, package guides) using write-prose skill standards.
   • Missing README.md Detection: If no README.md exists in the component/package root and creating one would benefit the project, explicitly prompt the user (using your interactive question tool if available, or in chat and waiting for their reply) asking if they would like a new README.md generated.
3. Final Verification:
   • Run the full test suite one final time to verify all tests pass.
   • Commit documentation updates (git commit -m "docs: sync inline documentation, README, and CHANGELOG").
4. Summary & PR Description:
   • Output a concise summary to the user outlining coverage stats, review loop iterations completed, and stacking structure.
   • Automatically run the write-pr-description skill (which orchestrates with the write-prose skill) to generate the PR title and description artifact for submission.

Phase 5: Post-PR Creation Draft Tracking & Feedback Handling

Refer to post_pr_creation.md for detailed execution steps:

1. Prompt User for Draft Submission Approval: Present the generated PR description and request explicit permission to create the Draft PR on GitHub by rendering an inline confirm_gate via genui (when a2ui-pane is available) or prompting via your interactive question tool / chat (waiting for approval).
2. Submit Draft PR: Upon approval, push branch and run gh pr create --draft (following gh-cli skill).
3. 5-Minute CI & Feedback Schedule: Set a 5-minute schedule timer (schedule tool) to monitor CI status (gh pr checks) and review comments (analyze-github-pr script).
4. Feedback Resolution Selection: If CI fails or review comments exist, prompt the user (using your interactive question tool if available, or in chat and waiting for their reply, listing your recommended option first with (Recommended)):
   • Interactive Dashboard: Delegate to pr-feedback-handler skill (launch_dashboard.py).
   • Direct Fix & Respond: Fix findings directly, verify with unit tests, commit, push, and submit thread replies via pr-feedback-handler scripts (update_thread.py).
5. Mark Ready for Review: Once CI passes and feedback is clean, request approval via an inline confirm_gate in genui (when a2ui-pane is available) or via your interactive question tool / chat, and run gh pr ready to publish out of draft state.