devflow:build:plan-issue

Plan Work

I'll analyze issue $ARGUMENTS and create a detailed implementation plan.

---

Step 1: Load Configuration and Fetch Issue

Use the build-ops skill to:

1. Load backend configuration from devflow-config.md
2. Fetch issue $ARGUMENTS from the configured issue tracker

The build-ops skill handles all backend-specific operations (Jira, GitLab, GitHub) and enforces parameter validation. See skills/build-ops/SKILL.md.

3. Extract: Summary, Description, Acceptance Criteria, Issue Type/Labels
4. TDD is the default. Check if $ARGUMENTS contains --no-tdd flag (if yes: TDD Mode DISABLED; if no: TDD Mode ENABLED)
5. Proceed to Step 2

---

Step 2: Analyze Codebase

Based on the issue requirements, let me analyze the existing codebase.

Note for AI Assistants - ANALYSIS PHASE

Codebase Analysis:

• Use Grep/Glob to search for related code
• Identify existing patterns (imports, error handling, logging, structure)
• Find integration points
• Document code patterns to follow

If the issue is a bug: Load references/bug-fix-planning.md for guidance on root cause analysis, impact assessment, and planning the fix approach. The plan should address root cause, not just symptoms.

TDD is the default. Detect the repo's test framework, test patterns, and test commands. Understand how existing tests are structured so the plan can specify a TDD workflow that follows established patterns. If --no-tdd was specified, still analyze the testing setup but plan a test-after approach instead.

After gathering this information, proceed to Step 3.

---

Step 3: Research with Context7

Now I'll research relevant technologies, libraries, and frameworks to ensure we follow current best practices.

Note for AI Assistants - RESEARCH PHASE

ALWAYS use Context7 research when:

• Issue involves implementing a new feature (research the domain/approach)
• Issue mentions ANY specific library or framework (research current docs)
• Issue requires integration with external services/APIs
• Issue involves a technology you need current best practices for
• Issue type is Feature, Story, or Epic

For each technology/library identified:

1. Use mcp__context7__resolve-library-id to identify the library
2. Use mcp__context7__get-library-docs to fetch current documentation
3. Document in your analysis:
   • Current best practices and recommended patterns
   • Version-specific considerations
   • Common pitfalls to avoid
   • Integration patterns relevant to this codebase

Skip Context7 research ONLY when:

• Issue is a simple bug fix in existing code
• Issue is refactoring with no new dependencies
• Issue is documentation-only changes

After research, proceed to Step 4.

---

Step 4: Present Draft Plan for Approval

Based on my analysis, here's the proposed implementation plan for $ARGUMENTS:

Issue Summary: [Issue type, summary, key requirements]

Acceptance Criteria: [Breakdown of each criterion]

Codebase Analysis: [Existing patterns found, integration points, files to modify]

Implementation Plan:

1. Files to create/modify: [specific paths]
2. Functions/components to implement: [details]
3. Code patterns to follow: [from codebase analysis]
4. Integration approach: [how it connects]

Testing Strategy (TDD by default):

• Test framework: [detected from repo]
• Existing test patterns: [from analysis]
• Test cases derived from acceptance criteria
• TDD workflow: RED (failing tests) → GREEN (implement to pass) → REFACTOR
• [If --no-tdd: describe test-after approach instead]

Context7 Research: [Best practices, patterns, version notes - if applicable]

Documentation Updates: [Files to update: README, docs/, .reference/, code comments]

Commit Strategy:

1. [Logical unit 1] - refs $ARGUMENTS
2. [Logical unit 2] - refs $ARGUMENTS
3. [etc.]

---

Does this plan look good? Would you like any changes?

You can:

• Type "yes" or "approved" to finalize and save the plan
• Request changes like "add more detail to testing" or "research authentication patterns"
• Ask questions about any part of the plan

Take your time to review - we'll iterate until you're satisfied.

Note for AI Assistants - APPROVAL PHASE

[WAIT FOR USER RESPONSE BEFORE CONTINUING]

After user responds:

