abildtoft/kramme:siw:generate-phases

Generate Phases from Specification

Break down a specification into atomic, committable issues organized into phases. Each phase results in a demoable or reviewable outcome appropriate to the work type, and each issue represents a self-contained piece of work with tests/validation.

Workflow Boundaries

This command creates issue files from a specification.

• DOES: Read spec, decompose into phases/tasks, create issue files, update overview table
• DOES NOT: Implement features, write code, or make changes to the codebase

Implementation is a separate workflow. After this command completes, use /kramme:siw:issue-implement to start implementing.

Issue Numbering Scheme

Use phase-prefixed numbering for clear organization:

• Phase 1 tasks: ISSUE-P1-001, ISSUE-P1-002, ISSUE-P1-003...
• Phase 2 tasks: ISSUE-P2-001, ISSUE-P2-002...
• General tasks: ISSUE-G-001, ISSUE-G-002... (cross-cutting concerns like setup, tooling, documentation)

Process Overview

/kramme:siw:generate-phases [spec-file-path]
    ↓
[Validate SIW workflow exists]
    ↓
[Find and read spec file(s)]
    ↓
[Check if implementation in progress] -> Ask: continue or abort
    ↓
[Check for existing issues] -> Ask: append, replace, or abort
    ↓
[Analyze spec and decompose into phases/tasks]
    ↓
[Launch review subagent] -> Validates atomicity, testability, dependencies
    ↓
[Present phase plan to user] -> Confirm or request changes
    ↓
[Create issue files and update overview]
    ↓
[Report summary] -> Suggest /kramme:siw:issue-implement

Shared Guardrails

Before executing Phase 2 or any later step, read references/quality-gates.md so the required output markers, hard gates, and final verification checklist are active throughout the workflow.

Phase 1: Prerequisites & Input

1.1 Validate SIW Workflow Exists

Check for siw/OPEN_ISSUES_OVERVIEW.md:

ls siw/OPEN_ISSUES_OVERVIEW.md 2> /dev/null

If not found: Inform user and suggest running /kramme:siw:init first. Stop.

1.2 Find Spec File(s)

If $ARGUMENTS provided: Use as spec path. If the path does not exist, stop and surface the missing path; do not silently fall back to a glob.

Otherwise: Glob for candidate spec files (anything under siw/ that is not a workflow artifact):

