Plot: Sprint

Sprints are not plans. Plans track what to build; sprints track when to ship it. Sprint files live in docs/sprints/, committed directly to main — no PR, no review gate. Principle 2 ("Plans merge before implementation") does not apply to sprints.

Input: $ARGUMENTS determines the subcommand.

Form	Action
`/plot-sprint`	Status (infer slug or list all)
`/plot-sprint <slug>`	Status of slug (or create if not found)
`/plot-sprint <slug> commit`	Lock sprint contents
`/plot-sprint <slug> start`	Begin the sprint
`/plot-sprint <slug> close`	End timebox, capture retro
`/plot-sprint <slug> add/remove/reprio`	Change sprint scope (see Scope Change)
`/plot-sprint <slug>: <goal>`	Create slug with goal

Argument parsing: $ARGUMENTS = [<slug>] [<subcommand>] [<args>]

$ARGUMENTS[0] → slug (first word, if present)
$ARGUMENTS[1] → subcommand: commit, start, close
Create detected by : in slug token (e.g. week-1: Ship auth)
If no slug given: discover from docs/sprints/active/ — one active sprint → use it, multiple → list and ask, none → offer to create

Setup

Add a ## Plot Config section to the adopting project's CLAUDE.md:

## Plot Config
- **Project board:** <your-project-name> (#<number>)  <!-- optional, for `gh pr edit --add-project` -->
- **Branch prefixes:** idea/, feature/, bug/, docs/, infra/
- **Plan directory:** docs/plans/
- **Active index:** docs/plans/active/
- **Delivered index:** docs/plans/delivered/
- **Sprint directory:** docs/sprints/

Model Guidance

Steps	Min. Tier	Notes
Create, commit, start, status	Small	Git commands, templates, file ops
Close	Mid	Checkbox parsing + reading plan files to check delivery status of `[slug]` refs

All sprint operations are structural (Small or Mid). No Frontier needed.

Sprint Lifecycle

flowchart LR
    A["/plot-sprint<br/><slug>: <goal>"] -->|"⏸ drafting"| B["Planning"]
    B -->|"⏳ /plot-sprint commit"| C["Committed"]
    C -->|"⚡ /plot-sprint start"| D["Active"]
    D -->|"⏳ /plot-sprint close"| E["Closed"]

Legend: ⚡ automate ASAP · ⏸ natural pause · ⏳ human-paced

Guardrail

Sprint files must not contain ## Design or ## Approach sections. If detected, warn: "This looks like a plan, not a sprint. Use /plot-idea for plans."

Subcommands

Create: `/plot-sprint <slug>: <goal>`

Create a new sprint in Planning phase.

Pacing: ⏸ natural pause (drafting)

1. Parse Input

Extract <slug> (before the colon) and <goal> (after the colon). Both are required.

Slug: trimmed, lowercase, hyphens only
Goal: the sprint goal as a sentence

If no colon or missing parts: "Usage: /plot-sprint <slug>: <goal>"

2. Determine ISO Week Prefix

Derive the ISO week prefix from today's date for the filename:

WEEK_PREFIX=$(date -u +%Y-W%V)

The sprint file will be named docs/sprints/${WEEK_PREFIX}-<slug>.md.

3. Pre-flight Checks

ls docs/sprints/${WEEK_PREFIX}-<slug>.md 2>/dev/null

If file exists: "Sprint <slug> already exists for week ${WEEK_PREFIX}."

4. Discover Active Plans

List active plans so the user can add them to the sprint:

ls docs/plans/active/ 2>/dev/null

If plans exist, present: "Found N active plans. Add any to this sprint?" List them and let the user select which to include (or none). Selected plans are added as [slug] items under the appropriate MoSCoW tier.

5. Create Sprint File

mkdir -p docs/sprints

Write docs/sprints/${WEEK_PREFIX}-<slug>.md using the template from skills/plot/templates/sprint.md, substituting <title> and <sprint goal>.

Item format: - [ ] [slug] description (plan reference) or - [ ] description (lightweight task).

Item Annotations

Plan-backed items carry HTML comment annotations for automation tracking:

- [ ] [slug] description <!-- pr: #N, status: draft, branch: feature/slug -->

Field	Set by	Values
`pr`	`/plot-approve`	PR number (`#N`) or `none`
`status`	`/plot-approve`, `/plot-deliver`	`not-started`, `draft`, `open`, `merged`
`branch`	`/plot-approve`	Implementation branch name
`reviewed_at`	Review tracking	ISO 8601 timestamp
`review_sha`	Review tracking	HEAD SHA at time of review

Annotations are created by /plot-approve and updated by /plot-deliver. The status subcommand reads them for enriched output.

Review Tracking

The review_sha annotation enables skip-if-unchanged review:

Compare current HEAD SHA of the PR branch to the review_sha in the annotation
If same → no new commits since last review, skip
If different → new commits, needs re-review
If status is merged → never needs review

Use skills/plot/scripts/plot-review-status.sh <sprint-slug> to get review freshness for all sprint items as JSON.

Leave Start/End dates as placeholders — the user fills them during the Planning phase.

6. Update Plan Files

For each plan-backed item ([slug]) added in step 4, update the referenced plan file to record sprint membership:

Resolve the plan file via docs/plans/active/<slug>.md
Add - **Sprint:** <sprint-slug> to its ## Status section (after the Phase line)

This enables sprint awareness in /plot-approve and /plot-deliver.

7. Commit to Main

Sprint files are committed directly to main (include any updated plan files):

git add docs/sprints/${WEEK_PREFIX}-<slug>.md docs/plans/
git commit -m "sprint: create <slug>"
git push

8. Summary

Print:

Created: docs/sprints/${WEEK_PREFIX}-<slug>.md
Sprint: [*] Planning > [ ] Committed > [ ] Active > [ ] Closed
Plan files updated: N (if any)
Next: add items, set dates, then /plot-sprint <slug> commit when ready

Commit: `/plot-sprint <slug> commit`

Lock sprint contents. Team has agreed on what's in scope.

Pacing: ⏳ human-paced (team agreement)

1. Find Sprint File

ls docs/sprints/*-<slug>.md 2>/dev/null

If not found: "No sprint found for <slug>."

Read the sprint file. Check Phase field:

If not Planning: "Sprint is in <phase> phase, not Planning. Cannot commit."

2. Validate End Date

Check that the **End:** field has a real date (not the placeholder YYYY-MM-DD).

If missing or placeholder: "Set an end date before committing. Edit the sprint file directly."

3. Update Phase

Change **Phase:** Planning → **Phase:** Committed

4. Commit

git add docs/sprints/*-<slug>.md
git commit -m "sprint: commit <slug>"
git push

5. Summary

Print:

Committed: <slug>
Sprint: [ ] Planning > [x] Committed > [ ] Active > [ ] Closed
End date: <end date>
Items: N must-haves, N should-haves, N could-haves
Next: /plot-sprint <slug> start when the sprint begins

Start: `/plot-sprint <slug> start`

Begin the sprint. Creates the active symlink.

Pacing: ⚡ automate ASAP (mechanical transition)

1. Find and Validate Sprint File

Find sprint file, check Phase is Committed.

2. Create Active Symlink

mkdir -p docs/sprints/active
ln -s ../${WEEK_PREFIX}-<slug>.md docs/sprints/active/<slug>.md

3. Update Phase

Change **Phase:** Committed → **Phase:** Active

4. Commit

git add docs/sprints/*-<slug>.md docs/sprints/active/<slug>.md
git commit -m "sprint: start <slug>"
git push

5. Summary

Print:

Started: <slug>
Sprint: [ ] Planning > [ ] Committed > [x] Active > [ ] Closed
End date: <end date>
Active symlink: docs/sprints/active/<slug>.md
Next: work on sprint items. When timebox ends, /plot-sprint <slug> close

Close: `/plot-sprint <slug> close`

End the timebox. Check MoSCoW completeness and capture retrospective.

Pacing: ⏳ human-paced (retrospective)

1. Find and Validate Sprint File

Find sprint file, check Phase is Active.

2. MoSCoW Completeness Check

Parse the sprint file for checkbox items in each tier:

Count checked - [x] vs unchecked - [ ] items per tier
For plan-backed items ([slug]), check if the referenced plan is delivered (exists in docs/plans/delivered/)

Present results:

Must Have:  2/4 complete
Should Have: 1/2 complete
Could Have:  0/1 complete

If must-haves are incomplete, present three options:

Close anyway (must-haves stay unchecked in place)
Move incomplete must-haves to Deferred — move each unchecked - [ ] line from ### Must Have to ### Deferred, preserving the original text
Hold off (don't close yet)

3. Capture Retrospective

Ask the user: "Add a retrospective? (optional)"

If yes, prompt for:

What went well?
What could improve?
Action items for next sprint?

Fill the ## Retrospective section using the template from skills/plot/templates/retrospective.md. Include the Metrics subsection with actual counts from step 2.

4. Update Phase and Remove Symlink

Change **Phase:** Active → **Phase:** Closed

git rm docs/sprints/active/<slug>.md
git add docs/sprints/*-<slug>.md
git commit -m "sprint: close <slug>"
git push

5. Summary

Print:

Closed: <slug>
Sprint: [ ] Planning > [ ] Committed > [ ] Active > [x] Closed
Must-haves: N/M complete
Deferred: N items (if any moved)
Retrospective: captured / skipped
Suggested next actions:
1. Review the retrospective action items
2. Carry deferred items to the next sprint: /plot-sprint <new-slug>: <goal>
3. If all planned work is delivered: /plot-release to cut a release

Scope Change

Scope changes are allowed during Active (or Committed) sprints. All changes are logged in the sprint file's ## Notes > ### Scope Changes section for traceability.

Adding items mid-sprint:

Add the new - [ ] item to the appropriate MoSCoW tier
Log: - YYYY-MM-DD: Added [slug] to Must/Should/Could — <reason>
If plan-backed ([slug]), update the plan's Sprint field

Removing or deferring items:

Move the item to the ### Deferred section (do not delete — preserve history)
Log: - YYYY-MM-DD: Deferred [slug] from Must — <reason>

Changing MoSCoW tier:

Move the item between tier sections (e.g., Must → Should)
Log: - YYYY-MM-DD: Reprioritized [slug] Must → Should — <reason>

Commit scope changes directly to main with message: sprint: scope change <slug>.

Status: `/plot-sprint` or `/plot-sprint <slug>`

Show sprint status.

1. Resolve Slug

If slug provided ($ARGUMENTS[0] present, no subcommand):

Find sprint file: ls docs/sprints/*-<slug>.md 2>/dev/null
Found → show status for that sprint (step 2)
Not found → "No sprint <slug> found. Create it with /plot-sprint <slug>: <goal>"

If no arguments:

List active sprints: ls docs/sprints/active/ 2>/dev/null
One active sprint → use it, show status (step 2)
Multiple → list all active sprints with summary
None → "No active sprints. Create one with /plot-sprint <slug>: <goal>"

2. For Each Sprint

Read the sprint file and display:

Sprint name and goal
Phase
Time remaining (days until end date; "ended N days ago" if past)
MoSCoW progress: Must N/M, Should N/M, Could N/M
For plan-backed items with annotations: show PR number, status, and branch

3. Summary

## Active Sprints

- `<slug>` — "<goal>" | [*] Active | 3 days remaining | Must: 2/4 | Should: 1/2 | Could: 0/1

plot-sprint

Plot: Sprint

Setup

Model Guidance

Sprint Lifecycle

Guardrail

Subcommands

Create: /plot-sprint <slug>: <goal>

1. Parse Input

2. Determine ISO Week Prefix

3. Pre-flight Checks

4. Discover Active Plans

5. Create Sprint File

Item Annotations

Review Tracking

6. Update Plan Files

7. Commit to Main

8. Summary

Commit: /plot-sprint <slug> commit

1. Find Sprint File

2. Validate End Date

3. Update Phase

4. Commit

5. Summary

Start: /plot-sprint <slug> start

1. Find and Validate Sprint File

2. Create Active Symlink

3. Update Phase

4. Commit

5. Summary

Close: /plot-sprint <slug> close

1. Find and Validate Sprint File

2. MoSCoW Completeness Check

3. Capture Retrospective

4. Update Phase and Remove Symlink

5. Summary

Scope Change

Status: /plot-sprint or /plot-sprint <slug>

1. Resolve Slug

2. For Each Sprint

3. Summary

Create: `/plot-sprint <slug>: <goal>`

Commit: `/plot-sprint <slug> commit`

Start: `/plot-sprint <slug> start`

Close: `/plot-sprint <slug> close`

Status: `/plot-sprint` or `/plot-sprint <slug>`