jg-breakdown

Invocation

This skill runs only when the developer invokes it. Execute its workflow with the available tools. Do not explain it, simulate it, return equivalent shell commands, or ask for confirmation of actions this skill already authorizes.

Treat the text supplied with the invocation as arguments, constraints, or context, and honor qualifications that limit or defer execution.

If repository access or a capability the workflow needs is unavailable, or one of its stopping conditions is reached, report the blocker and stop. Never simulate success.

Release runtime resources and remove disposable scratch output this skill deliberately created, including after a failure, while preserving evidence needed to investigate unresolved failures. Report anything retained within this skill’s output format. This cleanup is a narrow exception to the skill’s write limits. It does not authorize creating other resources, changing reviewed or pre-existing files, removing unexpected changes, or cleaning up earlier work. Every other write is defined by this skill’s workflow.

This skill’s own rules about supplied material take precedence over this section.

Workflow

Perform a planning-only evaluation of a concrete plan for the engineering change currently being discussed. Convert the plan into ordered implementation milestones only when decomposition provides meaningful execution and review boundaries. This skill does not create a new strategy or authorize implementation. It authorizes only the smallest read-only repository inspection needed to confirm that the plan remains current and the creation, update, or removal of milestones.md in that plan’s directory. It does not authorize editing any other file, updating tests or snapshots, running write-producing auto-fixes or generators, installing dependencies, creating migrations or generated artifacts, changing Git state, committing, pushing, or beginning implementation.

A concrete plan is required. Use the plan at the path supplied with the invocation, otherwise the exact plan established in the current discussion, and the planning directory that holds it. Do not search other planning directories or select a plan based on timestamps. If the plan was not persisted, use the exact plan most recently presented to the developer, keep that limitation explicit, and do not create a new planning directory during jg-breakdown. Do not use jg-breakdown to redesign the solution, expand or reduce scope, change architecture, alter acceptance criteria, introduce optional improvements, or silently resolve decisions that belong at the plan level. If no current plan exists, it cannot be identified safely, repository evidence has materially invalidated it, or producing a safe breakdown would require changing a material plan decision, report the blocker and stop; the plan must be created or revised through jg-plan before it can be broken down.

1. Reuse the repository evidence and decisions established by the current plan when they remain current. Perform additional read-only inspection only when needed to determine whether useful milestone boundaries exist, establish their dependencies, assign verification ownership, or determine whether the plan has become stale.

2. Determine whether the plan contains at least two coherent implementation slices that can each reach a meaningful finished state, complete their required tests or other verification, and support a useful developer review checkpoint. Do not split a plan merely because it contains multiple files, implementation steps, layers, or verification commands.

3. If the plan is one coherent implementation slice, do not create milestones.md. If milestones.md already exists in that plan’s directory, remove it so an obsolete breakdown does not remain. Tell the developer that the plan should be implemented as one complete scope without breaking it down. If the plan has not yet been approved, state that its approval is still required. Then stop without appending a completion summary.

4. When decomposition is warranted, convert the plan’s strategic implementation steps into an ordered sequence of numbered milestones. Use Milestone as the execution unit; do not create a milestone, task, and subtask hierarchy merely to increase granularity.

5. Make each milestone the smallest coherent implementation slice that can reasonably be completed, tested or otherwise verified, and reviewed as a meaningful finished state. Keep each milestone small enough to finish in one fresh context window, and put refactoring that makes later milestones easier first. For every milestone, include:

   • a concise objective describing the finished outcome
   • dependencies on earlier milestones or external prerequisites
   • the exact in-scope files, modules, symbols, contracts, configuration, documentation, and migrations from the plan that the milestone owns when they are known
   • the implementation work required to reach the milestone’s finished state
   • the focused tests and other verification that must be completed for that milestone
   • concrete acceptance criteria that determine whether the milestone is complete
   • a review checkpoint identifying the behavior, contracts, risks, integration points, or other material details the developer should inspect before continuing

