# Start Task

> Start working on a task (claim, gather context, define acceptance criteria)

- Skill: `josephneumann/start-task` (Agent Skill)
- Install (CLI): `npx skillmds@latest add josephneumann/start-task`
- Raw SKILL.md: https://api.skillmd.com/api/skills/josephneumann/start-task/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: josephneumann (https://skillmd.com/u/josephneumann)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/josephneumann/start-task

---


# Start Task: $ARGUMENTS

You are starting work on a task. Follow this checklist precisely.

## 0. Parse Arguments

The command format is: `/start-task <task-id> [--handoff "<context>"]`

Parse `$ARGUMENTS` to extract:
- `task_id`: The task ID, e.g. INT-14 (everything before any flags)
- `handoff_context`: Optional inline handoff text (content in quotes after `--handoff` flag)

Examples:
- `/start-task INT-14` → task_id = `INT-14`
- `/start-task INT-14 --handoff "Use 3% tolerance"` → with handoff context

## 1. Validate and Claim Task (FIRST!)

**CRITICAL: Claim the task immediately to prevent race conditions with parallel workers.**

If Linear MCP is available, call `get_issue(id=<task_id>, includeRelations=true)` to validate the task exists and get its details.

If the task doesn't exist, stop and report the error.

If the task is already `In Progress` or `Done`, warn the user:
- If `In Progress`: "This task is already claimed. Another worker may be on it. Proceed anyway?"
- If `Done`: "This task is already closed. Did you mean a different task?"

**Claim it immediately** (if Linear MCP available):

Call `save_issue(id=<task_id>, state="In Progress", assignee="me")`

This must happen BEFORE any other setup (branch creation, context gathering, etc.) to minimize the window where two workers might claim the same task.

## 2. Display Handoff Context (if provided)

If handoff context was provided, display it prominently:

```
==============================================
HANDOFF CONTEXT FROM PREVIOUS SESSION
==============================================
<handoff_context>
==============================================
```

**Note**: This is supplementary guidance from an orchestrating session. Still gather full project context and read the task directly — the handoff supplements but doesn't replace normal setup.

## 3. Rename Conversation

Rename this conversation to the task ID and title for easy reference later:

```
/rename <task_id>: <task title>
```

For example: `/rename frq: Implement backtest engine`

## 4. Gather Project Context

Read these files to understand the project:
- `CLAUDE.md` - Development guidelines
- `PROJECT_SPEC.md` - Project specification (if exists)
- `AGENTS.md` - Agent workflow documentation (if exists)
- `README.md` - Project overview

## 5. Check Recent Work

If Linear MCP is available, call `list_issues(state="In Progress")` and `list_issues(state=Done, limit=10)` to see recent work.

```bash
git log --oneline -10
```

Understand what's been done recently and what state the project is in.

## 6. Check Task Dependencies

If Linear MCP is available, the `get_issue` call from Step 1 already includes relations. Check the `blockedBy` array. If this task has unmet dependencies, warn the user and ask if they want to proceed anyway.

### 6.1 Concurrent Work Awareness

If Linear MCP is available, call `list_issues(state="In Progress")` to see what other tasks are currently being worked on.

If other tasks are in progress, note them for awareness — avoid modifying files that are likely being changed by other workers. If you discover a shared interface concern during implementation, document it in your session summary for the orchestrator.

## 6.5 Research Phase (Conditional)

### High-Risk Indicators (Research First)

Research is recommended when the task involves:
- **Security**: authentication, authorization, encryption, secrets
- **Payments**: billing, subscriptions, transactions, financial data
- **External APIs**: third-party integrations, webhooks, OAuth
- **Data migrations**: schema changes, data transformations
- **New frameworks/libraries**: unfamiliar dependencies

### Research Agents to Consider

1. **framework-docs-researcher**
   - Read: `~/.claude/agents/research/framework-docs-researcher.md`
   - Use when: Task involves libraries or frameworks
   - Checks: Documentation, deprecation warnings, best practices

2. **best-practices-researcher**
   - Read: `~/.claude/agents/research/best-practices-researcher.md`
   - Use when: Architectural decisions needed
   - Provides: Industry best practices, pattern recommendations

### Launch Research (if needed)

```
Use Task tool with subagent_type=general-purpose:

Task: [appropriate-researcher]
- Read agent definition from ~/.claude/agents/research/
- Provide task context and requirements
- Return: Relevant findings, recommendations, warnings
```

### Skip Research If

- Internal refactoring only (no new patterns)
- Strong patterns already documented in CLAUDE.md
- Established team conventions for this type of work
- Simple bug fix with clear scope

### Document Research Findings

If research was conducted and Linear MCP is available, post findings as a comment:
Call `save_comment(issueId=<task_id>, body="Research: <brief summary of findings>")`

---

## 7. Verify Branch Isolation

Ensure you are on a task-specific branch, not `main` or `master`. Workers must isolate their changes on dedicated branches.

```bash
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
  echo "WARNING: On main branch. Creating task branch..."
  git checkout -b <task_id>
fi
echo "Running on branch $(git branch --show-current)"
```

