practical-stack · p-iknow · Oct 25, 2025 · Oct 25, 2025 · Oct 25, 2025
diff --git a/.claude/commands/make-task-issue.md b/.claude/commands/make-task-issue.md
diff --git a/.claude/commands/plan-issue.md b/.claude/commands/plan-issue.md
@@ -10,7 +10,9 @@ allowed-tools:
 
 # Plan Issue
 
-Fetch a GitHub issue and create an interactive, detailed implementation plan with clear rationale for each decision.
+Fetch a well-structured GitHub issue and create an interactive, detailed implementation plan with clear rationale for each decision.
+
+**Note**: This command works best with issues created using `/make-task-issue`, which provides structured Context, Requirement, and Solution sections. This command focuses on breaking down the problem into actionable implementation steps, not on defining the problem itself.
 
 ## Usage
 
@@ -46,35 +48,52 @@ Extract and analyze:
 
 ### 3. Analyze Issue Content
 
-Parse the issue body to understand:
-
-**Problem/Requirement Analysis:**
-- What is the core problem or requirement?
-- Why does this need to be solved?
-- What is the expected outcome?
-- Are there any constraints or considerations?
-
-**Context Gathering:**
-- Review related files mentioned in the issue
+**Expected Issue Structure:**
+Issues created with `/make-task-issue` will have the following sections:
+- **Context**: Background and why this is needed
+- **Requirement**: What needs to be done and expected outcome
+- **Solution**: Proposed approach (may be empty or brief)
+- **Test Plan**: Success criteria (may be empty or brief)
+- **Reference**: Related files or documentation
+
+**Parse the issue body to extract:**
+- **Context section**: Understand the background and motivation
+- **Requirement section**: Identify what needs to be implemented
+- **Solution section**: Review any proposed approaches (if provided)
+- **Test Plan section**: Note any existing success criteria (if provided)
+
+**Additional Context Gathering:**
+- Review related files mentioned in the issue or Reference section
 - Check existing patterns in the codebase
 - Identify dependencies or related features
+- Use Read/Glob/Grep to explore relevant code
+
+**Note**: If the issue doesn't have this structure (e.g., older issues or manually created issues), do your best to extract similar information from whatever structure exists.
 
 ### 4. Generate Initial Plan
 
 Create a structured implementation plan with the following sections:
 
+**IMPORTANT - Separation of Concerns:**
+- The issue already contains Context, Requirement, and Solution (from `/make-task-issue`)
+- **DO NOT re-do problem definition work** - use what's already in the issue
+- **FOCUS ON** breaking down the solution into actionable implementation steps
+- Your job is to create a concrete execution plan, not to redefine the problem
+
 #### Problem Analysis
-- **What**: Clear statement of what needs to be solved
-- **Why**: Explanation of why this is important
-- **Context**: Relevant background information
+- **What**: Summarize from the issue's Requirement section (don't rewrite it)
+- **Why**: Reference the issue's Context section (don't re-analyze it)
+- **Context**: Pull from the issue's Context and Reference sections
 
 #### Solution Approach
