<procedure name="ideation">
<execute_dor_checks_before_starting/>
<schedule_dod_checks_with_sub_agent_before_starting/>
<phase_1 name="博学之 — Study Broadly">
<step_1_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. Resolve extra_instructions (see Input Initialization)
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. If `x-ipe-tool-web-search` is enabled, mark it available for Step 1.3 research calls.
8. 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, loaded_tool_skills</output>
</step_1_1>
<step_1_2>
<name>Analyze Idea Files</name>
<action>
0. Resolve extra_context_reference inputs:
- FOR EACH ref in [raw-ideas, uiux-reference]:
IF workflow mode AND extra_context_reference.{ref} is a file path:
READ the file at that path
ELIF extra_context_reference.{ref} is "auto-detect":
Use existing discovery logic below
ELIF extra_context_reference.{ref} is "N/A":
Skip this context input
ELSE (free-mode / absent):
Use existing behavior
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_1_2>
<step_1_3>
<name>Research Common Principles</name>
<action>
1. Identify if topic is common/established (auth, API, UI/UX, security)
2. IF topic is common AND `x-ipe-tool-web-search` appears in enabled_tool_list:
- Invoke `x-ipe-tool-web-search` with operation `research_topic`
- Pass topic, research goal, and 2-3 focused questions
- Use returned findings to document "Common Principles" and authoritative sources
ELIF topic is common:
- Research using existing model knowledge only
- Note that no external citations were fetched
ELSE: skip this step
</action>
<output>common_principles[], references[], web_research_summary</output>
</step_1_3>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<step_2_1>
<name>Generate Understanding Summary</name>
<action>
1. Create summary of what you understand from Phase 1 analysis
2. Include: Core Concept, Key Goals, Identified Components
3. List Questions and Ambiguities
4. List enabled tools from step 1.1
5. Share summary with user for validation
</action>
<output>understanding_summary</output>
</step_2_1>
<step_2_2>
<name>Brainstorming Session</name>
<action>
1. Ask yourself two questions, 'which mode interaction_mode is in?'
2. Ask questions in batches (3-5 at a time) to avoid overwhelming, iterate based on user responses
3. Wait for response based on interaction_mode condition before proceeding
4. Build on previous answers
5. Challenge assumptions constructively
6. 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
7. 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.1's tool list for the content type
Response source (based on interaction_mode):
IF process_preference.interaction_mode == "dao-represent-human-to-interact":
→ Resolve ambiguities via x-ipe-assistant-user-representative-Engineer
→ Build comprehensive brainstorming notes from source material + decisions
ELSE (interact-with-human/dao-represent-human-to-interact-for-questions-in-skill):
→ Ask human for response
</action>
<constraints>
- BLOCKING: Continue until idea is well-defined
- CRITICAL (manual/stop_for_question): Ask human for response
- CRITICAL (auto): Resolve all ambiguities via x-ipe-assistant-user-representative-Engineer, do not ask human
- MANDATORY: Only use tools that appear in the enabled tool list from step 1.1
</constraints>
<output>brainstorming_notes, artifacts[]</output>
</step_2_2>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<step_3_1>
<name>Critique and Feedback</name>
<action>
1. Invoke sub-agent to review the brainstorming results and idea concept
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 concept and brainstorming results
model_hint: sonnet
evaluation_criteria:
- Clarity: Is the problem statement clear?
- Completeness: Are all key aspects covered?
- Consistency: Do elements 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_3_1>
</phase_3>
<phase_4 name="明辨之 — Discern Clearly">
<step_4_1>
<name>Improve and Decide on Feedback</name>
<action>
1. Review critique feedback from step 3.1
2. Decide which improvement suggestions to incorporate
3. Resolve any questions raised
4. Document decisions: which feedback accepted, which deferred, and why
5. Finalize the approach and content direction for drafting
</action>
<constraints>
- CRITICAL: All feedback items must be addressed (accepted or explicitly deferred with rationale)
</constraints>
<output>improvement_decisions, finalized_approach</output>
</step_4_1>
</phase_4>
<phase_5 name="笃行之 — Practice Earnestly">
<step_5_1>
<name>Generate Idea Draft</name>
<action>
1. Synthesize outputs from all phases: study (1.1-1.3), inquiry (2.1-2.2), critique (3.1), decisions (4.1)
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.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
8. Apply improvement decisions from step 4.1
</action>
<constraints>
- CRITICAL: Only use tools that appear in the enabled tool list from step 1.1 -- if a tool is not in the enabled list, do NOT use it
- MANDATORY: Include all sections from template
- MANDATORY: File links in generated markdown MUST use project-root-relative paths so the UI can intercept them and open a preview modal. **Avoid** relative paths (`../`, `./`, `../../`) and absolute filesystem paths (`/Users/...`). **Correct:** `[spec](x-ipe-docs/requirements/EPIC-001/specification.md)`, `[skill](.github/skills/x-ipe-task-based-bug-fix/SKILL.md)`. **Wrong:** `[spec](../specification.md)`, `[spec](./specification.md)`.
- RECOMMENDED: Prefer enabled tools over plain markdown for richer idea presentation
</constraints>
<output>idea_summary_path</output>
</step_5_1>
<step_5_2>
<name>Complete and Request Review</name>
<action>
1. IF execution_mode == "workflow-mode":
a. Run the workflow update script via bash (`python3 .github/skills/x-ipe-tool-x-ipe-app-interactor/scripts/workflow_update_action.py`) with:
- workflow_name: {from context}
- action: "refine_idea" ← HARDCODED: always use "refine_idea", NEVER "compose_idea" or any other action
- status: "done"
- deliverables: {"refined-idea": "{path to idea-summary file}", "refined-ideas-folder": "{path to refined-idea/ folder}"}
b. Log: "Workflow action status updated to done"
2. Verify all DoD checkpoints are met
3. Present final idea summary
4. Ask if any aspects of the idea are missing or unclear
5. IF human/DAO identifies gaps → revise specific sections
Response source (based on interaction_mode):
IF process_preference.interaction_mode == "dao-represent-human-to-interact":
→ Auto-select next task from next_task_based_skill after DoD verification
ELSE (interact-with-human/dao-represent-human-to-interact-for-questions-in-skill):
→ Ask human if idea is complete before proceeding
</action>
<constraints>
- BLOCKING (manual/stop_for_question): Human MUST confirm idea is complete before proceeding
- BLOCKING (auto): Proceed after DoD verification; auto-select next task
</constraints>
<output>next_task_choice, workflow_action_updated</output>
</step_5_2>
</phase_5>
<phase_6 name="继续执行（Continue Execute）">
<step_6_1>
<name>Decide Next Action</name>
<action>Collect task_completion_output. IF interaction_mode == "dao-represent-human-to-interact": invoke x-ipe-assistant-user-representative-Engineer with type: "routing", completed_skill_output, next_task_based_skill. ELSE: present next task suggestion to human.</action>
<constraints>
- BLOCKING (manual): Human MUST confirm or redirect
- BLOCKING (auto): Auto-select next task via DAO after DoD verification
</constraints>
<output>Next action decided</output>
</step_6_1>
<step_6_2>
<name>Execute Next Action</name>
<action>Load target skill's SKILL.md, generate execution plan, start from first phase.</action>
<constraints>MUST load skill before executing — follows target skill's procedure.</constraints>
<output>Next task execution started</output>
</step_6_2>
</phase_6>
</procedure>
<definition_of_done>
<checkpoint required="true">
<name>Config Loaded</name>
<verification>x-ipe-docs/config/tools.json loaded, enabled tool list output, and enabled skill-backed tools loaded</verification>
</checkpoint>
<checkpoint required="true">
<name>Files Analyzed</name>
<verification>All files in idea folder analyzed</verification>
</checkpoint>
<checkpoint required="true">
<name>Understanding Summary Shared</name>
<verification>Initial understanding summary shared with user</verification>
</checkpoint>
<checkpoint required="true">
<name>Brainstorming Complete</name>
<verification>Idea is well-defined with clear goals</verification>
</checkpoint>
<checkpoint required="true">
<name>Draft Created</name>
<verification>Idea draft generated, enabled tools from step 1.1 used where appropriate</verification>
</checkpoint>
<checkpoint required="true">
<name>Critique Received</name>
<verification>Sub-agent provided constructive feedback</verification>
</checkpoint>
<checkpoint required="true">
<name>Feedback Addressed</name>
<verification>All critique items addressed — accepted or explicitly deferred with rationale</verification>
</checkpoint>
<checkpoint required="true">
<name>Summary Created and Complete</name>
<verification>x-ipe-docs/ideas/{folder}/refined-idea/idea-summary-vN.md exists with all sections filled and key decisions documented</verification>
</checkpoint>
<checkpoint required="recommended">
<name>Principles Researched</name>
<verification>Common principles researched if topic is established; web-search tool used when enabled and needed</verification>
</checkpoint>
<checkpoint required="if-applicable">
<name>Workflow Action Status Updated</name>
<verification>If execution_mode == "workflow-mode", ran `workflow_update_action.py` script with status "done" and deliverables keyed dict</verification>
</checkpoint>
</definition_of_done>
