bodangren/sprint-planner

Sprint Planner Skill

Purpose

To plan and initialize a new sprint by intelligently decomposing approved specifications into a comprehensive set of atomic GitHub issues. This skill bridges the gap between high-level specs and executable work items by using the Gemini CLI to analyze the spec's content and generate a thoughtful task breakdown. It then automates the creation of these tasks as GitHub issues within a new sprint milestone.

When to Use

Use this skill in the following situations:

• Starting a new sprint or development cycle.
• Converting an approved spec into actionable GitHub issues.
• When you want an AI-assisted breakdown of an epic into atomic implementation tasks.

Prerequisites

• Project board configured with an "Approved Backlog" status column.
• Approved spec files exist in the docs/specs/ directory.
• An Epic issue exists on GitHub that links to the spec file in its body.
• gh CLI tool installed and authenticated.
• jq tool installed for JSON parsing.
• gemini CLI tool installed and authenticated.

Workflow

Step 1: Review Project Board

Check the project board for approved specs (represented as Epics) ready to be planned.

Step 2: Discuss Sprint Scope with User

Engage the user to determine which epic(s) from the "Approved Backlog" to include in the sprint.

Step 3: Define Sprint Metadata

Work with the user to establish the sprint name (e.g., "Sprint 4").

Step 4: Run the Helper Script

Execute the sprint planning script to automate GitHub issue creation:

bash scripts/create-sprint-issues.sh

Step 5: Understand What the Script Does

The helper script automates these steps:

1. Queries Project Board: Fetches all items from the "Approved Backlog" and prompts you to select an Epic to plan.
2. Extracts Spec File: Parses the selected Epic's body to find the associated spec file path.
3. Creates Milestone: Prompts you for a sprint name and creates the corresponding GitHub milestone.
4. Decomposes Spec with AI: Instead of relying on a rigid format, the script sends the full content of the spec file and the parent Epic to the Gemini CLI. It asks the AI to generate a list of atomic, actionable tasks based on its understanding of the document.
5. Creates GitHub Issues: The script parses the structured task list from Gemini's response and creates a GitHub issue for each task. Each issue is automatically titled, assigned to the new milestone, and includes a description and references to the parent Epic and spec file.

Step 6: Verify Issue Creation

After the script completes, review the newly created issues in your milestone.

gh issue list --milestone "Your Sprint Name"

Step 7: Review Created Issues with User

Walk through the AI-generated issues with your team. The generated tasks provide a strong baseline, but you should review them to confirm completeness, adjust priorities, and make any necessary refinements.

Error Handling

jq or Gemini Not Installed

Symptom: Script reports that jq or gemini command is not found. Solution: Install the required tool and ensure it's in your system's PATH.

No Approved Epics Found

Symptom: Script reports no epics in the approved backlog. Solution: Ensure your Epics are in the correct status column on your project board.

Epic Body Missing Spec Reference

Symptom: Script cannot find a spec file path in the Epic's body. Solution: Edit the Epic's issue body on GitHub to include a valid path to a spec file (e.g., docs/specs/my-feature.md).

Gemini CLI Issues

Symptom: The script fails during the task decomposition step with an error from the gemini command. Solution:

• Ensure the gemini CLI is installed and authenticated (gemini auth).
• Check for API outages or network issues.
• The quality of the task breakdown depends on a functional Gemini CLI.

Notes

• Intelligent Decomposition: The skill no longer relies on a rigid task format in spec files. Gemini reads and understands the document to create tasks.
• LLM guides strategy, script executes: You decide which spec to plan; the script uses AI to handle the tedious decomposition and issue creation.
• One epic per run: Run the script once for each Epic you want to plan for the sprint.
• Traceability is built-in: Each created task issue automatically references the parent Epic and the source spec file.
• Manual refinement is expected: The AI-generated task list is a starting point. Review and adjust it with your team.