abildtoft/kramme:siw:issue-define

Define Local Issue

Create or improve a local issue through guided interactive refinement. Can start from scratch with a description, or improve an existing issue by providing its identifier. Supports file references for technical context and proactively explores the codebase to inform issue definition.

Issue Naming: New issues default to G-XXX (General). Use P1-, P2-, etc. for phase-specific issues. When creating a new issue, recommend a phase prefix if the issue fits an active (not completed) phase.

Workflow Boundaries

This command ONLY creates or updates local issue files.

• DOES: Interview user, explore codebase for context, compose well-structured issue, create/update issue file
• DOES NOT: Write code, implement features, fix bugs, or make any changes to the codebase

Implementation is a separate workflow. This skill ends when the issue file is written and the tracker is updated. After it completes, the user can invoke /kramme:siw:issue-implement if they want to start implementing.

Prerequisites

Workflow files should exist. If siw/OPEN_ISSUES_OVERVIEW.md doesn't exist, suggest running /kramme:siw:init first. If the file is still missing after that suggestion, stop without creating an issue.

Audience Priority

Primary: Future You — The issue must be clear enough to understand days or weeks later.

Secondary: Other Developers — Technical context helps others understand the work.

Content Priority Order

1. Problem Statement - What pain point or opportunity exists?
2. Context - What's the current state and why does this matter?
3. Scope / Non-Goals - What's in, what's out, and what should wait?
4. Acceptance Criteria - How do we know we've solved the problem?
5. Technical Notes - Implementation direction (not detailed how-to)

Phase 1: Input Parsing & Mode Detection

Handling $ARGUMENTS:

Step 1: Detect Mode

Check if input matches an existing issue:

• Issue identifier patterns:
  • Full format: ISSUE-G-001, ISSUE-P1-001, ISSUE-P2-001, etc.
  • Short format: G-001, P1-001, P2-001, etc.
  • Legacy format: ISSUE-001 or 001 (treated as G-001)

Detection rule: Only treat it as an existing issue if a matching file exists in siw/issues/ISSUE-{prefix}-{number}-*.md.

If existing issue detected → IMPROVE MODE:

1. Extract the prefix and number (e.g., G and 001 from ISSUE-G-001, or P1 and 002 from P1-002)
2. Find and read the issue file from siw/issues/ISSUE-{prefix}-{number}-*.md
3. Store the existing issue content
4. Set mode flag to "improve"

If an identifier-like argument was provided but no file exists:

1. Use AskUserQuestion to confirm whether they want to create a new issue instead
2. If creating: treat the provided prefix as requested_prefix and ignore the provided number
3. If the identifier was followed by additional text, treat that remainder as the initial description; otherwise ask for a description
4. Continue in CREATE MODE

If no issue detected → CREATE MODE:

1. Parse optional prefix hint at the start of $ARGUMENTS:
   • Accepted: G, G-, P1, P1-, P2, P2-, etc.
   • Store as requested_prefix (without trailing -) and strip it from the description
2. Parse for file paths (anything containing / or ending in common extensions) and store for Step 2
3. Remaining text is the description/idea
4. If empty, use AskUserQuestion to gather the initial concept
5. Set mode flag to "create"

Step 2: Process File References (Both Modes)

If file paths provided:

1. Read each file using the Read tool
2. Extract relevant context:
   • What functionality does this code provide?
   • What patterns or conventions does it follow?
   • What dependencies or integrations exist?
3. Store findings for use in interview and issue composition

Step 3: Issue Type Classification

Auto-detect from context and suggest to the user (they can override):

Issue Types:

• Bug (Simple): Root cause is known or easily identified, fix is localized, no architectural decisions needed
• Bug (Complex): Unknown root cause, affects multiple components, requires investigation
• Feature: New functionality
• Improvement: Enhance existing functionality

Detection Heuristics:

• Keywords like "bug", "fix", "broken", "doesn't work", "error" → suggest Bug
• If user provides root cause and specific file(s) → suggest Bug (Simple)
• If scope is unclear, multiple components mentioned → suggest Bug (Complex)
• Keywords like "add", "new", "implement", "create" → suggest Feature
• Keywords like "improve", "refactor", "enhance", "optimize" → suggest Improvement

Present classification to user via AskUserQuestion:

• Show detected type with reasoning
• Allow override to any type
• Store issue_type for conditional behavior

For Bug (Simple), store:

• is_simple_bug = true
• This enables streamlined interview and simple template

Step 4: Phase Recommendation (Create Mode)

Only for CREATE MODE. Skip for IMPROVE MODE.

Goal: recommend a phase prefix (P1-, P2-, etc.) when the issue clearly fits an active (not completed) phase. If the issue doesn't suit a phase well, or the relevant phase is completed, recommend G (General, i.e., IDs like G-001).

Inputs to check:

1. siw/ spec file created by /kramme:siw:init (phase breakdown and tasks).
2. siw/LOG.md for phase completion notes (e.g., "Phase 1 complete", "Status: DONE").
3. siw/OPEN_ISSUES_OVERVIEW.md for existing phase sections and active work.

