Plan Task

/plan-task $ARGUMENTS

You are starting the task-level planning phase. Your goal is to design focused implementation steps for a single task — either a standalone task or a sub-task within an existing epic. Architecture decisions are already made (in the epic plan or in the Jira ticket); you refine the details into concrete, TDD-driven implementation steps.

Step 0 — Parse arguments

$ARGUMENTS contains the raw input. Split it into:

• TASK_ID: the first whitespace-separated token (e.g., MLID-2082).
• EXTRA_CONTEXT: everything after the first token, with surrounding quotes ("..." or '...') stripped. May be empty.

Treat EXTRA_CONTEXT as user guidance about how to plan — not as part of the ticket itself. It can narrow scope, point to reference implementations, flag constraints, or highlight a specific concern. If empty, proceed normally.

For the rest of this skill, use TASK_ID wherever the Jira ticket is referenced, and surface EXTRA_CONTEXT at the steps noted below.

Step 1 — Read the Jira ticket

Use the Atlassian MCP to read the Jira issue TASK_ID:

• Summary, description, and acceptance criteria
• Story points and issue type
• Parent/epic link — this determines if it's standalone or an epic sub-task

Step 2 — Determine task type and load context

If standalone task (no parent epic):

• Read docs/agomez/dx/task-git-branch-strategy.md
• Base branch: develop
• No prior architectural context to load

If epic sub-task (has parent epic):

• Read docs/agomez/dx/epic-git-branch-strategy.md
• Find and read the epic plan-progress file at docs/agomez/plans/. Search for files matching the epic ID.
• From the plan-progress, extract:
  • Architecture decisions already made
  • Data models already designed or built
  • What's already been implemented (completed tasks/deliverables)
  • What deliverable this task belongs to
  • Dependencies on other tasks
  • Integration points and data shapes defined in the epic plan
• Base branch: the epic branch (noted in the plan-progress file)

This is critical: The epic plan-progress contains architecture, data models, and design decisions that are the source of truth. Do NOT re-investigate or re-decide things that are already settled in the epic plan.

Also check the current git branch with git branch --show-current.

Step 3 — Investigate the codebase (focused)

Launch the codebase-investigator agent with a prompt that includes:

• The Jira ticket summary and acceptance criteria
• If epic sub-task: the relevant architectural context from the plan-progress (data models, service layer functions, API patterns already decided)
• Specific areas to investigate based on what this task touches
• If EXTRA_CONTEXT is non-empty: include it verbatim in a "User guidance" section so the investigator can scope its search accordingly

The investigation should be narrow and focused — only the files and patterns directly relevant to this task. The investigator does NOT need to understand the whole epic.

Tell the investigator to focus on:

• Files this task will create or modify
• Existing functions/services this task will call or extend
• Test patterns used in adjacent test files
• Exact data shapes at integration boundaries

Wait for the investigation results.

Step 4 — Design the implementation plan

Launch the solution-architect agent with:

• The Jira ticket details (from Step 1)
• The epic context summary (from Step 2, if epic sub-task)
• The codebase investigation summary (from Step 3)
• The task type (standalone vs epic sub-task)
• The plan template: docs/agomez/dx/individual-task-workflow.md
• If EXTRA_CONTEXT is non-empty: include it verbatim under a "User guidance for planning" section, and instruct the architect to honor it (e.g., scope narrowing, preferred patterns, constraints)

Tell the architect:

• Architecture decisions are already made — do not redesign. Reference the epic plan for data models, API contracts, and service layer design.
• Focus on implementation steps: ordered, TDD-driven (RED -> GREEN -> REFACTOR), each step a single commit.
• Be specific: exact file paths, function signatures, type definitions, test cases.
• For epic sub-tasks, the base branch is the epic branch, not develop.
• Never write a migration number into the plan. Not the next number, not the current last journal entry, not "as a sanity check". Many engineers push to develop daily, so both migration sequences — Drizzle in packages/db/migrations and Mongo db-update — move constantly, and a number written into a plan is wrong within days while still reading as an input. Refer to a migration by what it does, and where the number matters, state the rule instead of a figure: read it from the migration journal at the moment the migration is generated, and read it again immediately before the branch merges.
• Number every open question. If the plan has an Open Questions section with one or more entries, each entry gets a stable identifier — Q1, Q2, Q3 — written into the entry itself, so the user can answer them by number in conversation, in review comments and in the Jira ticket. Format each as - **Q<n> — <the question>?** <reasoning and recommendation>. Numbers are assigned in the order the questions appear and are never reused and never renumbered: when a question is later answered, its answer is recorded under its own number rather than the entry being deleted, so a reference to "Q3" means the same thing months later. Add a short note at the top of the section stating that convention. If there are no open questions, say so in one line and add no numbering.

Model: use sonnet — the hard architectural thinking was done in /plan-epic. This is execution planning.

The architect writes the plan to docs/agomez/plans/{TASK_ID}-short-description.md (use the parsed TASK_ID, not the raw $ARGUMENTS).

Step 5 — Present the plan for approval

After the architect completes:

1. Read the plan file that was written
2. Present the full plan to the user inline
3. STOP and wait for approval

Tell the user:

• "Here's the implementation plan for TASK_ID. Review the steps and let me know if you'd like changes, or approve it to proceed with /implement-task TASK_ID." (substitute the actual task ID)
• Do NOT proceed to write any implementation code

Important Rules

• No implementation code — this skill only produces a task plan document
• Always use both agents — investigator first, then architect
• Always stop for approval — never auto-proceed to implementation
• Respect the epic plan — if this is a sub-task, the epic plan-progress is the source of truth for architecture. Do not contradict it.
• Focused scope — plan only what this task requires. Don't plan adjacent tasks or redesign the architecture.
• Plan file: docs/agomez/plans/{TASK_ID}-short-description.md (separate file, not inside the epic plan-progress)
• No migration numbers in the plan — refer to a migration by what it does, never by number, for the reason given in Step 4. Check this when you read the plan back in Step 5 and strip any number the architect wrote in, replacing it with the read-the-journal rule. The same applies to anything you say when presenting the plan.
• Open questions are always numbered — Q1, Q2, Q3, assigned in document order, never reused, never renumbered when one is answered. Verify this when you read the plan back in Step 5, and fix it yourself if the architect returned an unnumbered list. When you present the plan and when you discuss the questions afterwards, refer to them by number.
• Extra context is guidance, not requirements — EXTRA_CONTEXT shapes how you plan, but the Jira ticket remains the source of truth for what the task is. If the two appear to conflict, surface the conflict to the user before proceeding.