| name | x-ipe-task-based-technical-design |
| description | Create technical design for a single feature. Queries feature board, reads specification, designs solution with KISS/YAGNI/DRY principles. Creates two-part design document. Triggers on requests like "design feature", "technical design", "architecture planning". |
Task-Based Skill: Technical Design
Purpose
Create technical design for a single feature by:
- Querying feature board for full Feature Data Model
- Reading feature specification document
- Researching best practices and existing patterns
- Creating two-part technical design document
- NO board status update (handled by category skill)
Important Notes
BLOCKING: Learn x-ipe-workflow-task-execution skill before executing this skill.
Note: If Agent does not have skill capability, go to .github/skills/ folder to learn skills. SKILL.md is the entry point.
BLOCKING: Single Feature Only. This skill operates on exactly ONE feature at a time. Do NOT batch or combine multiple features in a single execution. If multiple features need processing, run this skill separately for each feature.
Workflow Mode: When execution_mode == "workflow-mode", the completion step MUST 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 workflow.name input, action from workflow.action input, status: "done", and a deliverables keyed dict using ONLY the extract tags defined in workflow-template.json for this action (format: {"tag-name": "path/to/file"}). Do NOT pass a flat list of file paths. Verify the script exits with code 0 before marking the task complete.
Key Rules
- Two-Part Document: All technical designs use Part 1 (Agent-Facing Summary) + Part 2 (Implementation Guide). See references/design-principles.md for structure details.
- Single File: Maintain ONE
technical-design.md per feature. Do NOT create versioned files. Use Version History table inside the document.
- Design Principles: Follow KISS, YAGNI, DRY, and 800-line module threshold. See references/design-principles.md for details.
- Document Location: Feature-specific at
x-ipe-docs/requirements/FEATURE-XXX/technical-design.md; cross-feature at x-ipe-docs/architecture/technical-designs/{component}.md.
- Templates: See references/design-templates.md for full document template, Part 1/Part 2 guidelines, dependency table format, mockup reference guidelines, and diagram examples.
Mockup List Loading
When mockup_list input is needed, resolve in this order:
- Previous Idea Mockup task's
task_output_links
- Human-provided explicit path
- Feature specification's "Linked Mockups" section
- Idea summary's "Mockups & Prototypes" section
- Default: N/A
MANDATORY: When mockup_list is provided AND scope includes [Frontend] or [Full Stack], the agent MUST open, analyze, extract UI requirements, and reference mockups in Part 2.
IMPORTANT: When process_preference.interaction_mode == "dao-represent-human-to-interact", NEVER stop to ask the human. Instead, call x-ipe-assistant-user-representative-Engineer to get the answer. The DAO skill acts as the human representative and will provide the guidance needed to continue.
Input Parameters
input:
task_id: "{TASK-XXX}"
task_based_skill: "x-ipe-task-based-technical-design"
execution_mode: "free-mode | workflow-mode"
workflow:
name: "N/A"
extra_context_reference:
specification: "path | N/A | auto-detect"
category: "feature-stage"
next_task_based_skill:
- skill: "x-ipe-task-based-code-implementation"
condition: "Implement the designed feature"
process_preference:
interaction_mode: "{from input process_preference.interaction_mode}"
feature_phase: "Technical Design"
mockup_list: "N/A"
feature_id: "{FEATURE-XXX}"
Input Initialization
<input_init>
<field name="task_id" source="x-ipe-tool-task-board-manager (auto-generated)" />
<field name="execution_mode" source="x-ipe-workflow-task-execution (from --workflow-mode@{name})" />
<field name="workflow.name" source="x-ipe-workflow-task-execution (from --workflow-mode@{name})" />
<field name="process_preference.interaction_mode" source="from caller (x-ipe-workflow-task-execution) or default 'interact-with-human'" />
<field name="feature_id" source="previous task | task board | human input">
<steps>
1. Check previous task (Feature Refinement) output for feature_id
2. If not available, query task board for current feature context
3. If still unresolved, ask human for feature_id
</steps>
</field>
<field name="extra_context_reference.specification" source="workflow context | auto-detect">
<steps>
1. If workflow-mode: read from workflow context extra_context_reference.specification
2. If free-mode or auto-detect: resolve from x-ipe-docs/requirements/{feature_id}/specification.md
3. Default: N/A
</steps>
1. IF previous task was "Feature Refinement" → use previous task output's mockup_list field (or derive from linked_mockups)
2. ELIF human provides explicit mockup links → use human-provided value
3. ELSE → set to N/A
Note on program_type and tech_stack: These fields are determined during Step 5 (not provided as input). The agent identifies them from the design decisions and includes them in the Output Result for downstream skills.
Definition of Ready
<definition_of_ready>
<checkpoint required="true">
<name>Feature exists on feature board</name>
<verification>Query feature board for feature_id; confirm entry exists</verification>
</checkpoint>
<checkpoint required="true">
<name>Feature status is "Done Feature Refinement"</name>
<verification>Check feature status field equals "Done Feature Refinement"</verification>
</checkpoint>
<checkpoint required="true">
<name>Feature specification document exists</name>
<verification>Verify file exists at x-ipe-docs/requirements/FEATURE-XXX/specification.md</verification>
</checkpoint>
</definition_of_ready>
Execution Flow
| Phase | Steps | Action | Gate |
|---|
| 1. 博学之 — Study Broadly | 1.1 Query Feature Board, 1.2 Read Specification | Load feature data, read specification | Full context gathered |
| 2. 审问之 — Inquire Thoroughly | 2.1 Reference Architecture, 2.2 Research Best Practices | Check existing patterns, research libraries and best practices | Research complete |
| 3. 慎思之 — Think Carefully | 3.1 Create Technical Design Document | Write two-part technical design document | Design written |
| 4. 明辨之 — Discern Clearly | 4.1 Self-Critique Design | AI validates design against spec; escalates ONLY specific unresolvable conflicts | Design validated |
| 5. 笃行之 — Practice Earnestly | 5.1 Complete | Verify DoD, update workflow, output summary | Task complete |
| 继续执行 | 6.1 | Decide Next Action | Next action decided |
| 继续执行 | 6.2 | Execute Next Action | Execution started |
BLOCKING: Phase 1 fails if feature not on board or status not "Done Feature Refinement".
BLOCKING (manual/stop_for_question): Phase 4 - present design, ask if architecture decisions are correct before Code Implementation.
BLOCKING (auto): Proceed automatically after DoD verification.
Execution Procedure
<procedure name="technical-design">
<execute_dor_checks_before_starting/>
<schedule_dod_checks_with_sub_agent_before_starting/>
<phase_0 name="Board — Register Task">
<step_0_1>
<name>Create Task on Board</name>
<action>
Call `x-ipe-tool-task-board-manager` → `task_create.py`:
- task_type: "Technical Design"
- description: summarize work from input context
- status: "in_progress"
- role: from input context
- assignee: from input context
Store returned task_id for later update.
</action>
<output>Task created on board with status in_progress</output>
</step_0_1>
</phase_0>
<phase_1 name="博学之 — Study Broadly">
<step_1_1>
<name>Query Feature Board</name>
<action>
1. CALL x-ipe-tool-task-board-manager skill:
operation: query_feature
feature_id: {feature_id from task_data}
2. RECEIVE Feature Data Model:
feature_id, title, version, status, specification_link
</action>
<constraints>
- BLOCKING: Feature must exist on board with status "Done Feature Refinement"
Feature Data Model with specification_link
Read Specification
0. Resolve extra_context_reference inputs:
- FOR ref specification:
IF workflow mode AND extra_context_reference.specification is a file path:
READ the file at that path (use instead of specification_link)
ELIF extra_context_reference.specification is "auto-detect":
Use existing discovery logic below
ELIF extra_context_reference.specification is "N/A":
Skip this context input
ELSE (free-mode / absent):
Use existing behavior
1. READ {specification_link} from Feature Data Model
2. UNDERSTAND:
- User stories and acceptance criteria
- Business rules and constraints
- Edge cases documented
- Dependencies on other features
- CRITICAL: Do NOT proceed to design until spec is fully understood
Comprehensive understanding of feature requirements
Reference Architecture
1. READ x-ipe-docs/architecture/ for existing patterns
2. IDENTIFY reusable components, established conventions, integration requirements
3. AVOID reinventing existing solutions
List of applicable patterns and reusable components
Research Best Practices
1. CONSULT TOOL SKILLS (config-filtered):
a. DISCOVER: Scan .github/skills/x-ipe-tool-implementation-*/ for available tools
b. READ CONFIG: Read x-ipe-docs/config/tools.json → stages.implement.technical_design
- IF section missing/empty → config_active = false (all discovered tools enabled)
- ELSE → config_active = true (opt-in filtering); force-enable general
c. FILTER: IF config_active → only ENABLED tools participate
d. FOR EACH enabled tool: read "Built-In Practices" and "Operations" sections
e. DOCUMENT as "Tool Capability Summary" (informational only — not binding)
2. SEARCH official documentation, libraries, reference implementations, API docs
3. IF mockup_list provided AND scope includes [Frontend] or [Full Stack]:
OPEN and analyze all mockup files. EXTRACT layout, components, spacing, colors, interactions. The mockup is source of truth for visual design.
4. DOCUMENT findings for design decisions (include tool capability summary)
- Tool consultation is INFORMATIONAL ONLY — do not invoke tools for code execution
- Part 2 format MUST remain independent of tool availability (FR-048.1.5)
Research findings including tool capability summary and mockup constraints if applicable
Create Technical Design Document
1. WRITE two-part technical design at x-ipe-docs/requirements/FEATURE-XXX/technical-design.md
2. ADAPT structure based on implementation type (API, CLI, frontend, backend)
3. USE templates from references/design-templates.md
4. IF mockup_list provided AND scope includes [Frontend] or [Full Stack]:
Open mockup files, extract UI component requirements, design frontend components based on mockup layout, reference mockup in Part 2
ELSE: Focus on service architecture, data models, APIs
5. INCLUDE Design Change Log section at end of document
6. IDENTIFY and record program_type and tech_stack:
- program_type: classify using known types (non-exhaustive, extend as needed):
- "frontend": Browser-only (HTML/CSS/JS, no server logic)
- "backend": Server-only (API, services, data processing)
- "fullstack": Both server routes AND browser UI (JS/CSS)
- "cli": Command-line tool
- "library": Reusable package/module
- "skills": Agent skill definitions (SKILL.md, prompt engineering)
- "mcp": MCP server tools/endpoints
- Other types may emerge as tech evolves — use descriptive lowercase names
- tech_stack: list all technologies used (e.g. ["Python/Flask", "JavaScript/Vanilla", "HTML/CSS", "pytest"])
- These are passed to downstream skills (Test Generation, Code Implementation) to determine test types
7. LEVERAGE tool capability summary from Step 2.2:
- Reference tool built-in practices instead of duplicating (e.g., "Python tool enforces PEP 8")
- Focus Part 2 on what tools NEED: module boundaries, API contracts, data models
- Note: Part 2 format remains independent of tool availability
- MANDATORY: Part 1 must have component table with Tags for semantic search
- MANDATORY: Part 1 must have usage example
- 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)`.
- CRITICAL: Follow KISS/YAGNI/DRY principles
Complete two-part technical design document
Self-Critique Design
1. AI self-critique — validate the design against objective criteria:
a. Every specification acceptance criterion maps to a component or flow
b. No contradictions between chosen patterns (e.g., stateless API + server-side sessions)
c. Technology choices are compatible (versions, licenses, runtime)
d. No over-engineering: each component has a clear reason from the spec
2. Collect unresolved_questions[] — ONLY items AI genuinely cannot decide:
- Trade-offs needing user preference (e.g., "Redis vs Memcached?")
- Business-domain constraints AI lacks context for
- Conflicting requirements needing human prioritization
3. IF unresolved_questions is EMPTY → design is validated, proceed
4. IF unresolved_questions is NON-EMPTY:
IF process_preference.interaction_mode == "dao-represent-human-to-interact":
→ Invoke x-ipe-assistant-user-representative-Engineer with specific questions list
ELSE:
→ Present ONLY the specific questions to human (not "review the whole design")
→ Incorporate answers, revise affected sections
- MUST NOT ask broad "is this correct?" — only ask specific, bounded questions
- IF self-critique passes with zero questions → skip human/DAO entirely
Design validated (self-critique passed or specific questions resolved)
Complete
1. VERIFY all DoD checkpoints are met
2. 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: {workflow.action}
- status: "done"
- feature_id: {feature_id}
- deliverables: {"tech-design": "{path to technical-design.md}", "feature-docs-folder": "{path to FEATURE-XXX/ folder}"}
b. Log: "Workflow action status updated to done"
3. OUTPUT task completion summary
- All required DoD checkpoints pass
- Design document created at correct location
- feature_phase set to "Technical Design"
Task completion output with design document link, workflow_action_updated
Update Board
1. Call `x-ipe-tool-task-board-manager` → `task_update.py`:
- task_id: from Phase 0
- status: "done"
- output_links: list of deliverables produced in this skill execution
2. Call `x-ipe-tool-task-board-manager` → `feature_update.py`:
- feature_id: from input context
- status: "Designed"
Task marked done, feature status updated to Designed
Decide Next Action
Collect the full context and task_completion_output from this skill execution.
IF process_preference.interaction_mode == "dao-represent-human-to-interact":
→ Invoke x-ipe-assistant-user-representative-Engineer with:
type: "routing"
completed_skill_output: {full task_completion_output YAML from this skill}
next_task_based_skill: "{from output}"
context: "Skill completed. Study the context and full output to decide best next action."
→ DAO studies the complete context and decides the best next action
ELSE (interact-with-human):
→ Present next pipeline step hint to human:
"✅ Technical design complete for {feature_id}.
Next step: Code Implementation — implement {feature_id}.
Want me to proceed?"
→ Wait for human instruction
- BLOCKING (manual): Human MUST confirm or redirect before proceeding
- BLOCKING (auto): Proceed after DoD verification; auto-select next task via DAO
Next action decided with execution context
Execute Next Action
Based on the decision from Step 6.1:
1. Load the target task-based skill's SKILL.md
2. Generate an execution plan from the skill's Execution Flow table
3. Start execution from the skill's first phase/step
- MUST load the skill before executing — do not skip skill loading
- Execution follows the target skill's procedure, not this skill's
Next task execution started
Output Result
task_completion_output:
category: "feature-stage"
status: completed | blocked
next_task_based_skill:
- skill: "x-ipe-task-based-code-implementation"
condition: "Implement the designed feature"
process_preference:
interaction_mode: "{from input process_preference.interaction_mode}"
execution_mode: "{from input}"
workflow:
name: "{from input}"
workflow_action: "{workflow.action}"
workflow_action_updated: true | false
task_output_links:
- "x-ipe-docs/requirements/FEATURE-XXX/technical-design.md"
mockup_list: {from input mockup_list, pass to next task if applicable}
feature_id: "FEATURE-XXX"
feature_title: "{title}"
feature_version: "{version}"
feature_phase:
[, , ]
Definition of Done
CRITICAL: Use a sub-agent to validate DoD checkpoints independently.
<definition_of_done>
<checkpoint required="true">
<name>Technical design document created</name>
<verification>File exists at x-ipe-docs/requirements/FEATURE-XXX/technical-design.md</verification>
</checkpoint>
<checkpoint required="true">
<name>Part 1 has component table with tags</name>
<verification>Verify "Key Components Implemented" table exists with Tags column</verification>
</checkpoint>
<checkpoint required="true">
<name>Part 1 has usage example</name>
<verification>Verify "Usage Example" section exists with code snippet</verification>
</checkpoint>
<checkpoint required="recommended">
<name>Part 2 has workflow diagrams (Mermaid)</name>
<verification>Check for mermaid code blocks in Part 2</verification>
Part 2 has class diagram (Mermaid)
Check for classDiagram mermaid block in Part 2
Part 2 adapted to implementation type
Verify Part 2 sections match implementation type (API/CLI/frontend/backend)
KISS/YAGNI/DRY principles followed
Review design for over-engineering, speculative features, or unnecessary duplication
Mockup List analyzed (if provided AND frontend scope)
If mockup_list != N/A and scope is Frontend/Full Stack, verify mockup was referenced
UI components derived from mockup (if frontend scope)
If frontend scope with mockup, verify component breakdown references mockup
Workflow Action Updated
If execution_mode == "workflow-mode", ran `workflow_update_action.py` script with status "done" and deliverables keyed dict
MANDATORY: After completing this skill, return to x-ipe-workflow-task-execution to continue the task execution flow.
Patterns & Anti-Patterns
| Pattern | When | Key Actions |
|---|
| API-Based | REST/GraphQL endpoints | Focus Part 2 on API spec, request/response schemas, auth, sequence diagrams |
| Background Service | Background process | Fault tolerance, retry/backoff, monitoring points, state diagrams |
| UI-Heavy | Primarily frontend | Component architecture, state management, mockup references (mockup = source of truth) |
| Anti-Pattern | Why Bad | Do Instead |
|---|
| Over-engineering | Wasted effort | Apply KISS principle |
| Future-proofing | YAGNI violation | Design for current needs |
| No research | Reinventing wheels | Research existing solutions |
| Monolithic design | Hard to change | Design modular components |
| Missing workflows | Hard to understand | Always include Mermaid diagrams |
| No tags | Hard for AI to find | Always add searchable tags |
Examples
See references/examples.md for detailed execution examples.
