# Krammelinearissue Define > Create or improve a well-structured Linear issue through exhaustive guided refinement Use when this capability is needed. - Skill: `tomevault-io/krammelinearissue-define` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/krammelinearissue-define` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/krammelinearissue-define/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/krammelinearissue-define --- # Define Linear Issue Create or improve a Linear issue through exhaustive 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. ## Workflow Boundaries **This command ONLY creates or updates Linear issues.** - **DOES**: Interview user, explore codebase for context, compose well-structured issue, create/update in Linear - **DOES NOT**: Write code, implement features, fix bugs, or make any changes to the codebase **Linear Issue Creation Override**: Invoking this command IS explicit instruction to create or update a Linear issue. When Phase 7 is reached and the user approves the draft, proceed with `mcp__linear__create_issue` or `mcp__linear__update_issue`. This overrides any global rules requiring "explicit instruction" to create/modify Linear issues. **Implementation is a separate workflow.** After this command completes, the user can invoke `/kramme:linear:issue-implement` if they want to start implementing. **CRITICAL**: Do NOT proceed to code implementation after creating the issue. The workflow is complete once the issue URL is returned. ## Audience Priority **Primary: Product Team** — The issue must be understandable and compelling to non-technical stakeholders. **Secondary: Development Team** — Technical context helps engineers, but they determine implementation details. ### Content Priority Order 1. **Problem Statement** - What pain point or opportunity exists? 2. **Value Proposition** - Why should we invest time in this? 3. **User/Business Impact** - Who benefits and how? 4. **Scope / Non-Goals** - What is intentionally excluded so the issue stays focused? 5. **Success Criteria** - How do we know we've solved the problem? 6. **Technical Context** - High-level implementation direction (not detailed how-to) ### Technical Content Guidelines - Implementation proposals should be **strategic, not tactical** - Describe **what** needs to change, not **how** to change it - Only include code examples for: - Specific bugs (show the problematic code) - Very concrete, well-defined fixes - For new features: describe the approach architecturally - Engineers will determine the detailed implementation ## Process Overview 1. **Input Parsing & Mode Detection**: Detect if improving existing issue or creating new 2. **File References & Issue Type**: Read provided files (if any) and classify the issue type 3. **Linear Context Discovery**: Fetch available teams, labels, and projects 4. **Existing Issue Handling**: For improve mode, fetch issue; for create mode, check duplicates 5. **Codebase Exploration**: Search for related implementations and patterns 6. **Autonomous Framing**: Infer target user, why-now, likely non-goals, and decision boundaries from the evidence gathered 7. **Interview**: Multi-round questioning (adapted for issue type and mode) 8. **Issue Composition**: Draft issue following the template 9. **Review & Create/Update**: User approval, then create or update in Linear ## Phase 1: Input Parsing & Mode Detection **Handling `$ARGUMENTS`:** ### Step 1: Detect Mode Check if input matches an existing Linear issue: - **Issue identifier pattern**: `TEAM-123` (uppercase letters, hyphen, numbers) - **Linear URL**: Contains `linear.app` with issue path - **UUID**: 36-character UUID format **If existing issue detected → IMPROVE MODE:** 1. Extract the issue identifier 2. Fetch issue details using `mcp__linear__get_issue` with `id` parameter 3. Store the existing issue content (title, description, labels, etc.) 4. Set mode flag to "improve" 5. **Check for Dev Ask label** - Inspect the fetched issue's labels - If the issue has the "Dev Ask" label (case-insensitive match): - Set `is_dev_ask` flag to true - Store the original issue description as `original_dev_ask_content` - This content will be preserved in the final issue regardless of refinements **If no issue detected → CREATE MODE:** 1. Parse for file paths (anything that looks like a path: contains `/`, ends in common extensions) and store them for Step 2 2. Remaining text is the description/idea 3. If empty, use `AskUserQuestion` to gather the initial concept 4. 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 After determining the mode (and any file context, if provided), classify the issue type. 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", "issue" → suggest Bug - If user provides root cause and specific file(s) → suggest Bug (Simple) - If scope is unclear, multiple components mentioned, or investigation needed → 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 in later phases **For Bug (Simple), store these flags:** - `is_simple_bug = true` - This enables the streamlined interview and simple template ## Phase 2: Linear Context Discovery Fetch Linear workspace context to enable informed metadata selection: 1. **Teams**: `mcp__linear__list_teams` - Get available teams for assignment 2. **Labels**: `mcp__linear__list_issue_labels` - Get available labels for classification 3. **Projects**: `mcp__linear__list_projects` - Get active projects for association Store this context for use in Phase 5 (Metadata & Classification round). ## Phase 3: Existing Issue Handling This phase differs based on mode: ### IMPROVE MODE The target issue was already fetched in Phase 1. Now present it to the user: 1. **Present Current Issue** - Show the issue title, description, labels, and metadata - Format clearly for review - If this is a Dev Ask issue (has "Dev Ask" label): - Note to user: "This issue was created through Linear Asks. The original request will be preserved in an 'Original Dev Ask' section at the bottom of the refined issue." 2. **Identify Improvement Areas** - Use `AskUserQuestion` to ask what aspects to improve: - Problem statement clarity - Value proposition - Scope definition - Acceptance criteria - Technical context - Metadata (labels, priority, etc.) - All of the above (full refinement) - Store selected areas for focused interview in Phase 5 3. **Search for Related Issues** - Use `mcp__linear__list_issues` with keywords from the existing issue - Identify issues to link as related or blockers **Output**: Improvement areas selected, related issues identified. ### CREATE MODE Before creating a new issue, check for existing Linear issues that may already cover this topic: 1. **Search for Duplicates** - Use `mcp__linear__list_issues` with `query` parameter containing keywords from the description - Search across relevant teams identified in Phase 2 2. **Identify Related Issues** - Look for issues that partially overlap with the proposed scope - Find issues that might be blockers or dependencies - Identify issues that could be affected by this work 3. **Present Findings to User** - If potential duplicates found, show them to the user via `AskUserQuestion`: - Option to proceed with new issue (if not truly a duplicate) - Option to improve an existing issue instead → **Switch to IMPROVE MODE** - Option to link as related issue - If related issues found, note them for the Dependencies section 4. **Decision Point** - If user confirms this is a duplicate → Stop and direct to existing issue - If user wants to improve existing issue → Fetch that issue with `mcp__linear__get_issue`, switch to IMPROVE MODE, and restart from Phase 3 - If user confirms new issue is needed → Continue to Phase 4 - Store any related issues for later linking **Output**: List of related issues to reference, confirmation to proceed. ## Phase 4: Codebase Exploration **For Simple Bugs (`is_simple_bug = true`):** Skip this phase if the user has already provided the root cause and affected file(s). Only explore if root cause is uncertain. **For all other issue types:** Proactively search the repository to inform the issue definition: 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 - Find configuration or setup patterns 3. **Discover Related Components** - Find services, modules, or components that may be affected - Identify integration points - Map dependencies 4. **Find Existing Tests** - Search for test files covering similar functionality - Note testing patterns and conventions 5. **Collect TODOs & FIXMEs** - Search for `TODO`, `FIXME`, `HACK` comments related to the topic - These may inform scope or reveal known issues **Output**: Summarize findings to share with user and inform interview questions. Before starting the interview, synthesize a working hypothesis for: - target user or stakeholder - job-to-be-done / problem pressure - why this matters now - obvious non-goals or work that should be split out - which decisions belong in the issue versus which should stay implementation-level Present these as assumptions and refine them only where the evidence is weak. ## Phase 5: Interview The interview process adapts based on the issue type detected in Step 3. ### Simple Bug Interview (if `is_simple_bug = true`) For simple bugs, use a streamlined 2-round interview instead of the full 5-round process. The goal is to quickly capture the essential information without unnecessary overhead. **Round 1: Problem & Reproduction** Questions to cover: - 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** Questions to cover: - What's causing the bug? (if known - 1-2 sentences) - What needs to change to fix it? (1-2 sentences) - Which file(s) are affected? **If root cause is unknown or unclear after Round 2:** - Reclassify as **Bug (Complex)** and set `is_simple_bug = false` - Switch to the **Standard Interview** starting at Round 1 - Use the **Comprehensive Template** in Phase 6 After these 2 rounds, skip to **Round 5: Metadata & Classification** (streamlined - just team and labels, skip project/priority unless user wants them). Then proceed directly to Phase 6 with the simple bug template. --- ### Standard Interview (for all other issue types) Conduct a thorough, multi-round interview using `AskUserQuestion`. Provide context before each question explaining why it matters and your recommendation if you have one. ### Mode-Specific Behavior **IMPROVE MODE:** - Focus on the improvement areas selected in Phase 3 - For each round, show the current content from the existing issue first - Ask if the user wants to: keep as-is, modify, or expand the current content - Skip rounds not selected for improvement (but allow user to request them) - Track what has changed vs. original **CREATE MODE:** - Follow the standard interview flow below - Start from blank for each section Read the 5-round interview structure from `references/interview-rounds.md`. It covers Problem & Value, Scope & Boundaries, Technical Context, Acceptance Criteria, and Metadata & Classification — each with questions to cover and guidance on when to dig deeper. ### Adaptive Follow-up After each round: - **Dig deeper** when answers reveal unexpected complexity - **Pivot** when answers reveal the problem is different than assumed - **Clarify** when answers are ambiguous or contradictory **Track coverage:** ``` Coverage: [Problem: X%] [Scope: X%] [Technical: X%] [Acceptance: X%] [Metadata: X%] ``` Continue until all dimensions show adequate coverage for a well-defined issue. ## Phase 6: Issue Composition ### Template Selection Choose the template based on `issue_type`: - **Bug (Simple)**: Use the Simple Bug Template below - **All others**: Use the Comprehensive Template --- Read the simple bug template from `assets/simple-bug-template.md`. Use for `is_simple_bug = true`. It provides a concise format with title format, description template (Problem, Root Cause, Fix), and notes on when to reclassify. --- ### Comprehensive Template (for features, improvements, complex bugs) Read the comprehensive issue template from `assets/comprehensive-template.md`. It covers mode-specific behavior (IMPROVE vs CREATE), title format, description template (Problem, Value, Goal, Scope, Acceptance Criteria, Edge Cases, Technical Notes, Dependencies, Dev Ask), and technical notes guidelines. ### Metadata to Set - **Team**: From Round 5 selection - **Labels**: From Round 5 selection - **Project**: From Round 5 selection (if applicable) - **Priority**: From Round 5 selection (if determined) - **Related Issues**: From Phase 3 findings (if any) ## Phase 7: Review & Create/Update ### 1. Present Draft **IMPROVE MODE:** - Show the updated issue with change indicators - Highlight what changed vs. original content - Show before/after for significant modifications **CREATE MODE:** - Show the complete issue (title, description, metadata) - Format clearly for review ### 2. Allow Refinements - Ask if any changes are needed - Iterate on feedback until user is satisfied ### 3. Create or Update Issue **IMPROVE MODE:** - Use `mcp__linear__update_issue` with: - `id`: The existing issue ID - `title`: Updated title (if changed) - `description`: The updated markdown description (include "Original Dev Ask" section at the bottom if `is_dev_ask` is true) - `labels`: Updated labels (if changed) - `priority`: Updated priority (if changed) - Other metadata as applicable **CREATE MODE:** - Use `mcp__linear__create_issue` with: - `title`: The composed title - `description`: The full markdown description - `team`: Selected team ID or name - `labels`: Array of selected label names - `project`: Selected project (if any) - `priority`: Selected priority (if any) ### 4. Return Result **IMPROVE MODE:** - Provide the updated issue URL - Summarize what was changed **CREATE MODE:** - Provide the created issue URL - Confirm successful creation ### 5. Workflow Complete - STOP **The linear:issue-define workflow is now complete.** - Do NOT proceed to code implementation - Do NOT start working on the issue - Do NOT invoke other commands automatically **Next steps for the user:** - Review the created/updated issue in Linear - If ready to implement, invoke `/kramme:linear:issue-implement {issue-id}` - If changes needed, run `/kramme:linear:issue-define {issue-id}` again to refine **STOP HERE.** Wait for the user's next instruction. ## Important Guidelines ### Template Selection 1. **Use Simple Bug Template when:** - The root cause is known or easily identified - The fix is localized to 1-3 files - No architectural decisions are needed - The bug can be fully described in a few sentences 2. **Use Comprehensive Template when:** - Root cause is unknown and needs investigation - Multiple components are affected - The issue is a feature, improvement, or complex bug - Scope boundaries need definition - Stakeholder alignment is important ### General Guidelines 1. **Lead with "Why"** - Problem and value proposition are the most important parts. Don't settle for vague justifications. 2. **Make non-goals explicit** - A focused issue is stronger than an aspirational one. If something should wait, say so. 3. **Infer before asking** - Use repo context, existing issues, and provided files to draft the likely answer before asking the user to fill in basics. 4. **Separate product calls from engineering choices** - Capture the decision that needs alignment, not detailed implementation instructions. 5. **Write for Product Team first** - The issue should be compelling to non-technical stakeholders. They read Problem, Value, Goal, Scope, and Acceptance Criteria. 6. **Technical details are secondary** - Keep implementation proposals high-level. Engineers determine the detailed how. 7. **Code examples only when necessary** - Only for specific bugs or concrete fixes. New features don't need code examples. 8. **Check for duplicates first** - Always search existing issues before creating new ones. 9. **Exhaust the interview** - Don't rush through questions. Especially Round 1 (Problem & Value) for comprehensive issues. 10. **Use exploration findings strategically** - Reference patterns and affected areas, but don't dump implementation details. 11. **Craft real options** - Every AskUserQuestion option should be a legitimate choice. 12. **Connect the dots** - Show how different decisions interact and affect each other. 13. **Challenge diplomatically** - If scope seems too broad, suggest splitting. 14. **Get user approval** - Always show the draft before creating the issue. 15. **Keep simple bugs simple** - Don't over-engineer the issue definition. If root cause and fix are clear, the simple template is sufficient. ## Starting the Process 1. Parse `$ARGUMENTS` and detect mode (issue ID → improve, otherwise → create) 2. If improve mode: fetch the existing issue details 3. If create mode with no input: ask what issue they want to define 4. Process file references (if any) 5. Classify issue type (auto-detect and confirm with user) 6. Begin Phase 2 (Linear Context Discovery) 7. Phase 3: For improve mode, present issue and select areas to improve; for create mode, check for duplicates 8. Phase 4: Codebase exploration (skip for simple bugs if root cause known) 9. Phase 5: Interview (simple 2-round for simple bugs, full 5-round for others) 10. Phase 6: Compose issue using appropriate template 11. Phase 7: Review, refine, and create/update issue --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/abildtoft) — claim your Tome and manage your conversions.