Issue Slice Autopilot

Drive a complex issue to completion across multiple PRs with minimal or no user intervention.

This skill is for long-running tasks where one giant PR is too risky. It repeatedly:

1. selects the largest sane slice with no overlap with in-flight work,
2. implements and validates the slice,
3. runs $commit-and-push,
4. runs $enter-merge-queue until merged,
5. refreshes state and repeats.

Core Rules

• Keep exactly one active PR at a time.
• Always avoid overlap with open PRs touching the same area.
• Prefer the largest independent slice that has clear done criteria.
• Do not leave a slice half-shipped; either finish it or skip it for now.
• After each merged PR, re-evaluate the issue from current main.
• Stop only when issue completion criteria are met, or progress is blocked.

State (Required)

Persist state in git-ignored workspace state so the loop can resume after refreshes/restarts:

ISSUE_NUMBER="<issue-number>"
STATE_DIR=".git/issue-slice-autopilot"
STATE_FILE="$STATE_DIR/issue-${ISSUE_NUMBER}.json"
mkdir -p "$STATE_DIR"

State shape:

{
  "issue_number": 2540,
  "repo": "owner/repo",
  "iteration": 0,
  "completed_slices": [],
  "skipped_slices": [],
  "active_pr": null,
  "last_merged_pr": null,
  "blocked_reason": null,
  "updated_at": "<iso>"
}

Update this file at the end of each major phase.

Phase 1: Issue Recon

1. Resolve repo and load issue:

REPO=$(./scripts/agents/tooling/agentTool.ts getRepo)
gh issue view "$ISSUE_NUMBER" -R "$REPO" --json number,title,body,state,url

Issue Format Normalization

After loading the issue, check whether its body is already in autopilot-friendly format. An autopilot-friendly issue has:

• A ## Requirements section (or equivalent heading like ## Tasks, ## Checklist) with - [ ] checkbox items
• Each requirement is clear, testable, and independently implementable
• Enough granularity to decompose into slices

Skip normalization if the issue already has a requirements-style section with at least two - [ ] items.

If the issue body lacks structured requirements (e.g., plain prose, a single paragraph, or non-checkbox bullets), rewrite the body into autopilot-friendly format before proceeding:

1. Parse the existing body to extract intent, scope, and individual work items.

2. Rewrite into this structure:

   ## Summary
   <one paragraph describing the goal and outcome>
   
   ## Context
   <why this matters, impacted area, constraints>
   
   ## Requirements
   - [ ] <clear, testable requirement 1>
   - [ ] <clear, testable requirement 2>
   - [ ] ...
   
   ## Implementation Notes
   <initial approach, dependencies, or open questions>
   

3. Preserve the original issue body at the bottom under a collapsed details block:

   <details>
   <summary>Original issue body</summary>
   
   <original body here>
   
   </details>
   

4. Update the issue on GitHub:

   gh issue edit "$ISSUE_NUMBER" -R "$REPO" --body "$NEW_BODY"
   

Overlap Context

1. Build non-overlap context from open PRs:

gh pr list -R "$REPO" --state open --json number,title,headRefName

For each open PR, collect changed files:

gh pr view <pr> -R "$REPO" --json files --jq '.files[].path'

1. Collect prior merged work linked to the issue (for dedupe):

gh pr list -R "$REPO" --state merged --search "#${ISSUE_NUMBER} in:body" --json number,title,mergedAt

1. Convert issue requirements into a slice backlog. Each slice needs:

• name
• scope
• candidate_files
• done_criteria
• validation_commands
• risk_level
• estimated_size

Phase 2: Slice Selection

Score candidates by:

score = size + independence + impact - overlap_risk - migration_risk

Selection rules:

1. Exclude slices whose candidate_files overlap with any open PR files.
2. Exclude slices with unclear done criteria.
3. Prefer slices that:

• remove legacy paths/endpoints,
• remove proxy layers,
• remove obsolete dependencies,
• unlock later deletions.

1. Pick the highest scoring remaining slice.

If no non-overlapping slice exists, set blocked_reason and stop.

Phase 3: Implement Slice

1. Ensure clean base:

git checkout main >/dev/null
git pull --ff-only >/dev/null

1. Create implementation branch for this slice.
2. Implement fully with tests.
3. Run focused validation first, then broader required checks.

If coverage or quality gates fail, add tests before commit. Do not lower thresholds.

Phase 4: Ship Slice

After implementation is complete and local validation passes:

1. Invoke $commit-and-push.
2. Invoke $enter-merge-queue.
3. Wait for merge completion (handled by $enter-merge-queue).

Do not start the next slice until merge is confirmed.

Phase 5: Post-Merge Update

1. Refresh workspace (normally handled by $enter-merge-queue).
2. Confirm current branch is main and clean.
3. Append merged PR metadata to completed_slices.
4. Increment iteration.
5. Re-run Phase 1 recon against latest code.

Repeat Phases 2-5 until done.

Completion Conditions

Mark complete when all are true:

• Issue checklist items are satisfied in code.
• No remaining runtime references to removed legacy paths/proxy helpers (except explicitly allowed exceptions).
• Required builds/tests pass for touched packages.
• No additional non-overlapping high-value slice remains.

Blocked Conditions

Stop and report when any occurs:

• No non-overlapping slices remain while open PRs are still active.
• A required slice repeatedly fails CI 3 times after fixes.
• Merge conflicts require ambiguous tradeoffs and cannot be resolved safely.
• The issue requires user product decisions that cannot be inferred.

Anti-Patterns (Never)

• Do not bundle unrelated cleanup into one slice.
• Do not open multiple active PRs for one issue in parallel.
• Do not reply to review threads referencing unpushed commits.
• Do not skip validation gates to keep momentum.
• Do not use auto-close keywords in PR bodies.

Recommended Loop Skeleton

LOAD/INIT STATE
RECON ISSUE + PR OVERLAP
WHILE NOT COMPLETE:
  SELECT LARGEST NON-OVERLAPPING SLICE
  IMPLEMENT + TEST
  RUN $commit-and-push
  RUN $enter-merge-queue
  REFRESH + UPDATE STATE
FINAL ISSUE COMPLETION REPORT

Issue #2540 Mapping Heuristic

For #2540-like migrations, prefer this order:

1. Remaining deproxy service slices with strongest boundaries.
2. Legacy routing/unmount deletion once deproxy dependencies are removed.
3. Client wrapper/type migration cleanup.
4. Final dependency removals and dead-code deletion.

Always re-check overlap against currently open PRs before each slice.

Output Contract Per Iteration

For each slice, report:

• selected slice name and rationale,
• overlap check result,
• PR number/URL,
• merge result,
• remaining backlog.

At final completion, report:

• all merged PRs in order,
• what issue requirements were completed in each,
• any intentionally deferred follow-ups.