• If user approves (says "yes", "approved", "looks good", "go ahead", "lgtm", "ship it", etc.):

  • Acknowledge approval
  • Proceed to Step 5
  • Write the final plan to .devflow/plans/$ARGUMENTS.md

• If user requests changes (says "change X", "add Y", "remove Z", "make it more detailed", "research [technology]", etc.):

  • Acknowledge their feedback
  • Re-analyze codebase if they want more technical details
  • Re-research with Context7 if they mention new technologies/patterns
  • Revise the specific sections they mentioned
  • Present the COMPLETE revised plan using the same format as above
  • Ask the same approval question again: "Does this plan look good? Would you like any changes?"
  • [WAIT FOR USER RESPONSE BEFORE CONTINUING]
  • Repeat this cycle until they explicitly approve

• If user asks questions (seeks clarification about approach, asks "why X", etc.):

  • Answer their questions thoroughly
  • Offer to revise the plan if needed based on the discussion
  • [WAIT FOR USER RESPONSE BEFORE CONTINUING]

CRITICAL: Do NOT proceed to Step 5 until user explicitly approves with phrases like "yes", "approved", "looks good", "go ahead", "lgtm", etc.

---

Step 5: Save Approved Plan

✅ Plan approved!

Save the final plan to .devflow/plans/$ARGUMENTS.md with these sections:

1. Issue Summary — type, key requirements, acceptance criteria
2. Codebase Analysis — patterns found, integration points, files to modify
3. Implementation Plan — approach, components to build, code patterns to follow
4. Testing Strategy — TDD workflow (default) with test framework, test cases from acceptance criteria, and test commands. If --no-tdd was specified, describe the test-after approach instead.
5. Context7 Research (if performed) — best practices, patterns, version notes
6. Documentation Updates — files to update
7. Commit Strategy — logical units, each with a description and commit message referencing $ARGUMENTS. Each unit = one pause point during implementation where the developer reviews before continuing.

The commit strategy is critical — it defines the incremental units that implement-issue will execute, pausing after each one for developer review (unless --auto is used).

After saving, proceed to the completion message.

---

✅ Planning Complete

Your implementation plan has been saved to: .devflow/plans/$ARGUMENTS.md

---

📋 What Happens Next?

You have 2 options:

Option 1: Implement the Plan

By default, implementation pauses after each increment for your review:

/devflow:build:implement-issue $ARGUMENTS

This incremental mode will pause after each logical unit (commit) so you can:

• Review what changed (tests, implementation, documentation)
• Approve and continue to next increment
• Request revisions to the current increment
• Review specific files
• Or stop implementation if needed

OR run all increments continuously without pauses:

/devflow:build:implement-issue --auto $ARGUMENTS

Auto mode runs through all logical units from start to finish. Use this when you trust the plan and want hands-off execution.

---

Which mode should you use?

• New to the codebase? Use default incremental mode to learn as you go
• Complex feature? Use incremental mode to catch issues early
• Simple bug fix? Use --auto if the plan is straightforward
• High confidence? Use --auto for faster execution

---

What implement does:

• Create a feature branch for $ARGUMENTS
• Update issue status to "In Progress"
• Implement the code following your approved plan
• Run tests (TDD by default, or test-after if --no-tdd was used)
• Create commits referencing $ARGUMENTS

Option 2: Revise the Plan

If you thought of improvements, just tell me what to change:

• "Add more detail about error handling"
• "Research [library] for the authentication part"
• "Include database migration steps"

I'll update .devflow/plans/$ARGUMENTS.md and present the revised version.

---

🛑 Planning Phase Complete

This command has finished its job. The plan is saved and ready for implementation.

No code has been written. This command ONLY creates plans - the /devflow:build:implement-issue command handles all code changes, testing, commits, and PR/MR creation.

---

Note for AI Assistants - COMMAND COMPLETE

This command is FINISHED. Stop here.

Do NOT:

• Implement any code
• Create branches
• Make commits
• Update issue tracker
• Create pull requests
• Use Edit or MultiEdit tools

The /devflow:build:implement-issue command will handle all implementation tasks.