Task-Based Skill: Ideation

Purpose

Learn and refine user ideas through collaborative brainstorming by:

1. Analyzing uploaded idea files from Workplace
2. Generating an initial understanding summary
3. Asking clarifying questions to brainstorm with user
4. Creating a structured idea summary document with visual infographics
5. Preparing for Idea Mockup, Idea to Architecture, or Requirement Gathering

---

Important Notes

BLOCKING: Learn x-ipe-workflow-task-execution skill before executing this skill.

CRITICAL: Only use tools that are explicitly enabled (true) in x-ipe-docs/config/tools.json under stages.ideation. Only true counts as enabled -- false, absent, or any other value means DISABLED. The tools.json config is the single source of truth for which tools are allowed.

Note: If Agent does not have skill capability, go to .github/skills/ folder to learn skills. SKILL.md is the entry point.

---

Input Parameters

input:
  task_id: "{TASK-XXX}"
  task_based_skill: "Ideation"
  
  category: ideation-stage
  next_task_based_skill: "Idea Mockup | Idea to Architecture"
  require_human_review: yes
  
  auto_proceed: false
  execution_mode: "free-mode | workflow-mode"  # default: free-mode; set by x-ipe-workflow-task-execution
  idea_folder_path: "x-ipe-docs/ideas/{folder}"
  toolbox_meta_path: "x-ipe-docs/config/tools.json"
  extra_instructions: "{N/A | from config | from human}"

Extra Instructions Loading

loading_logic:
  - step: 1
    condition: "human provides explicit Extra Instructions"
    action: "Use human-provided value"
  - step: 2
    condition: "x-ipe-docs/config/tools.json exists"
    action: "Read stages.ideation.ideation._extra_instruction field"
  - step: 3
    condition: "field not found or empty"
    action: "Set Extra Instructions = N/A"

---

Definition of Ready

<definition_of_ready>
  <checkpoint required="true">
    <name>Idea Files Uploaded</name>
    <verification>Files exist in x-ipe-docs/ideas/{folder}/</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Human Available</name>
    <verification>Human available for brainstorming session</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Idea Folder Path Provided</name>
    <verification>Path to idea folder specified</verification>
  </checkpoint>
</definition_of_ready>

---

Execution Flow

Step	Name	Action	Gate
1	Load Toolbox	Read tools.json config, output enabled tool list	config loaded
2	Analyze Files	Read all files in idea folder	files analyzed
3	Generate Summary	Create understanding summary	summary shared
4	Brainstorm	Ask clarifying questions (3-5 at a time)	idea refined
5	Research	Search for common principles	research complete
6	Generate Draft	Create idea draft, prefer enabled tools from step 1	draft created
7	Critique	Sub-agent provides constructive feedback	feedback received
8	Improve Summary	Incorporate feedback, prefer enabled tools from step 1	summary finalized
9	Rename Folder	Rename if "Draft Idea - xxx"	folder renamed
10	Complete	Request human review	human approves

BLOCKING: Step 4 - Continue brainstorming until idea is well-defined.

BLOCKING: Step 10 - Human MUST approve idea summary before proceeding.

---

Execution Procedure