-- **Strategy**: High-level approach to solving the problem
-- **Architecture**: Key design decisions and their rationale
+- **Strategy**: If the issue has a Solution section, elaborate on it; if not, propose one
+- **Architecture**: Key design decisions and their rationale (build on issue's Solution if provided)
 - **Alternatives Considered**: Other approaches and why they weren't chosen
 - **Trade-offs**: What we're optimizing for and what we're accepting
 
 #### Implementation Steps
+**This is the primary focus of this command.** Break down the work into concrete, actionable steps.
+
 For each step, include:
 - **Step description**: What will be done
 - **Rationale**: Why this step is necessary
@@ -83,9 +102,10 @@ For each step, include:
 - **Dependencies**: What needs to be done first
 
 #### Success Criteria
-- How will we know the implementation is complete?
-- What should be tested?
-- What documentation needs to be updated?
+- Start with what's in the issue's Test Plan section (if provided)
+- Add specific implementation verification steps
+- Include what should be tested
+- Note what documentation needs to be updated
 
 ### 5. Interactive Step-by-Step Review
 
@@ -203,11 +223,18 @@ After analyzing the issue, the command will generate a plan like:
 ## Best Practices
 
 ### Analysis
-- Read the issue thoroughly before planning
+- Read the issue thoroughly, especially Context, Requirement, and Solution sections
+- **Respect the work already done** in `/make-task-issue` - don't redo problem definition
 - Look for existing patterns in the codebase
 - Consider edge cases and error handling
 - Think about testing requirements
 
+### Separation of Concerns
+- **Problem definition** happens in `/make-task-issue` (Context, Requirement, Solution, Test Plan)
+- **Implementation planning** happens in `/plan-issue` (breaking down into steps)
+- Don't waste time re-analyzing what's already well-defined in the issue
+- Focus your energy on creating a concrete, actionable execution plan
+
 ### Communication
 - Be transparent about reasoning
 - Explain trade-offs clearly
@@ -225,3 +252,4 @@ After analyzing the issue, the command will generate a plan like:
 - Order steps logically with dependencies clear
 - Include both "what" and "why" for each step
 - Make success criteria measurable
+- **Primary focus**: Implementation Steps section - make it detailed and comprehensive
diff --git a/.github/ISSUE_TEMPLATE/agent.md b/.github/ISSUE_TEMPLATE/agent.md
@@ -7,24 +7,16 @@ assignees: ""
 
 ---
 
-## Requirement
-**What agent rule/command needs to be created/updated:**
+## Context
 
-## Implementation Plan (optional)
 
-**Rule/Command type:**
+## Requirement
 
-**Trigger conditions:**
 
-**Expected behavior:**
+## Solution
 
-**Files to be modified:**
 
-## Should be tested
+## Test Plan
 
-- [ ] Rule/command should be tested locally
-- [ ] Edge cases should be covered
-- [ ] Documentation should be updated (if applicable)
-- [ ] Documentation should referenced properly 
 
 ## Reference
diff --git a/.github/ISSUE_TEMPLATE/config.md b/.github/ISSUE_TEMPLATE/config.md
@@ -7,16 +7,16 @@ assignees: ""
 
 ---
 
+## Context
+
+
 ## Requirement
 
-## Implementation plan(optional)
 
-**Dependencies (if applicable):**
+## Solution
 
 
-## Should be tested
+## Test Plan
 
-- [ ] Configuration tested locally
-- [ ] CI/CD pipeline verified (if applicable)
 
 ## Reference
diff --git a/.github/ISSUE_TEMPLATE/doc.md b/.github/ISSUE_TEMPLATE/doc.md
@@ -7,20 +7,20 @@ assignees: ""
 
 ---
 
+## Context
+<!-- Why is this documentation needed? What's missing or unclear? -->
+
+
 ## Requirement
+<!-- What documentation needs to be created/updated? -->
 
-## Implementation Plan (optional)
 
-**Documentation type:**
+## Content Outline
+<!-- Document structure, sections, topics to cover -->
 
-**Content outline:**
 
-**Files to be modified:**
+## Verification
+<!-- How to verify documentation accuracy, examples tested, consistency checks -->
 
-## Should be tested
-- [ ] Documentation reviewed for accuracy
-- [ ] Examples tested and working
-- [ ] Consistency with existing documentation maintained
-- [ ] References and links properly connected
 
-## Reference (optionla)
+## Reference
diff --git a/.github/ISSUE_TEMPLATE/feat.md b/.github/ISSUE_TEMPLATE/feat.md
@@ -7,22 +7,16 @@ assignees: ""
 
 ---
 
-## Requirement
+## Context
 
-**What feature needs to be implemented:**
 
-## Implementation Plan (optional)
+## Requirement
 
-**Feature scope:**
 
-**Key components:**
+## Solution
 
-**Files to be modified:**
 
-## Should be tested
+## Test Plan
 
-- [ ] Feature tested locally
-- [ ] Edge cases covered
-- [ ] Documentation updated (if applicable)
 
-## Reference (optional)
+## Reference
diff --git a/.github/ISSUE_TEMPLATE/fix.md b/.github/ISSUE_TEMPLATE/fix.md
@@ -7,32 +7,20 @@ assignees: ""
 
 ---
 
-## Summary
+## Context
+<!-- Describe the bug: Steps to reproduce, Expected vs Current behavior -->
 
-A clear and concise description of what needs to be fixed.
 
-## Steps to Reproduce (if applicable)
+## Requirement
+<!-- What needs to be fixed -->
 
-1.
-2.
-3.
 
-## Expected Behavior
+## Solution
+<!-- Root cause analysis and fix approach -->
 
-## Current Behavior
 
-## Root Cause (optional)
+## Test Plan
+<!-- How to verify the fix, regression testing -->
 
-## Implementation Plan (optional)
 
-**Files to be modified:**
-
-**Approach:**
-
-## Should be tested
-
-- [ ] Fix verified locally
-- [ ] Regression testing completed
-- [ ] Edge cases covered
-
-## Reference (optional)
+## Reference
diff --git a/.github/ISSUE_TEMPLATE/perf.md b/.github/ISSUE_TEMPLATE/perf.md
@@ -7,29 +7,20 @@ assignees: ""
 
 ---
 
-## Requirement
-
-**What needs performance improvement:**
-
-**Current performance issue:**
+## Context
+<!-- Current performance issue and why it matters -->
 
-**Target performance goal:**
 
-## Implementation Plan (optional)
-
-**Approach:**
+## Requirement
+<!-- Target performance goals, metrics -->
 
-**Optimization strategy:**
 
-**Files to be modified:**
+## Solution
+<!-- Optimization strategy and approach -->
 
-**Breaking changes (if any):**
 
-## Should be tested
+## Verification
+<!-- Benchmarking method, performance testing, regression checks -->
 
-- [ ] Performance benchmarks run
-- [ ] Improvement verified and measured
-- [ ] No regression in other areas
-- [ ] Documentation updated with performance notes
 
-## Reference (optional)
+## Reference
diff --git a/.github/ISSUE_TEMPLATE/refactor.md b/.github/ISSUE_TEMPLATE/refactor.md
@@ -7,27 +7,20 @@ assignees: ""
 
 ---
 
-## Requirement
-
-**What needs to be refactored:**
+## Context
+<!-- Why is refactoring needed? Code quality issues, maintainability concerns -->
 
-**Why this refactoring is needed:**
 
-## Implementation Plan (optional)
-
-**Scope:**
+## Requirement
+<!-- What needs to be refactored and scope -->
 
-**Approach:**
 
-**Files to be modified:**
+## Solution
+<!-- Refactoring approach, breaking changes if any -->
 
-**Breaking changes (if any):**
 
-## Should be tested
+## Verification
+<!-- Ensuring no functional changes, all tests passing, quality metrics -->
 
-- [ ] Refactored code tested locally
-- [ ] No functional changes verified
-- [ ] All existing tests still passing
-- [ ] Code quality metrics improved (if applicable)
 
-## Reference (optional)
+## Reference
diff --git a/.github/ISSUE_TEMPLATE/test.md b/.github/ISSUE_TEMPLATE/test.md
@@ -7,27 +7,20 @@ assignees: ""
 
 ---
 
-## Requirement
+## Context
+<!-- Why are these tests needed? What's currently untested? -->
 
-**What tests need to be added/improved:**
 
-## Implementation Plan (optional)
+## Requirement
+<!-- What needs to be tested? -->
 
-**Test type:**
-- [ ] Unit tests
-- [ ] Integration tests
-- [ ] E2E tests
-- [ ] Performance tests
 
-**Test scope:**
+## Test Scope
+<!-- Test types (Unit/Integration/E2E/Performance), scope, coverage goals -->
 
-**Files to be modified:**
 
-## Should be tested
+## Verification
+<!-- How to verify tests are working, coverage metrics -->
 
-- [ ] Tests written and passing
-- [ ] Coverage improved (if applicable)
-- [ ] Edge cases covered
-- [ ] Test documentation added
 
-## Reference (optional)
+## Reference