name	workflows-plan
description	This skill should be used when transforming feature descriptions, bug reports, or improvement ideas into well-structured project plans following project conventions and best practices.

Create a Plan for a New Feature or Bug Fix

Note: The current year is 2025. Use this when dating plans and searching for recent documentation.

Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown plan files that follow project conventions and best practices.

Getting Started

If no feature description is provided, ask:

What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind.

Do not proceed until a clear feature description is available.

Main Tasks

1. Repository Research & Context Gathering

Spawn three sub-agents in parallel to research:

Repository Research - Analyze the codebase for existing patterns, similar implementations, and project conventions
Best Practices Research - Search for industry best practices and patterns relevant to the feature
Framework Documentation Research - Find relevant framework/library documentation for the implementation

Reference Collection:

Document all research findings with specific file paths (e.g., app/services/example_service.rb:42)
Include URLs to external documentation and best practices guides
Create a reference list of similar issues or PRs
Note any team conventions discovered in AGENTS.md or team documentation

2. Issue Planning & Structure

Title & Categorization:

Draft clear, searchable issue title using conventional format (e.g., feat:, fix:, docs:)
Determine issue type: enhancement, bug, refactor

Stakeholder Analysis:

Identify who will be affected (end users, developers, operations)
Consider implementation complexity and required expertise

Content Planning:

Choose appropriate detail level based on issue complexity and audience
List all necessary sections for the chosen template
Gather supporting materials (error logs, screenshots, design mockups)
Prepare code examples or reproduction steps if applicable

3. SpecFlow Analysis

After planning the issue structure, spawn a sub-agent to validate and refine the feature specification:

Analyze the feature description and research findings for completeness
Identify gaps, edge cases, and potential issues
Update acceptance criteria based on findings

4. Choose Implementation Detail Level

Select how comprehensive the plan should be—simpler is mostly better.

📄 MINIMAL (Quick Issue)

Best for: Simple bugs, small improvements, clear features

Includes:

Problem statement or feature description
Basic acceptance criteria
Essential context only

Structure:

[Brief problem/feature description]

## Acceptance Criteria

-  [ ] Core requirement 1
-  [ ] Core requirement 2

## Context

[Any critical information]

## MVP

### example.rb

```ruby
class Example
  def initialize
    @name = "example"
  end
end
```

References

Related issue: #[issue_number]
Documentation: [relevant_docs_url]


#### 📋 MORE (Standard Issue)

**Best for:** Most features, complex bugs, team collaboration

**Includes everything from MINIMAL plus:**
- Detailed background and motivation
- Technical considerations
- Success metrics
- Dependencies and risks
- Basic implementation suggestions

**Structure:**