<procedure name="ideation-v2">

  <step_1>
    <name>Load Ideation Toolbox Meta</name>
    <action>
      1. Check if x-ipe-docs/config/tools.json exists
      2. If exists: parse JSON, extract tools from stages.ideation
      3. If NOT exists: create default config with all tools disabled
      4. Load Extra Instructions (human → config → N/A)
      5. Build and output the enabled tool list -- only tools with value `true` count as enabled; `false`, absent, or any other value means DISABLED
      6. BLOCKING: For each enabled tool that has a corresponding skill at .github/skills/{tool-name}/SKILL.md, LOAD that skill now. This ensures correct syntax and grammar are available before any content generation.
      7. Output format:
         ```
         Enabled tools: [list of enabled tool names]
         Disabled tools: [list of disabled tool names]
         Loaded tool skills: [list of skills loaded in step 6]
         ```
    </action>
    <output>tool_config, enabled_tool_list, extra_instructions</output>
  </step_1>

  <step_2>
    <name>Analyze Idea Files</name>
    <action>
      1. Navigate to x-ipe-docs/ideas/{folder}/files/
      2. Read each file (text, markdown, code, etc.)
      3. Identify key themes, concepts, and goals
      4. Note any gaps or ambiguities
    </action>
    <constraints>
      - BLOCKING: All files must be analyzed before proceeding
    </constraints>
    <output>initial_analysis</output>
  </step_2>

  <step_3>
    <name>Generate Understanding Summary</name>
    <action>
      1. Create summary of what you understand
      2. Include: Core Concept, Key Goals, Identified Components
      3. List Questions and Ambiguities
      4. List enabled tools from step 1
      5. Share summary with user for validation
    </action>
    <output>understanding_summary</output>
  </step_3>

  <step_4>
    <name>Brainstorming Session</name>
    <action>
      1. Ask questions in batches (3-5 at a time)
      2. Wait for human response before proceeding
      3. Build on previous answers
      4. Challenge assumptions constructively
      5. IF extra_instructions is provided and non-empty:
         - Incorporate extra_instructions as additional context/guidance for the refinement
         - Treat as user preference that supplements (not replaces) the idea content
      6. When the user describes something visual (UI layouts, flows, system structure), proactively generate visual artifacts to enrich the brainstorming -- select the most appropriate enabled tool from step 1's tool list for the content type
    </action>
    <constraints>
      - BLOCKING: Continue until idea is well-defined
      - CRITICAL: Batch questions (3-5), do not overwhelm
      - MANDATORY: Only use tools that appear in the enabled tool list from step 1
    </constraints>
    <output>brainstorming_notes, artifacts[]</output>
  </step_4>

  <step_5>
    <name>Research Common Principles</name>
    <action>
      1. Identify if topic is common/established (auth, API, UI/UX, security)
      2. IF topic is common: research industry best practices, design patterns, document findings as "Common Principles", note authoritative sources
         ELSE: skip this step
    </action>
    <output>common_principles[], references[]</output>
  </step_5>

  <step_6>
    <name>Generate Idea Draft</name>
    <action>
      1. Synthesize outputs from steps 3, 4, 5 (summary, brainstorming, research)
      2. Determine version number (auto-increment)
      3. Output path: {idea_folder}/refined-idea/idea-summary-vN.md
         a. Create {idea_folder}/refined-idea/ folder if it does not exist
         b. IF folder already exists and contains previous output: clear it (overwrite mode)
         c. Write all refined output files to {idea_folder}/refined-idea/
      4. Create draft using template from templates/idea-summary.md
      5. RECOMMENDED: Use enabled tools from step 1's tool list to create rich visual content (diagrams, infographics, architecture views) -- select the most appropriate tool for each content type
      6. If no tools are enabled: use standard markdown (bullet lists, tables)
      7. Link to artifacts created during brainstorming
    </action>
    <constraints>
      - CRITICAL: Only use tools that appear in the enabled tool list from step 1 -- if a tool is not in the enabled list, do NOT use it
      - MANDATORY: Include all sections from template
      - RECOMMENDED: Prefer enabled tools over plain markdown for richer idea presentation
    </constraints>
    <output>idea_draft</output>
  </step_6>

  <step_7>
    <name>Critique and Feedback</name>
    <action>
      1. Invoke sub-agent to review the idea draft
      2. Sub-agent evaluates against quality criteria
      3. Sub-agent provides constructive feedback
    </action>
    <sub_agent>
      role: idea-critic
      goal: Provide constructive feedback on idea draft
      model_hint: sonnet
      evaluation_criteria:
        - Clarity: Is the problem statement clear?
        - Completeness: Are all key sections filled?
        - Consistency: Do sections align with each other?
        - Feasibility: Are goals realistic?
        - Visualization: Are enabled tools used effectively?
      feedback_format:
        - Strengths: What works well
        - Improvements: Specific actionable suggestions
        - Questions: Clarifications needed
    </sub_agent>
    <constraints>
      - CRITICAL: Feedback must be constructive, not just critical
      - MANDATORY: Include specific improvement suggestions
    </constraints>
    <output>critique_feedback</output>
  </step_7>

  <step_8>
    <name>Improve and Deliver Summary</name>
    <action>
      1. Review critique feedback from step 7
      2. Address each improvement suggestion
      3. Resolve any questions raised
      4. RECOMMENDED: Use enabled tools from step 1's tool list to enhance or add visual content where feedback suggests improvements -- select the most appropriate tool for each content type
      5. IF feedback requires minor-to-moderate changes:
         → Update the existing draft in-place
         IF feedback requires extensive rewrite (majority of sections affected):
         → Rewrite the file from scratch (same path)
      6. Finalize at {idea_folder}/refined-idea/idea-summary-vN.md
    </action>
    <constraints>
      - MANDATORY: Update the existing draft file in-place — do NOT create a new versioned file for critique improvements
      - CRITICAL: All feedback items must be addressed
      - CRITICAL: Only use tools that appear in the enabled tool list from step 1
    </constraints>
    <output>idea_summary_path</output>
  </step_8>

  <step_9>
    <name>Rename Folder</name>
    <action>
      1. Check if folder matches "Draft Idea - MMDDYYYY HHMMSS"
      2. IF folder matches draft pattern AND idea has clear identity:
         a. Generate new name based on idea content (2-5 words, Title Case)
         b. Rename folder to "{Idea Name} - {timestamp}"
         c. Update internal links
         ELSE: skip rename
    </action>
    <output>folder_renamed, new_folder_name</output>
  </step_9>

  <step_10>
    <name>Complete and Request Review</name>
    <action>
      1. IF execution_mode == "workflow-mode":
         a. Call update_workflow_action MCP with:
            - workflow_name: {from context}
            - action: "refine_idea"
            - status: "done"
            - deliverables: [list of output file paths]
         b. Log: "Workflow action status updated to done"
      2. Present final idea summary to human
      3. Ask human to choose next task
      4. Wait for approval
    </action>
    <constraints>
      - BLOCKING: Human MUST approve before proceeding
    </constraints>
    <output>human_approval, next_task_choice, workflow_action_updated</output>
  </step_10>