If multiple candidate spec files exist under siw/, ask the user which one is the main spec (exclude siw/LOG.md, siw/OPEN_ISSUES_OVERVIEW.md, and siw/DISCOVERY_BRIEF.md).

Heuristics:

• Map the issue description and any referenced tasks to the most relevant phase in the spec.
• If the phase is explicitly marked complete in the spec or log, do not recommend that phase.
• If the phase section header in siw/OPEN_ISSUES_OVERVIEW.md is marked with (DONE), treat the phase as completed.
• If siw/OPEN_ISSUES_OVERVIEW.md has a Phase N section and all issues in that phase are DONE, treat the phase as completed.
• If no phase info exists or mapping is unclear (or the issue doesn't suit a phase well), default to G.
• If the user explicitly supplied a prefix (requested_prefix), treat it as preferred, but warn if the phase appears completed and offer alternatives.

AskUserQuestion (recommendation + confirmation):

header: "Choose Issue Prefix"
question: "Which prefix should we use? Recommendation: {recommended_prefix}- ({reason})."
options:
  - label: "Use {recommended_prefix}- (recommended)"
    description: "Matches the spec/tasks and the phase isn't completed"
  - label: "Use a different phase prefix"
    description: "Pick P1-, P2-, P3-, etc."
  - label: "Use G- (General)"
    description: "Standalone or doesn't fit a phase well"

If {recommended_prefix} is G, omit the separate "Use G-" option to avoid duplicates.

Store issue_prefix based on the selection without the trailing dash (e.g., P1, P2, G).

Phase 2: Existing Issue Handling

IMPROVE MODE

Present the existing issue to the user:

1. Present Current Issue

   • Show the issue title, problem, context, and criteria
   • Format clearly for review

2. Identify Improvement Areas

   • Use AskUserQuestion:
     • Problem statement clarity
     • Context/background
     • Scope definition
     • Acceptance criteria
     • Technical notes
     • All of the above (full refinement)
   • Store selected areas for focused interview

CREATE MODE

Before creating a new issue, check for existing similar issues:

1. Scan Existing Issues

   • List files in siw/issues/ directory
   • Read siw/OPEN_ISSUES_OVERVIEW.md for existing issue titles

2. Check for Similar Issues

   • If any existing issue titles match keywords from the description, warn user
   • Use AskUserQuestion:
     • Proceed with new issue
     • Improve existing issue instead → Switch to IMPROVE MODE
     • Abort

3. Generate Next Issue Number

   • Determine issue_prefix (from Step 4; fallback to requested_prefix if present; otherwise default G)
   • Parse siw/OPEN_ISSUES_OVERVIEW.md table to find highest issue number within that prefix group
   • Compute candidate = highest + 1 (or 001 if no issues with that prefix exist), padded to 3 digits
   • Verify no on-disk collision: glob siw/issues/ISSUE-{issue_prefix}-{candidate}-*.md. If any file matches, the tracker is out of sync with siw/issues/. Increment the candidate and re-check until no file matches, then warn the user that the tracker may need a reindex via /kramme:siw:issue-reindex.
   • Store as issue_number
   • Full ID: {issue_prefix}-{issue_number} (e.g., G-001, P1-002)

Phase 3: Codebase Exploration

For Simple Bugs (is_simple_bug = true): Skip if user provided root cause and affected file(s).

For all other issue types: Proactively search the repository:

1. Find Related Implementations

   • Use Grep to search for keywords from the description
   • Use Glob to find files in related areas
   • Identify existing code that does something similar

2. Identify Patterns & Conventions

   • Look for architectural patterns in related code
   • Note naming conventions, file organization

3. Discover Related Components

   • Find services, modules, or components that may be affected
   • Identify integration points

4. Find Existing Tests

   • Search for test files covering similar functionality
   • Note testing patterns

Output: Summarize findings to share with user and inform interview.

Before the interview, synthesize a working hypothesis for:

• who is affected
• why this matters now
• what should be explicitly deferred or split into another issue
• which choices belong in the issue versus which should stay implementation-level

Use these as assumptions to validate instead of asking the user to restate obvious context.

Phase 4: Interview

The interview adapts based on issue type.

Simple Bug Interview (if is_simple_bug = true)

Streamlined 2-round interview:

Round 1: Problem & Reproduction

• What's the bug? (brief description)
• Steps to reproduce (numbered list ending with "Bug: [what happens]")
• What should happen instead?

Round 2: Root Cause & Fix

• What's causing the bug? (if known)
• What needs to change to fix it?
• Which area(s) are affected? If specific files are known, use them as private context for exploration, but translate them into durable module/behavior language in the issue body.

If root cause unknown after Round 2:

• Confirm the reclassification with the user via AskUserQuestion (one question, defaulting to "reclassify as Bug (Complex)").
• Run the previously-skipped Phase 3 (Codebase Exploration).
• Restart the standard interview at Round 1, pre-filling answers from the Round 1/Round 2 simple-bug pass so the user only refines what's new.

Then run a streamlined Metadata pass and store the answers for Phase 5:

• Priority (default Medium unless the user indicated urgency)
• Size (default XS/S for localized simple bugs)
• Related issues or blockers, if any
• Parallelization category (default Safe to parallelize for localized fixes unless shared-state or sequencing concerns exist)
• Mode:
  • Default AUTO. Localized simple bugs with a known fix and automatable verification are the canonical AUTO case.
  • Use HITL — <one-line reason> only when the fix has a concrete human-input requirement (external access, manual testing that can't be automated, design review, or an unsettled architectural/judgment call). When unclear, choose AUTO.

Confirm inferred metadata with the user before composing. Then proceed to Phase 5 with the simple template.

Standard Interview (for all other types)

Multi-round interview using AskUserQuestion.

IMPROVE MODE: Focus on selected improvement areas. Show current content first.

CREATE MODE: Follow standard flow below.

Round 1: Problem & Context (Most Important)

Questions:

• What specific problem or pain point does this solve?
• Who is affected (end users, internal teams)?
• How significant is the impact?
• What happens if we don't address this?

Dig deep:

• Don't accept vague answers
• Push for concrete impact

Round 2: Scope & Boundaries

Questions:

• What is explicitly in scope?
• What is explicitly out of scope?
• Are there related changes that should be separate issues?
• What is the minimum viable implementation?

Round 3: Technical Context

Questions:

• Which components/areas are affected?
• Are there dependencies or blocking issues?
• What existing patterns should be followed?
• Are there technical constraints?

Leverage exploration findings:

• Present discovered patterns as options
• Highlight related code

Round 4: Acceptance Criteria

Questions:

• What defines "done"?
• How should this be tested/verified?
• Are there specific edge cases?
• What quality criteria must be met?

Guide toward testable criteria:

• Each criterion should be verifiable
• Include both happy path and error scenarios

Round 5: Priority, Related Work & Mode

Questions:

• What priority level? (High/Medium/Low)
• What size best fits this issue? (XS/S/M/L)
  • XS = 1 file, single function
  • S = 1-2 files, one contained change
  • M = 3-5 files, one feature/spec slice
  • L = 6-8 files, multi-component
• Are there related issues or tasks?
• Does this block or depend on other work?
• What parallelization category fits this work?
  • Safe to parallelize
  • Must be sequential
  • Needs coordination
• What Mode fits this issue?
  • AUTO (default) — an autonomous agent can implement, verify, and prepare for review without human input
  • HITL — human-in-the-loop is required by a concrete need: an unsettled architectural decision, design review, a genuine product/judgment call, manual testing that can't be automated, or external system access. HITL requires a one-line reason naming that need.

If the answer isn't supplied, infer Mode from the issue type and exploration findings. Default to AUTO; only choose HITL when you can name a specific blocking human requirement, and confirm before composing.

Phase 5: Issue Composition

Read references/issue-templates.md and select the appropriate template:

• Use the Simple Bug Template when is_simple_bug = true.
• Use the Comprehensive Template otherwise.

Both templates include the Mode: field. When emitting the issue, fill Mode: AUTO or Mode: HITL — <one-line reason> from Round 5.

The references file also defines the Durability rule: issue bodies must describe modules, behaviors, and contracts — not file paths, line numbers, or internal helper/class names. Apply it to every section of the composed issue (Problem, Context, Technical Notes, References).

Phase 6: Review & Create/Update

1. Present Draft

IMPROVE MODE: Show updated issue with change indicators.

CREATE MODE: Show complete issue.

2. Allow Refinements

• Ask if any changes are needed
• Iterate until user is satisfied

3. Write Issue File

Create/Update issue file:

siw/issues/ISSUE-{prefix}-{number}-{sanitized-title}.md

Sanitize title:

• Lowercase
• Replace spaces with hyphens
• Remove special characters
• Max 40 characters

4. Update siw/OPEN_ISSUES_OVERVIEW.md

Issues are grouped by prefix (General, Phase 1, Phase 2, etc.).

For new issues: Add a row to the appropriate section. If the section doesn't exist yet, create the section header and table first.

For updated issues: Update the existing row if title, priority, status, or mode changed.

Read references/tracker-schema.md for the column-layout rules (three coexisting layouts, when to use each, when to migrate), the parallelization-summary recomputation rules, and the (DONE) phase-marker rules.

5. Return Result

IMPROVE MODE:

• Confirm issue file updated
• Summarize what changed

CREATE MODE:

• Confirm issue file created
• Show file path

6. Workflow Complete

The skill ends here. Surface the file path and tell the user that if they want to implement next, they can run /kramme:siw:issue-implement {prefix}-{number}, or re-run /kramme:siw:issue-define {prefix}-{number} to refine. Do not start implementation.

Guidelines

1. Lead with "Why" — Problem statement is most important.
2. Make non-goals explicit — A tighter issue is more actionable than a broad wish list.
3. Infer before asking — Use codebase and workflow context to draft likely answers before asking the user for basics.
4. Separate product calls from implementation details — Capture the decision that needs alignment, not low-level how-to.
5. Be specific — Vague issues lead to vague implementations.
6. Check for similar issues — Don't create duplicates.
7. Keep simple bugs simple — Don't over-engineer.
8. Exhaust the interview — Especially Round 1 for complex issues.
9. Get user approval — Always show draft before creating.