**Sequential/direct mode exception:** If your dispatch prompt includes `EXECUTION_MODE: sequential`, you are running directly on the orchestrator's working branch (e.g., a milestone branch). In this case:
- Do NOT create a task-specific branch — commit directly to the current branch
- The current branch should already be a non-main working branch (dispatch validates this)
- If you find yourself on `main` in sequential mode, STOP and report the error

## 8. Assess Task Size

**Philosophy: Task-sized work** — Tasks should fit comfortably in context.

Now that you can see the codebase, evaluate whether this task is appropriately sized:

**Signs the task is too large:**
- Multiple independent features bundled together
- Requires changes across 10+ files
- Has vague scope like "refactor the entire X system"
- You anticipate needing a handoff mid-task

**If too large**, present options to the user:

```
This task seems large for a single session. Options:

1. **Break it down** — I'll create subtasks and we pick one to start
2. **Proceed anyway** — Work on it knowing we may need a handoff
3. **Scope it down** — Redefine acceptance criteria to a smaller slice

Which approach?
```

**If user chooses "Break it down"** and Linear MCP is available:

Create subtasks under the parent, applying the quality gate — each subtask must have a structured description:

```
save_issue(
  title="<descriptive subtask title>",
  team=<team>,
  parentId=<parent-task-id>,
  priority=<same as parent>,
  labels=<inherit from parent or assign>,
  description="## Problem\n<what this subtask addresses>\n\n## Approach\n<how to implement>\n\n## Acceptance Criteria\n- [ ] ...\n\n## Target Files\n- ..."
)
```

After each creation, run post-write validation: `get_issue(id=<id>)` — check for formatting artifacts and rewrite if needed.

Unclaim the parent: `save_issue(id=<parent-task-id>, state=Todo)`

If subtasks have ordering (part 2 depends on part 1): `save_issue(id=<part-2-id>, blockedBy=[<part-1-id>])`

Then ask: "Which subtask should we work on? I'll switch to that task."

If they pick a subtask, **start over from step 1** with the subtask ID.

**If appropriately sized**, continue to step 9.

## 9. Define Acceptance Criteria

**Philosophy: Bounded autonomy** — Define "done" before coding.

Work with the user to establish clear acceptance criteria. Use `AskUserQuestion` to confirm:

```
Before I start, let me confirm the acceptance criteria:

1. [ ] <functional requirement 1>
2. [ ] <functional requirement 2>
3. [ ] <edge case or constraint>
4. [ ] Tests pass
5. [ ] /finish-task run (creates PR, session summary, closes task)

Is this complete? Anything to add or change?
```

> **Verification discipline** (from `/verify`): Each criterion must be independently verifiable. For every acceptance criterion, you should be able to name the command that proves it. If you can't, the criterion is too vague — rewrite it.

**IMPORTANT**: Items 4 and 5 are ALWAYS required and non-negotiable:
- **Tests pass** — Code must be verified working
- **`/finish-task` run** — The session is not complete without this. It creates the PR, generates a session summary for the orchestrator, and closes the task. Skipping this breaks the coordination workflow.

**Good acceptance criteria are:**
- **Specific** — "User can log in with email/password" not "authentication works"
- **Testable** — Can be verified with a test or clear manual check
- **Bounded** — Clear what's in scope and what's not

If Linear MCP is available, record the agreed criteria as a comment:
Call `save_comment(issueId=<task_id>, body="Acceptance Criteria:\n<criteria list>")`

## 10. Clarify Ambiguities

**CRITICAL**: Before writing any code, use `AskUserQuestion` to resolve any remaining ambiguities:

- Implementation approach if multiple valid options exist
- Edge cases not covered by acceptance criteria
- Integration points with existing code
- Testing strategy

Keep asking until you have a clear picture. Do NOT proceed with assumptions.

Example questions:
- "The task mentions X but doesn't specify Y - which approach do you prefer?"
- "Should this handle edge case Z, or is that out of scope?"
- "I see two ways to implement this: A or B. Do you have a preference?"

## 11. Begin Implementation

Once:
- Task is appropriately sized (or user approved proceeding)
- Acceptance criteria are defined
- Ambiguities are resolved

Ask: "Ready to begin implementation?"

Only start coding after the user confirms.

---

## 12. CRITICAL: Task Completion Contract

**YOUR WORK IS NOT DONE UNTIL YOU RUN `/finish-task <task-id>`**

When implementation is complete (tests pass, code works), you MUST run:

```
/finish-task <task-id>
```

This command handles everything required to properly close out:
- Creates the PR
- Runs automated code review
- Generates session summary for orchestrator
- Closes the task

**DO NOT**:
- Stop the session without running `/finish-task`
- Tell the user "done!" without running `/finish-task`
- Consider the task complete just because tests pass
- Hand off without `/finish-task` (notify the team lead if work is incomplete)

The orchestrator depends on your session summary to coordinate parallel work. A task without a session summary is invisible to coordination.