</procedure>

---

Output Result

task_completion_output:
  category: ideation-stage
  status: completed | blocked
  next_task_based_skill: "Idea Mockup | Idea to Architecture"
  require_human_review: yes
  task_output_links:
    - "x-ipe-docs/ideas/{folder}/refined-idea/idea-summary-vN.md"
    - "x-ipe-docs/ideas/{folder}/mockups/mockup-vN.html"
  # Dynamic attributes
  execution_mode: "free-mode | workflow-mode"  # propagated from input
  workflow_action: "refine_idea"        # triggers workflow status update when execution_mode == workflow-mode
  workflow_name: "{from context}"       # used to locate workflow JSON
  workflow_action_updated: true | false # true if update_workflow_action was called
  idea_id: "IDEA-XXX"
  idea_status: Refined
  idea_version: "vN"
  idea_folder: "{renamed folder name or original}"
  folder_renamed: true | false

Next Task Selection

After ideation completes, ask human to choose:

next_task_options:
  - option: "Idea Mockup"
    best_for: "Ideas with strong UI focus"
  - option: "Idea to Architecture"
    best_for: "Ideas requiring system design, integrations"
  - option: "Skip to Requirement Gathering"
    best_for: "Simple ideas or when mockups/architecture not needed"

---

Definition of Done

CRITICAL: Use a sub-agent to validate DoD checkpoints independently.

CRITICAL: Every step output in Execution Procedure MUST have a corresponding DoD checkpoint.

<definition_of_done>
  <checkpoint required="true">
    <name>Config Loaded</name>
    <verification>x-ipe-docs/config/tools.json loaded, enabled tool list output</verification>
    <step_output>tool_config, enabled_tool_list, extra_instructions</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Files Analyzed</name>
    <verification>All files in idea folder analyzed</verification>
    <step_output>initial_analysis</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Understanding Summary Shared</name>
    <verification>Initial understanding summary shared with user</verification>
    <step_output>understanding_summary</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Brainstorming Complete</name>
    <verification>Idea is well-defined with clear goals</verification>
    <step_output>brainstorming_notes, artifacts[]</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Draft Created</name>
    <verification>Idea draft generated, enabled tools from step 1 used where appropriate</verification>
    <step_output>idea_draft</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Critique Received</name>
    <verification>Sub-agent provided constructive feedback</verification>
    <step_output>critique_feedback</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Feedback Addressed</name>
    <verification>All critique items addressed in final summary</verification>
    <step_output>N/A (validation step)</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Summary Created</name>
    <verification>x-ipe-docs/ideas/{folder}/refined-idea/idea-summary-vN.md exists</verification>
    <step_output>idea_summary_path</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Human Approved</name>
    <verification>Human has reviewed and approved idea summary</verification>
    <step_output>human_approval, next_task_choice</step_output>
  </checkpoint>
  <checkpoint required="recommended">
    <name>Folder Renamed</name>
    <verification>Draft folder renamed if applicable</verification>
    <step_output>folder_renamed, new_folder_name</step_output>
  </checkpoint>
  <checkpoint required="recommended">
    <name>Principles Researched</name>
    <verification>Common principles researched if topic is established</verification>
    <step_output>common_principles[], references[]</step_output>
  </checkpoint>
  <checkpoint required="if-applicable">
    <name>Workflow Action Status Updated</name>
    <verification>If execution_mode == "workflow-mode", called update_workflow_action MCP with status "done" and deliverables list</verification>
  </checkpoint>
</definition_of_done>

MANDATORY: After completing this skill, return to x-ipe-workflow-task-execution to continue the task execution flow.

---

Patterns & Anti-Patterns

Pattern: Raw Notes Upload

When: User uploads unstructured notes or braindump
Then:

1. Extract key themes from notes
2. Organize into logical categories
3. Ask clarifying questions about each category
4. Help structure into coherent idea

Pattern: Technical Specification Upload

When: User uploads detailed technical spec
Then:

1. Validate technical feasibility
2. Ask about business goals (why this spec?)
3. Identify missing user context
4. Connect technical details to user value

Pattern: Multiple Conflicting Ideas

When: Uploaded files contain conflicting approaches
Then:

1. Surface the conflicts clearly
2. Ask user to prioritize or choose
3. Help evaluate trade-offs
4. Document decision rationale

Anti-Patterns

Anti-Pattern	Why Bad	Do Instead
Summarizing without questions	Misses refinement	Engage in brainstorming
Too many questions at once	Overwhelms user	Batch 3-5 questions
Accepting at face value	May miss issues	Challenge constructively
Skipping to requirements	Idea not refined	Complete ideation first
Ignoring tools.json	Uses wrong tools	Always check enabled tool list from step 1
Using disabled tools	Violates config	Only use tools in the enabled list

---

Examples

See references/examples.md for concrete execution examples:

• Business plan ideation with tools enabled
• Ideation without tools (all disabled)
• Missing config file handling
• Draft folder rename scenario