6. Keep implementation and its required correctness evidence together. Do not split required tests, directly affected documentation, error-contract synchronization, migrations, public exports, or other necessary supporting work into later milestones merely to make an earlier milestone smaller. Do not create placeholders, temporary duplication, unused abstractions, transitional compatibility paths, dead-end scaffolding, or deliberately incomplete implementations solely to manufacture milestone boundaries unless the approved plan explicitly requires a staged compatibility or migration path. Do not make milestones artificially small or uniform in size. Order them according to real implementation dependencies and risk.

7. Perform a plan-to-milestone coverage pass before finalizing the sequence. Every in-scope deliverable, acceptance criterion, required production change, test, documentation update, migration, public-contract change, removal, integration point, and verification requirement in the plan must appear in at least one developer-visible milestone. The sequence presented to the developer is the complete and final milestone sequence. Do not reserve hidden milestones, maintain an alternate internal sequence, omit required work, or rely on unstated milestone-level work. If required work cannot be assigned without changing a material plan decision, report the blocker and stop; the plan must be revised through jg-plan before the breakdown can be completed.

8. Write the complete final milestone sequence to milestones.md in the current plan’s directory. When invoked while a current milestone sequence exists, revise it. Reuse the plan’s directory and update milestones.md to reflect the current repository state, completed milestones, and the revised current and remaining work. Put a status line directly under every milestone heading, the marker jg-execute and jg-review read, derived from the repository: **Status:** done when its work is already complete, **Status:** in progress when part of its work exists, otherwise **Status:** pending. Above the first milestone, write an ## Overview table with one row per milestone: its number, its name linked to its heading, and its status, matching that milestone’s status line, which stays the authority. When revising a breakdown, refresh the table, and add one when the existing file has none. Never move an existing status backward unless the developer explicitly asks to revisit that work. When repository evidence contradicts a status marked done, keep the status, report the contradiction, and ask whether to reopen that milestone. This applies even after approval or after implementation has started; do not create a new planning directory solely because development is underway. Do not modify any other file or Git state. When the file is persisted, report its repository-relative path before presenting the milestone body. The complete Markdown body presented to the developer must match milestones.md exactly, including milestone numbers, names, scope, implementation work, tests, acceptance criteria, review checkpoints, ordering, and approval statement. If the plan was not persisted or the required write capability is unavailable, present the complete milestone sequence, state that it was not persisted, and do not claim that milestones.md exists.

9. End both milestones.md and the matching response body with a ## Approval required section summarizing the complete milestone sequence and stating these rules, then stop:

   • Each milestone needs its own explicit authorization, is the complete scope of that request, and ends at its review checkpoint. Invoking jg-execute authorizes the milestone it runs; jg-execute auto authorizes every remaining milestone, or only the milestone it names.
   • If a milestone depends on incomplete earlier work, or completing it would cross a milestone boundary or change the approved plan, stop and report before expanding scope.
   • To change the plan, invoke jg-plan with the amendments. To create or change milestones, invoke jg-breakdown.

   This skill’s output contract replaces any general completion-summary requirement; do not append a completion summary after ## Approval required. Approval must be issued after the current milestone sequence is presented; the jg-breakdown invocation itself, earlier approval of a superseded milestone sequence, questions, feedback, or requests to revise the sequence do not count as approval or authorize implementation. If the underlying plan was not already approved, explicit developer approval issued after the current milestone sequence is presented approves the presented plan and milestone sequence unless the developer limits that approval. If the plan was already approved before jg-breakdown was invoked, the plan remains approved but the current milestone sequence requires explicit approval before milestone-scoped implementation begins. Approval of the current milestone sequence alone does not authorize implementing any milestone. After approval, implementation proceeds one milestone at a time, and each milestone needs its own authorization as the first rule above describes. The developer may combine milestone-sequence approval with authorization to implement one milestone in the same instruction. Invoking jg-execute after the sequence is presented counts as approval of it. Completing or approving one milestone never authorizes the next milestone, except that jg-execute auto without a named milestone authorizes every remaining milestone; after completing the authorized milestone and its required verification, report the result and stop until the developer explicitly authorizes another milestone.