Sprint Planning

This skill enacts the Endogenous-First axiom from MANIFESTO.md: before proposing any new sprint, the agent reads the full open-issue backlog, existing milestones, and prior workplans — so the sprint is scaffolded from known committed context, not invented interactively. Sprint planning discipline is governed by AGENTS.md § Sprint Phase Ordering Constraints and § Agent Communication → docs/plans/. When this skill and those documents conflict, the primary documents take precedence.

Canonical workplan template: docs/plans/2026-03-08-value-encoding-fidelity.md

Beliefs & Context

This skill implements the sprint-planning workflow as a repeatable procedure for the Executive PM and Executive Planner.

Used by:

• Executive PM — owns milestone creation, issue assignment, label taxonomy
• Executive Planner — owns phase decomposition and workplan authoring
• Executive Orchestrator — delegates when user requests "plan the next sprint"

Foundation documents:

• AGENTS.md — sprint ordering constraints and commit discipline
• docs/guides/github-workflow.md — labels, milestones, gh CLI patterns
• docs/plans/ — prior workplans as canonical templates
• data/labels.yml — canonical label taxonomy

1. When to Use This Skill

Use this skill when:

2. Read the Current State

Step 2a — Scratchpad

ls .tmp/
# Read today's scratchpad if it exists

Step 2b — Open Issues

# All open issues with labels, milestone, body
gh issue list --state open --limit 100 \
  --json number,title,labels,milestone,body,createdAt,updatedAt \
  | jq '.[] | {number, title, labels: [.labels[].name], milestone: .milestone.title, age_days: ((now - (.createdAt | fromdateiso8601)) / 86400 | floor)}'

Step 2c — Milestone Overview

gh milestone list --state open
gh milestone list --state closed --limit 5

Step 2d — Recent Merged PRs (since last sprint)

git --no-pager log --oneline --merges -20

Step 2e — Prior Workplans

ls -lt docs/plans/ | head -10

Read the most recent docs/plans/*.md to understand the prior sprint's scope and what carried over.

3. Cluster and Classify the Backlog

Write a ## Sprint Planning Backlog section in the scratchpad. For each open issue:

Cluster taxonomy (assign one per issue):

Priority signals:

• priority:critical / priority:high → must-have for this sprint
• priority:medium → include if sprint capacity allows
• priority:low / no priority → candidates for backlog milestone

4. Propose the Sprint

Write a ## Sprint Proposal — <Sprint Name> section in the scratchpad.

Sprint Name Convention

Sprint NNN — <theme> (<YYYY-MM-DD>)

Where NNN is the next sequential sprint number derived from existing milestones:

gh milestone list --state all --json title | jq '.[].title' | grep -i sprint | sort | tail -1

Sprint Proposal Template

## Sprint Proposal — Sprint NNN — <theme>

**Target start**: <date>
**Target end**: <date (typically 2 weeks)>
**Capacity**: <S/M/L — rough estimate of available effort>

### Must-Have (priority:high or priority:critical)
| # | Title | Type | Effort | Cluster |
|---|-------|------|--------|---------|
| #N | ... | ... | ... | ... |

### Should-Have (priority:medium, fits capacity)
| # | Title | Type | Effort | Cluster |
|---|-------|------|--------|---------|
| #N | ... | ... | ... | ... |

### Defer to Backlog
| # | Title | Reason |
|---|-------|--------|
| #N | ... | priority:low / blocked / out of scope |

### Sprint Total Effort: <XS×N + S×N + M×N ...>

### Milestone Name: Sprint NNN — <theme>

### Workplan slug: sprint-NNN-<theme-slug>

Capacity Guidelines

5. Apply Labels and Milestone

After the proposal is reviewed (self-loop or human confirmation), apply changes:

# Create the sprint milestone
gh milestone create --title "Sprint NNN — <theme>" --due-date "<YYYY-MM-DD>"

# Assign issues to milestone
gh issue edit <number> --milestone "Sprint NNN — <theme>"

# Apply missing labels
gh issue edit <number> --add-label "priority:high,type:feature,area:scripts"

Pre-use validation before each gh issue edit:

gh issue view <number> --json number,title,labels,milestone | jq '{number, title, labels: [.labels[].name], milestone: .milestone.title}'

Verify-after-act:

gh issue list --milestone "Sprint NNN — <theme>" --json number,title,labels

6. Scaffold the Workplan

Once the milestone is confirmed, scaffold a workplan:

uv run python scripts/scaffold_workplan.py sprint-NNN-<theme-slug> \
  --issues "<comma-separated issue numbers>" \
  --ci "Tests,Auto-validate"

The scaffolded workplan is at docs/plans/YYYY-MM-DD-sprint-NNN-<theme-slug>.md.

Open it and fill in:

1. Objective section — one paragraph describing the sprint arc
2. Phase Plan — one phase per cluster (not per issue); assign agents and deliverables
3. Acceptance Criteria — what "sprint complete" means (all issues closed, CI green, CHANGELOG updated)

Commit the workplan before execution begins:

git add docs/plans/YYYY-MM-DD-sprint-NNN-<theme-slug>.md
git commit -m "docs(plans): scaffold Sprint NNN workplan"

7. Close the Planning Session

After the workplan is committed:

1. Write a ## Sprint Planning Summary section in the scratchpad.
2. Post a comment on each selected must-have issue with:

   Added to Sprint NNN — <milestone name>. Workplan: docs/plans/YYYY-MM-DD-sprint-NNN-<slug>.md

3. Return to Executive Orchestrator with the sprint proposal.

Completion Criteria

Sprint planning is done when:

• All open issues have at least one type: and one priority: label
• A sprint milestone exists for the proposed sprint
• All must-have issues are assigned to the sprint milestone
• Defer-to-backlog issues have backlog milestone or priority:low label
• docs/plans/YYYY-MM-DD-sprint-NNN-<slug>.md is committed
• Scratchpad contains ## Sprint Proposal and ## Sprint Planning Summary sections
• Each selected issue has a sprint-assignment comment
• Verify-after-act passes: gh milestone list --state open shows the new sprint

Anti-Patterns