ls siw/*.md 2> /dev/null | grep -v -E '(LOG\.md|OPEN_ISSUES_OVERVIEW\.md|DISCOVERY_BRIEF\.md|SPEC_STRENGTHENING_PLAN\.md|AUDIT_.*\.md)'

Also check for supporting specs:

ls siw/supporting-specs/*.md 2> /dev/null

Main-spec selection:

• Zero candidates: stop. Surface MISSING REQUIREMENT: no spec file found under siw/ and suggest the user run /kramme:siw:discovery or pass an explicit $ARGUMENTS path. Do not invent a spec.
• One candidate: use it as the main spec.
• Multiple candidates: read the first ## Project (or # ) heading of siw/LOG.md to find the initiative name; pick the spec whose filename matches that name (case-insensitive, hyphen/underscore-insensitive). If no match, surface UNVERIFIED: multiple spec files found, picked {first} and use the first candidate; the user can re-run with an explicit path.

1.3 Check Implementation Status

Implementation is considered in progress when either signal is present:

• Any row in siw/OPEN_ISSUES_OVERVIEW.md has status IN PROGRESS or IN REVIEW.
• siw/LOG.md contains an entry dated within the last 7 days under ## Current Progress or an active task list.

Do not infer in-progress from generic git log keywords or unrelated uncommitted changes — those produce false positives. The two signals above are authoritative.

If implementation appears in progress: Use AskUserQuestion:

header: "Implementation In Progress"
question: "It looks like implementation may already be underway. Generating phases now could disrupt the current workflow. How should I proceed?"
options:
  - label: "Continue anyway"
    description: "Generate phases despite ongoing work (use with caution)"
  - label: "Abort"
    description: "Cancel and continue with current workflow"

If "Abort": Stop the workflow.

1.4 Check for Existing Issues

List files in siw/issues/:

ls siw/issues/ISSUE-*.md 2> /dev/null

If issues exist: show the matched filenames inline so the user sees exactly what is on disk before choosing. Then use AskUserQuestion:

header: "Existing Issues"
question: "Found {N} existing issues in siw/issues/ (listed above). How should I proceed?"
options:
  - label: "Append"
    description: "Add new phase issues alongside existing ones"
  - label: "Replace"
    description: "Delete existing issues and create fresh phase breakdown"
  - label: "Abort"
    description: "Cancel and keep existing issues"

If "Abort": Stop the workflow.

If "Replace": Verify nothing is at risk before deleting.

1. Check for uncommitted changes under siw/issues/:

   git status --porcelain -- siw/issues/ 2> /dev/null
   

   If output is non-empty, list the dirty paths and re-prompt with AskUserQuestion options "Proceed and discard changes" / "Abort". Abort by default if the user does not pick "Proceed".

2. Delete the issue files. Prefer trash for recoverability; fall back to rm -f with a warning:

   if command -v trash &> /dev/null; then
     trash siw/issues/ISSUE-*.md 2> /dev/null
   else
     echo "Warning: 'trash' not found. Files will be permanently deleted. Install with 'brew install trash' (macOS) or your distro's 'trash-cli' package."
     rm -f siw/issues/ISSUE-*.md
   fi
   

Phase 2: Spec Analysis

2.1 Extract Work Context

After finding spec files, look for a ## Work Context section in the spec files:

1. Parse the markdown table to extract: Work Type, Priority Dimensions, Deprioritized dimensions
   • If multiple spec files define Work Context, use the main spec file (the one matching the SIW init filename). If ambiguous, use the first found and warn.
2. If not found or malformed, default to Production Feature (3-5 phases, standard sizing)
3. Store as work_context

2.2 Read Spec Content

Read the main spec file and any supporting specs found in Phase 1.2.

Read failure: if any spec file fails to read (permission error, missing file, empty file), stop and surface the path and the error. Do not silently skip the file or paraphrase what the spec "probably" said.

2.3 Extract Key Elements

Identify and extract:

• Overview/objectives - What is the project trying to achieve?
• Scope - What's in and out of scope?
• Success criteria - How do we know we're done?
• Technical design - Architecture, data model, API contracts
• Existing task breakdowns - Any phases or tasks already defined
• Implementation phases - Natural groupings or milestones

Phase 3: Phase Decomposition

3.1 Identify Phase Boundaries

Analyze the spec to find natural phase boundaries:

• Look for milestones, logical groupings, or dependency chains
• Each phase should result in a demoable or reviewable outcome appropriate to the work type
• Default phase count depends on Work Context:
  • Production Feature (default): 3-5 phases. Each phase results in demoable, tested software.
  • Prototype / Spike: 2-3 phases. Larger, more exploratory phases. Phase 1 proves the core concept. Acceptance criteria focus on "does it work" over "is it production-ready." Skip polish and documentation phases.
  • Internal Tool: 3-4 phases. Prioritize getting to a working tool fast. Phase 1 is the happy-path core workflow.
  • Tech Debt / Refactor: 2-4 phases ordered by risk. Phase 1 tackles the highest-risk transformation with rollback capability. Include explicit rollback verification in phase acceptance criteria.
  • Documentation / Process: Phases map to document sections or workflow stages. Each phase produces a reviewable deliverable.
• Identify cross-cutting concerns for the "General" category (setup, tooling, docs)

3.2 Break Into Atomic Tasks

For each phase, decompose into atomic tasks:

Each task should be:

• Committable independently - A single focused change
• Testable - Has clear acceptance criteria and validation
• Sized XS, S, M, or L per references/task-sizing.md. XL tasks MUST be decomposed further before approval.
• Clearly defined - Unambiguous scope with explicit boundaries
• Mode-tagged - AUTO or HITL (see Mode taxonomy below)

Mode taxonomy (AUTO vs HITL — load-bearing for autonomous-agent pickup):

• AUTO — an autonomous agent can pick up, implement, verify, and prepare for review without human input.
• HITL — human-in-the-loop is required for at least one of: an unsettled architectural decision, design review, a genuine product/judgment call, manual testing that cannot be automated, external-system access an agent cannot perform. HITL tasks MUST carry a one-line reason (e.g., "needs architectural decision", "involves manual UAT").

Tag each task during decomposition. Default to AUTO; reserve HITL for tasks with a concrete human-input requirement from the list above, and when unclear choose AUTO. The subagent in Phase 4 will flag any task without a Mode label, any HITL task without a reason, and any task marked HITL whose stated reason is weak or speculative rather than a real blocking requirement.

Sizing and triggers:

Read sizing grammar, break-down triggers, and the context-appropriate slicing rule from references/task-sizing.md and apply them during decomposition. Every task gets an explicit size (XS/S/M/L); any task that hits a break-down trigger — especially one that bundles multiple independently reviewable outcomes — splits before leaving this step.

Slicing shape (context-aware — load-bearing): apply the vertical-vs-horizontal rule from references/task-sizing.md to each task in the chosen Work Context. Each task must leave the smallest reviewable end-to-end outcome for its context.

Identify dependencies:

• Which tasks block other tasks within the same phase?
• Which phases depend on completing previous phases?

3.3 Generate Phase Plan Structure

For each phase:

• Phase goal - What milestone does this achieve?
• Outcome description - What can be demonstrated or reviewed after this phase?
• Tasks - List of atomic issues with titles, sizes, and brief descriptions
• Dependencies - What blocks what
• Parallelization - Group category plus any gating note from Phase 3.4
• Validation - How to verify the phase is complete

For general tasks:

• Setup/scaffolding that doesn't fit a specific phase
• Tooling and configuration
• Documentation tasks

3.4 Parallelization Assessment

Annotate each task group with one of the three parallelization categories defined in references/task-sizing.md (Safe to parallelize / Must be sequential / Needs coordination). The categorization surfaces safe-to-run-in-parallel work explicitly instead of defaulting to serial execution.

Record the chosen category per group (e.g., "Phase 1 tasks: Safe to parallelize after P1-001") so Phase 5's user-facing plan reflects it, the generated issue files keep the exact approved guidance, and siw/OPEN_ISSUES_OVERVIEW.md stores the same decision as one section-level summary per task group.

Phase 4: Subagent Review

Launch a Task subagent to review the proposed breakdown:

Before the prompt, instruct the subagent to read references/task-sizing.md completely and use it as the source of truth for sizing, break-down triggers, slicing shape, and parallelization taxonomy.

Prompt:

Review this phase/task breakdown for a software project or adjacent documentation/process deliverable.

Before evaluating the plan, read `references/task-sizing.md` completely and use it as the source of truth for task sizing, break-down triggers, slicing shape, and parallelization categories.

Work Context: {work_context.work_type}
- Verify phase count and granularity match the work type
- For prototypes, do not flag broad task scope or missing test tasks
- For refactors, verify each task has rollback safety
- For documentation/process work, interpret "end-to-end" as the smallest reviewable deliverable for that workflow rather than schema + API + UI

Evaluate:

1. **Atomicity**: Is each task truly independent and committable on its own?
2. **Testability**: Does each task have clear, verifiable acceptance criteria?
3. **Dependencies**: Are dependencies correctly identified? Any missing?
4. **Completeness**: Are any tasks missing to achieve the phase goals?
5. **Phase coherence**: Does each phase result in a demoable or reviewable outcome that matches the work context?
6. **Sizing (hard gate)**: apply the XS/S/M/L grammar and the XL-is-not-acceptable rule from `references/task-sizing.md`. Flag any XL task explicitly.
7. **Slicing shape**: apply the vertical-vs-horizontal rule from `references/task-sizing.md` for the declared Work Context. Flag layer-by-layer tasks and tasks that bundle multiple independent deliverables.
8. **Parallelization**: Are parallelization categories (Safe / Must be sequential / Needs coordination) correctly assigned? Flag any safely-parallel work serialized unnecessarily, or any shared-state change marked parallel.
9. **Mode (AUTO vs HITL)**: The default is `AUTO`; `HITL` is the exception. Does every task carry a Mode label? Does every HITL task include a one-line reason naming a concrete human-input requirement (unsettled architectural decision, design review, genuine judgment call, non-automatable manual testing, external-system access)? Flag any unlabeled task, any HITL-without-reason, and any task marked HITL whose reason is weak or speculative rather than a real blocking requirement (it should be AUTO). Also flag the reverse: a task that genuinely needs human input but is marked AUTO (e.g., requires manual UAT).

For each issue found, provide:
- What's wrong
- Specific suggestion to fix it

If the breakdown looks good, confirm it's ready.

Incorporate feedback: Update the phase plan based on subagent suggestions.

Loopback gate (max 3 iterations): If the subagent reports any XL task, any context-inappropriate horizontal / over-bundled slice, or any Mode-coverage issue per criterion 9 (unlabeled task, HITL-without-reason, or HITL whose reason is too weak to justify it), re-run Phase 3.2 decomposition and re-submit to the subagent. Only proceed to Phase 5 once the subagent confirms zero XL tasks, zero slicing-shape issues, and complete, correctly-defaulted Mode coverage.

If the gate is still failing after 3 review passes, stop looping. Surface the remaining flagged items to the user as POTENTIAL CONCERNS and use AskUserQuestion to choose: "Proceed to Phase 5 with remaining concerns" / "Abort and let me edit the spec first". Do not loop a fourth time.

Subagent failure handling: If the Task subagent does not return structured feedback (empty response, unstructured text, or tool error), surface the raw response, treat the iteration as inconclusive, and ask the user how to proceed via AskUserQuestion: "Re-run review" / "Proceed without review" / "Abort". Re-runs count toward the 3-iteration cap.

Phase 5: User Approval

Present the proposed structure clearly, prefixed with the PLAN: output marker so downstream tooling can parse this block as the generated plan. Show each issue's size and Mode inline, and include one Parallelization: line per task group. HITL tasks include the one-line reason in the bracket:

PLAN: Phase Plan for {Project Name}
═══════════════════════════════════

General Tasks ({N} tasks)
─────────────────────────
  Parallelization: {Safe to parallelize | Must be sequential | Needs coordination}
  ISSUE-G-001: {Title} [Ready | Size: XS|S|M|L | AUTO]
  ISSUE-G-002: {Title} [Ready | Size: XS|S|M|L | HITL — needs architectural decision]

Phase 1: {Goal} ({N} tasks)
───────────────────────────
  Parallelization: {Safe to parallelize after P1-001 | Must be sequential | Needs coordination}
  ISSUE-P1-001: {Title} [Ready | Size: XS|S|M|L | AUTO]
  ISSUE-P1-002: {Title} [Blocked by P1-001 | Size: XS|S|M|L | AUTO]
  ISSUE-P1-003: {Title} [Ready | Size: XS|S|M|L | HITL — needs design review]

  Outcome: {What can be demonstrated or reviewed}
  Tests: {What tests validate this phase}

Phase 2: {Goal} ({N} tasks)
───────────────────────────
  Parallelization: {Safe to parallelize | Must be sequential after Phase 1 | Needs coordination}
  ISSUE-P2-001: {Title} [Blocked by Phase 1 | Size: XS|S|M|L | HITL — manual UAT]
  ISSUE-P2-002: {Title} [Ready | Size: XS|S|M|L | AUTO]

  Outcome: {What can be demonstrated or reviewed}
  Tests: {What tests validate this phase}

...

Total: {X} issues across {Y} phases + {Z} general
AUTO: {n} | HITL: {m}

Use AskUserQuestion:

header: "Phase Plan"
question: "Does this phase breakdown look correct? You can request specific changes."
options:
  - label: "Looks good - create issues"
    description: "Proceed to create all issue files"
  - label: "Need changes"
    description: "I'll describe what needs to be adjusted"

If "Need changes": Gather feedback and revise the plan. Repeat Phase 5.

Phase 6: File Creation

6.1 Create Issue Files

For each issue, create siw/issues/ISSUE-{prefix}-{number}-{title}.md:

File naming:

• Prefix: P1, P2, P3... for phases, G for general
• Number: 3-digit padded (001, 002, 003)
• Title: lowercase, hyphens, max ~40 characters

Issue template:

# ISSUE-{prefix}-{number}: {Title}

**Status:** Ready | **Priority:** {High|Medium|Low} | **Size:** {XS|S|M|L} | **Phase:** {N or General} | **Parallelization:** {Safe to parallelize | Must be sequential | Needs coordination; include gating note if applicable} | **Mode:** {AUTO | HITL — <one-line reason>} | **Related:** {dependencies}

## Problem

{What this task accomplishes and why it matters}

## Context

{How this fits into the overall project and phase goals}

## Scope

### In Scope

- {Specific deliverable 1}
- {Specific deliverable 2}

### Out of Scope

- {What's NOT included in this task}

## Acceptance Criteria

- [ ] {Testable criterion 1}
- [ ] {Testable criterion 2}
- [ ] Tests pass: {specific test requirement}

## Validation

{How to verify this task is complete}

- [ ] Code compiles/builds
- [ ] Tests: {specific tests to run or write}
- [ ] Manual verification: {what to check}

---

## Technical Notes

### Implementation Approach

{What needs to change - components, files, patterns}

### Affected Areas

- {Component/file 1}
- {Component/file 2}

### Dependencies

- Blocked by: {P1-001, P2-003, etc. if any, or "None"}
- Blocks: {P1-002, P3-001, etc. if any, or "None"}

### Parallelization Guidance

{Whether this issue can proceed in parallel, must stay sequential, or needs coordination first. Start from the same group-level note shown in Phase 5, then add issue-specific gating detail when needed. `siw/OPEN_ISSUES_OVERVIEW.md` keeps only the group summary line for that section.}

6.2 Update Overview Table

Update siw/OPEN_ISSUES_OVERVIEW.md with all new issues, grouped by phase. Modern sections keep one group-level **Parallelization:** summary line; exact per-issue guidance lives in the issue files. Legacy sections that predate that metadata keep their existing format unless the user is explicitly migrating the tracker schema.

If you add any non-DONE issues to a phase section currently marked (DONE), remove the marker (or ask the user) so the header stays accurate.

Append-mode compatibility rules:

• Inspect each existing section before appending rows.
• If a section already uses the 7-column schema | # | Title | Status | Size | Priority | Mode | Related |, keep that schema and emit Mode for new rows.
• If a section already uses the 6-column schema | # | Title | Status | Size | Priority | Related | (pre-Mode), preserve it for compatibility. Only migrate to the 7-column schema when the user explicitly requests a schema migration.
• If a section already uses the legacy 5-column | # | Title | Status | Priority | Related |, preserve that schema and do not inject Size or Mode columns into that section.
• If you're creating a brand-new section while appending into a tracker whose existing sections are legacy 5- or pre-Mode 6-column tables, match the existing dominant schema for the new section instead of mixing layouts mid-file.
• Preserve any existing section-level **Parallelization:** line exactly as written. If a legacy section predates that metadata, do not add the line unless the user is explicitly migrating the tracker schema.

The Mode cell is AUTO or HITL (no inline reason in the table; the reason lives in the issue file's frontmatter).

# Open Issues Overview

## General

**Parallelization:** {Safe to parallelize | Must be sequential | Needs coordination}

| #     | Title   | Status | Size   | Priority   | Mode | Related |
| ----- | ------- | ------ | ------ | ---------- | ---- | ------- |
| G-001 | {Title} | Ready  | {Size} | {Priority} | AUTO |         |
| G-002 | {Title} | Ready  | {Size} | {Priority} | HITL |         |

## Phase 1: {Goal}

**Parallelization:** {Safe to parallelize after P1-001 | Must be sequential | Needs coordination}

| #      | Title   | Status | Size   | Priority | Mode | Related |
| ------ | ------- | ------ | ------ | -------- | ---- | ------- |
| P1-001 | {Title} | Ready  | {Size} | High     | AUTO |         |
| P1-002 | {Title} | Ready  | {Size} | Medium   | AUTO | P1-001  |

## Phase 2: {Goal}

**Parallelization:** {Safe to parallelize | Must be sequential after Phase 1 | Needs coordination}

| #      | Title   | Status | Size   | Priority | Mode | Related |
| ------ | ------- | ------ | ------ | -------- | ---- | ------- |
| P2-001 | {Title} | Ready  | {Size} | High     | HITL | Phase 1 |

**Status Legend:** READY | IN PROGRESS | IN REVIEW | DONE

**Details:** See `siw/issues/ISSUE-{prefix}-XXX-*.md` files.

Legacy compatibility example when appending to an older 5-column tracker:

## Phase 1: {Goal}

| #      | Title   | Status | Priority | Related |
| ------ | ------- | ------ | -------- | ------- |
| P1-001 | {Title} | Ready  | High     |         |
| P1-002 | {Title} | Ready  | Medium   | P1-001  |

Phase 7: Summary

Report the results using the standard end-of-turn triplet (adapted: this skill creates files rather than changing code, so "CHANGES MADE" becomes "FILES CREATED"):

Phase Generation Complete
═════════════════════════

FILES CREATED:
  • siw/issues/ISSUE-*.md ({X} files)
    - General: {N} issues (G-001 to G-{N})
    - Phase 1: {N} issues (P1-001 to P1-{N})
    - Phase 2: {N} issues (P2-001 to P2-{N})
    ...
  • siw/OPEN_ISSUES_OVERVIEW.md (updated)

THINGS I DIDN'T TOUCH:
  • Any existing non-issue files under siw/ (LOG.md, spec files, supporting-specs/)
  • Source code — implementation is a separate workflow
  • {List any issues explicitly preserved during Append mode}

POTENTIAL CONCERNS:
  • {Any subagent-flagged risks that survived user approval}
  • {Any CONFUSION or MISSING REQUIREMENT markers from Phase 2 that were resolved by assumption — worth re-checking before implementation}
  • {If empty, state: "None"}

Suggested starting point:
  /kramme:siw:issue-implement ISSUE-{first-ready-issue}

Tips:
  • Work through phases sequentially (Phase 1 → Phase 2 → ...)
  • General tasks follow their recorded parallelization guidance; only `Safe to parallelize` work can truly be done anytime
  • Mark issues DONE in the overview as you complete them

STOP HERE. Wait for the user's next instruction.