القائمة
Prepare a Plane epic for implementation by refining requirements, creating detailed subtasks with relations, and writing test cases. Use before /implement-task to ensure requirements are clear.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Implement a complete Plane epic by reading tasks, understanding dependencies, and coding sequentially. Use when working on a full epic or multi-task feature.
Generate product documentation for an epic and publish to Plane wiki. Use when opening a PR to staging branch or after completing epic implementation.
استنادا إلى تصنيف SOC المهني
| name | prepare-task |
| description | Prepare a Plane epic for implementation by refining requirements, creating detailed subtasks with relations, and writing test cases. Use before /implement-task to ensure requirements are clear. |
Use this skill to take a Plane epic and prepare it for implementation
Key Differentiator: Unlike /implement-task (which writes code), this skill produces only plain English specifications ready for implementation.
/prepare-task <EPIC-ID>
Example: /prepare-task BETON-42 or /prepare-task INSP-15
Use the Plane MCP tools to read the epic:
mcp__plane__retrieve_work_item_by_identifier:
- project_identifier: <PROJECT> (e.g., "BETON", "INSP")
- sequence_id: <NUMBER> (e.g., "42")
Read and note:
Note: Epics are a separate entity type in Plane, but
retrieve_work_item_by_identifierworks for them because they share the identifier scheme. If this call returns unexpected results, see the Understanding Epics in Plane section for troubleshooting.
Check the epic description for:
Use WebFetch to read linked resources and extract requirements.
If the epic already has subtasks or relations:
mcp__plane__list_work_items:
- project_id: <uuid from epic>
- parent_id: <epic uuid>
Or:
mcp__plane__list_work_item_relations:
- project_id: <uuid from epic>
- work_item_id: <epic uuid>
Note any existing structure to build upon.
This is the most critical phase. Requirements often have ambiguities, gaps, and undefined behaviors.
Review the epic description and identify:
Ambiguities:
Gaps:
Undefined Behaviors:
Do that for both backend and frontend.
Use AskUserQuestion to clarify requirements. Group questions by topic:
Edge Cases & Error Handling:
Integration Specifics:
UX Decisions:
Priority & Scope:
Repeat Step 2.2 until:
Keep a record of all decisions made during clarification, e.g.:
## Decisions Made
1. **Empty state handling**: Show "No items yet" message with CTA
2. **Rate limiting**: Implement exponential backoff with 3 retries
3. **Error display**: Toast notification for transient errors, inline for validation
...
Enhance the epic description with:
Note:
update_work_itemworks for epics despite them being a separate entity type in Plane. The MCP tool handles them transparently.
Use mcp__plane__update_work_item to update the epic:
mcp__plane__update_work_item:
- project_id: <project uuid>
- work_item_id: <epic uuid>
- description_html: <updated HTML description>
Example Updated Description (HTML):
<h2>Overview</h2>
<p>[Refined description of what the epic accomplishes]</p>
<h2>Acceptance Criteria</h2>
<ul>
<li>[ ] Criterion 1 (specific, testable)</li>
<li>[ ] Criterion 2</li>
<li>[ ] Criterion 3</li>
</ul>
<h2>Technical Constraints</h2>
<ul>
<li>Must use existing Supabase client pattern</li>
<li>API must support pagination</li>
</ul>
<h2>Out of Scope</h2>
<ul>
<li>Bulk operations (future epic)</li>
<li>Export functionality (future epic)</li>
</ul>
<h2>Decisions Made</h2>
<ul>
<li><strong>Empty state:</strong> Show "No items yet" with CTA</li>
<li><strong>Error handling:</strong> Toast for API errors, inline for validation</li>
</ul>
Break the epic into tasks that:
Typical task categories:
For each task, use mcp__plane__create_work_item with structured description:
mcp__plane__create_work_item:
- project_id: <project uuid>
- name: <task title>
- description_html: <structured description - see template below>
- type: <task type id>
- parent: <epic uuid> # Links this work item as a child of the epic
IMPORTANT: Set parent to the epic's UUID to establish the parent-child relationship. This is how work items are associated with epics in Plane.
Epic parent constraint: Each work item can belong to at most one epic via the
parentfield. The parent must be a work item type whereis_epic: true. If the epic type is not found, verify epics are enabled in the project settings and runlist_work_item_typesto confirm.
For tasks with dependencies, create relations:
mcp__plane__create_work_item_relation:
- project_id: <project uuid>
- work_item_id: <source task uuid>
- related_work_item_id: <target task uuid>
- relation_type: "blocking" # or "blocked_by", "relates_to"
Relation types:
blocking: This task blocks the target taskblocked_by: This task is blocked by the target taskrelates_to: Tasks are related but not dependentFor each feature area in the epic, identify:
Create separate test tasks for each major feature area:
mcp__plane__create_work_item:
- project_id: <project uuid>
- name: "Test: <feature name>"
- description_html: <test cases - see template below>
- type: <task type id>
- parent: <epic uuid>
Link test tasks to their implementation tasks:
mcp__plane__create_work_item_relation:
- project_id: <project uuid>
- work_item_id: <test task uuid>
- related_work_item_id: <implementation task uuid>
- relation_type: "relates_to"
Make sure that implementation tasks depend on test tasks. This way, you will write the tests firsts and then code that passes it, not the other way around. No cheating!
Where helpful, add Mermaid diagrams to task descriptions:
Sequence Diagram (API Flow):
```mermaid
sequenceDiagram
participant U as User
participant F as Frontend
participant A as API
participant D as Database
U->>F: Click action
F->>A: POST /api/resource
A->>D: Insert record
D-->>A: Return ID
A-->>F: 201 Created
F-->>U: Show success
**State Diagram (Workflow):**
stateDiagram-v2
[*] --> Draft
Draft --> Pending: Submit
Pending --> Active: Approve
Pending --> Draft: Reject
Active --> Completed: Finish
Completed --> [*]
**ER Diagram (Data Model):**
erDiagram
WORKSPACE ||--o{ ACCOUNT : contains
ACCOUNT ||--o{ SIGNAL : generates
SIGNAL }o--|| SIGNAL_TYPE : has
#### Step 6.2: Attach Documentation Links
For each relevant task, attach documentation:
mcp__plane__create_work_item_link:
**Common link types:**
- Plane wiki pages
- GitHub repos
- Third-party API docs (PostHog, Stripe, etc.)
- Design files (Figma)
- Internal architecture docs
> Important:
> If the task or subtask requires external API – link to the docs is mandatory
> If the task or subtask requires using a new open source tool – link to the repo and docs is mandatory
---
### Phase 7: API Exploration
If the tasks or involves third-party APIs:
#### Step 7.1: Identify APIs Involved
List all external APIs the task requires
#### Step 7.2: Request Credentials
Use `AskUserQuestion` to request:
- API keys (for testing)
- Environment details (staging vs production)
- Rate limit information
- Special access requirements
**Never hardcode credentials** - request them interactively.
#### Step 7.3: Test APIs
Use curl to understand API behavior:
```bash
# Example: Test an API endpoint
curl -s -H "Authorization: Bearer $API_KEY" \
"https://api.example.com/v1/resource" | jq
If you only get 4xx and 5xx – use AskUserQuestion again for correct credentials/documentation
Document:
Add concrete API examples to relevant subtask descriptions:
<h3>API Reference</h3>
<p><strong>Request:</strong></p>
<pre><code>
POST https://api.posthog.com/api/projects/{project_id}/events
Headers: Authorization: Bearer {api_key}
Body: { "event": "page_view", "distinct_id": "user_123" }
</code></pre>
<p><strong>Response:</strong></p>
<pre><code>
{
"status": 1,
"queued": true
}
</code></pre>
<p><strong>Error Response (401):</strong></p>
<pre><code>
{ "detail": "Authentication credentials were not provided." }
</code></pre>
| Tool | Purpose |
|---|---|
mcp__plane__retrieve_work_item_by_identifier | Fetch epic by ID (e.g., BETON-42) |
mcp__plane__update_work_item | Update epic description |
mcp__plane__create_work_item | Create subtasks (set parent to epic ID) |
mcp__plane__create_work_item_relation | Link tasks: blocking, blocked_by, relates_to |
mcp__plane__create_work_item_link | Attach documentation URLs |
mcp__plane__create_work_item_comment | Add notes/decisions to items |
mcp__plane__list_work_items | List items in a project (use parent_id to filter by epic) |
mcp__plane__list_work_item_relations | List relations for an item |
mcp__plane__list_work_item_types | List work item types; identify epic types via is_epic: true flag |
Phase 1: Discovery
Phase 2: Clarification
AskUserQuestionPhase 3: Refinement
Phase 4: Task Breakdown
parent to epic ID for all subtasksPhase 5: Test Planning
Phase 6: Documentation
Phase 7: API Exploration
All content is plain English (no code implementations)
After running /prepare-task BETON-42, the epic might have:
Updated Epic Description:
Subtasks Created:
BETON-43: Add database migration for new table
BETON-44: Create API endpoint for resource
BETON-45: Build frontend form component
BETON-46: Test: Resource CRUD operations
Links Attached:
| Issue | Solution |
|---|---|
| Epic not found | Verify project identifier and sequence ID |
| MCP tool fails | Check Plane connection with /mcp status |
| Can't create subtask | Ensure parent is set to epic's UUID |
| Relation not created | Verify both work item UUIDs exist |
| User not responding to questions | Simplify questions, provide context |
| Epic type not found | Run list_work_item_types and look for is_epic: true; verify epics are enabled in project settings |
/implement-task - use prepare-task first, then implement-taskAskUserQuestion - never hardcodedrelates_to relation