# Krammelinearissue Implement > Start implementing a Linear issue with branch setup, context gathering, and guided workflow Use when this capability is needed. - Skill: `tomevault-io/krammelinearissue-implement` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/krammelinearissue-implement` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/krammelinearissue-implement/raw - Safety review: pending - 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-implement --- # Implement Linear Issue Start implementing a Linear issue through an extensive planning phase before any code changes. **IMPORTANT:** Linear issues are typically written for product teams and may be light on technical implementation details. This command emphasizes thorough planning and codebase exploration to translate product requirements into a concrete technical approach before starting implementation. ## Process Overview ``` /kramme:linear:issue-implement ABC-123 | v [Validate & Fetch Issue] -> Not found? -> Show error, abort | v [Branch Setup] -> IMMEDIATELY create/switch to Linear's branchName | v [Parse Requirements] -> Extract acceptance criteria from description | v =============== PLANNING PHASE (extensive) =============== | v [Codebase Exploration] -> ALWAYS search for patterns/implementations | v [Technical Analysis] -> Map product requirements to technical approach | v [Upfront Questions] -> Clarify ambiguities before proceeding | v [Create Technical Plan] -> Document approach, files, patterns to follow | v =================== EXECUTION PHASE =================== | v [Approach Selection] -> AskUserQuestion with 3 options | v [Execute Workflow] -> Guided / Context-only / Autonomous ``` --- ## Step 1: Parse Arguments and Fetch Issue ### 1.1 Extract Issue ID from Arguments `$ARGUMENTS` contains the issue ID provided by the user. **Validation:** - Pattern: `{TEAM}-{number}` where TEAM is any alphanumeric prefix - Case-insensitive (convert to uppercase for display) - Examples: `wan-123` -> `WAN-123`, `abc-456` -> `ABC-456` **If no argument provided or invalid format:** ``` Error: Please provide a Linear issue ID. Usage: /kramme:linear:issue-implement Example: /kramme:linear:issue-implement ABC-123 The issue ID should be in the format TEAM-NUMBER (e.g., WAN-521, HEA-456). ``` **Action:** Abort. ### 1.2 Fetch Issue Details **ALWAYS** use the Linear MCP tool to fetch complete issue details: ``` mcp__linear__get_issue with id: {ISSUE_ID} ``` **Capture from issue response:** - `id` - Linear issue UUID (for API calls) - `identifier` - Human-readable ID (e.g., WAN-123) - `title` - Issue title - `description` - Full issue description (markdown) - `state` - Current state (Backlog, In Progress, etc.) - `labels` - Associated labels - `branchName` - **CRITICAL**: Linear's recommended branch name - `url` - Link to issue in Linear - `project` - Associated project - `priority` - Issue priority ### 1.3 Fetch Issue Comments **ALWAYS** fetch comments for additional context: ``` mcp__linear__list_comments with issueId: {ISSUE_ID} ``` Comments often contain: - Clarifications from product/design - Technical discussions - Updated requirements - Scope changes ### 1.4 Handle Missing Issue **If issue not found:** ``` Error: Linear issue {ISSUE_ID} not found. Please verify: - The issue ID is correct (format: TEAM-123) - You have access to the issue's team - The issue exists in Linear Try again with /kramme:linear:issue-implement ``` **Action:** Abort. --- ## Step 2: Branch Setup (MANDATORY - DO IMMEDIATELY) **CRITICAL:** This step MUST be completed before any other actions. Do NOT proceed to issue parsing, planning, or any other step until you are on the correct branch. ### 2.1 Extract Branch Name from Linear The `mcp__linear__get_issue` response includes a `branchName` field - this is Linear's recommended branch name. **Priority:** 1. **FIRST**: Use `branchName` from Linear if present and non-empty 2. **FALLBACK ONLY**: If `branchName` is empty/missing, generate one using pattern: `{user-initials}/{ISSUE_ID}-{sanitized-title}` **If generating fallback:** - Ask user for their initials if not known - Sanitize title: lowercase, replace spaces with hyphens, max 50 chars for description ### 2.2 Check Current Git State ```bash git status --porcelain git branch --show-current ``` **If uncommitted changes exist:** Use AskUserQuestion: ```yaml header: "Uncommitted Changes" question: "You have uncommitted changes. How should I handle them?" options: - label: "Stash changes" description: "Save changes to stash, can be restored later" - label: "Commit changes" description: "Commit current changes before switching branches" - label: "Discard changes" description: "Warning: This will lose your uncommitted work" - label: "Abort" description: "Cancel and let me handle it manually" ``` ### 2.3 Create and Switch to Branch **If branch doesn't exist locally or remotely:** ```bash # Determine base branch BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||') || BASE="main" # Fetch latest git fetch origin $BASE # Create branch from latest base git checkout -b {branchName} origin/$BASE ``` **If branch exists locally:** ```bash git checkout {branchName} ``` **If branch exists only on remote:** ```bash git checkout -b {branchName} origin/{branchName} ``` ### 2.4 Verify Branch Creation (REQUIRED) **ALWAYS run this verification:** ```bash git branch --show-current ``` **The output MUST match the target `branchName`.** If not, something failed - report to user and abort. ### 2.5 Confirm Branch to User Display confirmation: ``` ✓ Branch: {branchName} Source: {Linear's suggested name | Generated from issue} Proceeding with issue analysis... ``` **Only after this confirmation may you proceed to the next step.** --- ## Step 3: Parse and Present Issue Context ### 3.1 Parse Issue Description Analyze the issue description to extract: **Requirements:** - Look for bullet points, numbered lists - Sections labeled "Requirements", "Acceptance Criteria", "Tasks" - User story format ("As a... I want... So that...") **Acceptance Criteria:** - Explicit criteria sections - "Done when..." statements - Verification checkpoints **Technical Notes:** - Implementation hints - API specifications - Database changes mentioned - Related files or components ### 3.2 Present Issue Summary Show the user what was found: ``` Linear Issue: {identifier} Title: {title} Description: --- {description - first 500 chars} {if longer: "... [truncated, full description will be used]"} --- State: {state} Priority: {priority} Labels: {labels} Project: {project} Recommended Branch: {branchName} Comments: {count} comments found {if comments exist: show key points from recent comments} Requirements Identified: - {requirement 1} - {requirement 2} - ... Acceptance Criteria: - {criterion 1} - {criterion 2} - ... ``` --- ## Step 4: Codebase Exploration (PLANNING PHASE) **CRITICAL:** Linear issues are typically product-focused and lack technical implementation details. **ALWAYS** perform extensive codebase exploration to understand how to implement the feature, regardless of how the issue is written. ### 4.1 Why This Phase Is Essential Linear issues often describe: - **What** the user should be able to do (user stories) - **Why** it matters (business value) - **Acceptance criteria** (verification conditions) They typically do NOT describe: - Which files/modules to modify - What patterns to follow - How existing similar features are implemented - Technical constraints or dependencies **Your job is to bridge this gap through thorough exploration.** ### 4.2 Mandatory Exploration Steps **ALWAYS perform these steps, even if the issue seems straightforward:** 1. **Search for similar features/patterns:** - Use Glob and Grep to find related code - Look for existing implementations of similar functionality - Identify relevant modules, services, or components 2. **Use the Explore agent:** ``` Task tool with subagent_type=Explore: "Find existing implementations related to {feature description from issue}. Identify relevant files, patterns, and conventions used in this codebase." ``` 3. **Identify key files and patterns:** - List files that will likely need modification - Note existing patterns to follow - Find test patterns for similar features ### 4.3 Present Findings After exploration, present findings to the user: ``` Codebase Exploration Results: Relevant Files Found: - {file 1} - {why relevant} - {file 2} - {why relevant} Existing Patterns: - {pattern description} in {location} Similar Implementations: - {feature} in {files} - could serve as reference Suggested Approach: {brief technical approach based on findings} ``` --- ## Step 5: Upfront Questions (PLANNING PHASE) **CRITICAL:** Tend towards asking questions rather than plunging into implementation. The goal is to fully understand requirements before writing any code. ### 5.1 Identify Ambiguities Review the issue and exploration results to identify: - Unclear requirements or acceptance criteria - Multiple valid technical approaches - Scope boundaries (what's in/out) - Dependencies on other work - Testing expectations ### 5.2 Ask Clarifying Questions **ALWAYS** use AskUserQuestion for each unclear aspect before proceeding. **Example questions to consider:** ```yaml header: "Implementation Scope" question: "The issue mentions {feature}. Should this include {related functionality} or just the core feature?" options: - label: "Core feature only" description: "Minimal implementation as described" - label: "Include {related functionality}" description: "Broader scope with additional features" ``` ```yaml header: "Technical Approach" question: "I found two patterns in the codebase for similar features. Which approach should we follow?" options: - label: "Pattern A - {description}" description: "Used in {files}" - label: "Pattern B - {description}" description: "Used in {files}" ``` ```yaml header: "Testing Requirements" question: "What level of test coverage is expected?" options: - label: "Unit tests only" description: "Test individual functions/methods" - label: "Unit + integration tests" description: "Also test component interactions" - label: "Full coverage including E2E" description: "Complete test suite" ``` ### 5.3 Create Technical Plan After gathering answers, create a comprehensive technical plan that translates the product requirements into a concrete implementation approach: Read the technical plan template from `assets/technical-plan.md` and populate it based on the gathered context and user answers. **Present this plan to the user and get confirmation before proceeding to implementation approach selection.** --- ## Step 6: Implementation Approach Selection ### 6.1 Present Approach Options Use AskUserQuestion: ```yaml header: "Implementation Approach" question: "How would you like to proceed with implementing this issue?" options: - label: "Guided Implementation" description: "I'll create a detailed plan with tasks, then implement step-by-step with verification at each stage. Best for complex features." - label: "Context Setup Only" description: "I'll set up the branch and create a todo list, but you'll guide the implementation. Best when you know the approach." - label: "Autonomous Implementation" description: "I'll analyze the codebase, plan, implement, and verify. Check in when done. Best for straightforward tasks." ``` --- ## Step 7: Workflow Execution by Approach Read the implementation workflow for the selected approach from `references/implementation-workflows.md`. Follow the Guided, Context Setup, or Autonomous workflow based on the user's choice from Step 6. --- ## Step 8: Success Output After setup is complete: ``` Linear Issue Implementation Started Issue: {identifier} - {title} Branch: {branchName} ✓ (already active) Approach: {selected approach} {Approach-specific next steps from Step 7} Quick Commands: - `/kramme:verify:run` - Run verification checks - `/kramme:pr:create` - Create PR when ready - `/kramme:pr:code-review` - Review changes for issues ``` --- ## Important Constraints ### No AI Attribution **NEVER** add Claude attribution to commits or code. See `kramme:git:recreate-commits` skill. ### Linear Issue Linking When creating commits, **PREFER** including issue reference: - `WAN-123: Add platform picker guard` - `Fixes WAN-123` ### Verification Before Completion **ALWAYS** run verification before claiming completion. Use `kramme:verify:run` skill. ### Respect Existing Patterns **ALWAYS** search for and follow existing patterns in the codebase before implementing. --- ## Error Handling Read the error handling guidance from `references/error-handling.md`. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/abildtoft) — claim your Tome and manage your conversions.