```markdown
## Overview

[Comprehensive description]

## Problem Statement / Motivation

[Why this matters]

## Proposed Solution

[High-level approach]

## Technical Considerations

- Architecture impacts
- Performance implications
- Security considerations

## Acceptance Criteria

- [ ] Detailed requirement 1
- [ ] Detailed requirement 2
- [ ] Testing requirements

## Success Metrics

[How we measure success]

## Dependencies & Risks

[What could block or complicate this]

## References & Research

- Similar implementations: [file_path:line_number]
- Best practices: [documentation_url]
- Related PRs: #[pr_number]

📚 A LOT (Comprehensive Issue)

Best for: Major features, architectural changes, complex integrations

Includes everything from MORE plus:

Detailed implementation plan with phases
Alternative approaches considered
Extensive technical specifications
Resource requirements and timeline
Future considerations and extensibility
Risk mitigation strategies
Documentation requirements

Structure:

## Overview

[Executive summary]

## Problem Statement

[Detailed problem analysis]

## Proposed Solution

[Comprehensive solution design]

## Technical Approach

### Architecture

[Detailed technical design]

### Implementation Phases

#### Phase 1: [Foundation]

-  Tasks and deliverables
-  Success criteria
-  Estimated effort

#### Phase 2: [Core Implementation]

-  Tasks and deliverables
-  Success criteria
-  Estimated effort

#### Phase 3: [Polish & Optimization]

-  Tasks and deliverables
-  Success criteria
-  Estimated effort

## Alternative Approaches Considered

[Other solutions evaluated and why rejected]

## Acceptance Criteria

### Functional Requirements

-  [ ] Detailed functional criteria

### Non-Functional Requirements

-  [ ] Performance targets
-  [ ] Security requirements
-  [ ] Accessibility standards

### Quality Gates

-  [ ] Test coverage requirements
-  [ ] Documentation completeness
-  [ ] Code review approval

## Success Metrics

[Detailed KPIs and measurement methods]

## Dependencies & Prerequisites

[Detailed dependency analysis]

## Risk Analysis & Mitigation

[Comprehensive risk assessment]

## Resource Requirements

[Team, time, infrastructure needs]

## Future Considerations

[Extensibility and long-term vision]

## Documentation Plan

[What docs need updating]

## References & Research

### Internal References

-  Architecture decisions: [file_path:line_number]
-  Similar features: [file_path:line_number]
-  Configuration: [file_path:line_number]

### External References

-  Framework documentation: [url]
-  Best practices guide: [url]
-  Industry standards: [url]

### Related Work

-  Previous PRs: #[pr_numbers]
-  Related issues: #[issue_numbers]
-  Design documents: [links]

5. Issue Creation & Formatting

Content Formatting:

Use clear, descriptive headings with proper hierarchy (##, ###)
Include code examples in triple backticks with language syntax highlighting
Add screenshots/mockups if UI-related
Use task lists (- [ ]) for trackable items
Add collapsible sections for lengthy logs using <details> tags
Apply appropriate emoji for visual scanning (🐛 bug, ✨ feature, 📚 docs, ♻️ refactor)

Cross-Referencing:

Link to related issues/PRs using #number format
Reference specific commits with SHA hashes when relevant
Link to code using permanent links
Mention relevant team members if needed
Add links to external resources with descriptive text

AI-Era Considerations:

Account for accelerated development with AI pair programming
Include prompts or instructions that worked well during research
Note which AI tools were used for initial exploration
Emphasize comprehensive testing given rapid implementation
Document any AI-generated code that needs human review

6. Final Review & Submission

Pre-submission Checklist:

Title is searchable and descriptive
Labels accurately categorize the issue
All template sections are complete
Links and references are working
Acceptance criteria are measurable
Add names of files in pseudo code examples and todo lists
Add an ERD mermaid diagram if applicable for new model changes

Output Format

Write the plan to plans/<issue_title>.md

Post-Generation Options

After writing the plan file, present these options:

Plan ready at plans/<issue_title>.md. What would you like to do next?

Open plan in editor - Open the plan file for review

Deepen plan - Enhance each section with parallel research (best practices, performance, UI)

Review plan - Get feedback from reviewers (reference @guidance/reviewers/ if available)

Start work - Begin implementing this plan (reference @workflows-work skill)

Create Issue - Create issue in project tracker (GitHub/Linear)

Simplify - Reduce detail level

Based on selection:

Open plan → Run open plans/<issue_title>.md
Deepen plan → Spawn sub-agents to research and enhance each section
Review plan → Reference @guidance/reviewers/ for reviewer perspectives
Start work → Reference @workflows-work skill to begin implementation
Create Issue → See "Issue Creation" section below
Simplify → Ask "What should I simplify?" then regenerate simpler version

Loop back to options after Simplify or other changes until implementation or review begins.

Issue Creation

When creating an issue, detect the project tracker from AGENTS.md:

Check for tracker preference in AGENTS.md (global or project):
- Look for project_tracker: github or project_tracker: linear

If GitHub:

gh issue create --title "feat: [Plan Title]" --body-file plans/<issue_title>.md

If Linear:

linear issue create --title "[Plan Title]" --description "$(cat plans/<issue_title>.md)"

If no tracker configured: Ask: "Which project tracker do you use? (GitHub/Linear/Other)" Suggest adding project_tracker: github or project_tracker: linear to AGENTS.md
After creation:
- Display the issue URL
- Ask if implementation or review should proceed

NEVER CODE! Just research and write the plan.

workflows-plan

Install Skill

SKILL.md