start-ticket

Start Ticket

Kicks off a new piece of work — from raw goal to failing tests that define "done." Use this when you want to set up and plan but implement manually. For full automation, use /dev instead.

Commit Discipline

Commit early and often. Push after every commit. Don't accumulate local commits.

Input

The user provides one of:

• A goal string: /start-ticket implement rate limiting for the admin API
• A Trello card: /start-ticket https://trello.com/c/abc123

If no argument, ask: "What are you working on? (paste a goal or Trello card URL)"

Phase 1: Environment

1. Verify Worktree

Run pwd. Must contain .claude/worktrees/.

If not: STOP. Say: "Not in a worktree. Run claude --worktree first, then /start-ticket again."

2. Set Up .env

If .env doesn't exist:

• Try cp ../../.env .env (from main project dir)
• Fallback: cp .env.example .env
• Warn about API keys if copied from example

3. Resolve the Goal

Trello card (URL contains trello.com/c/ or input starts with trello:):

• Parse card ID, fetch with ~/bin/trello card <ID>
• Extract title + description as the goal
• Move to In Progress: ~/bin/trello move <ID> <IN_PROGRESS_LIST_ID> (look up list ID via ~/bin/trello lists <BOARD_ID> if needed)
• Note the card ID in OBJECTIVE.md for /finish-ticket

Plain text: use as-is.

Phase 2: Understand and Plan

4. Research the Problem

Before planning, understand the relevant code:

• Read the project's ARCHITECTURE.md if it exists
• Search the codebase for modules/files related to the goal
• Read existing tests in the area to understand conventions and coverage
• Check dev/context/ files for relevant learnings, decisions, gotchas

5. Write dev/OBJECTIVE.md

# Objective

<One-sentence goal>

## Description

<2-3 sentences of context, informed by codebase research>

## Approach

<Bulleted plan — which files to modify, what the change looks like>

## Acceptance Criteria

- [ ] Failing unit tests written and verified failing
- [ ] Implementation makes all tests pass
- [ ] dev_checks passes
- [ ] <domain-specific criteria from the goal>

## Tracking

- Trello: <card URL or "none">
- Branch: <branch name>
- PR: <filled after creation>

6. Confirm Plan with User

Present the approach and ask: "Does this plan look right?"

Wait for confirmation before proceeding.

Phase 3: Draft PR (early)

7. Create Draft PR

Get the draft PR up before writing any tests or code:

git add dev/OBJECTIVE.md
git commit -m "chore: set objective to <short-handle>"
git push -u origin $(git rev-parse --abbrev-ref HEAD)
gh pr create --draft --title "<type>: <title>" --body "$(cat <<'EOF'
## Objective

<objective statement>

## Approach

<approach from OBJECTIVE.md>

## Acceptance Criteria

<criteria>
EOF
)"

Update dev/OBJECTIVE.md Tracking section with the PR URL. If Trello card is linked, comment the PR URL on the card.

Phase 4: Test-First

8. Write Failing Tests

Write unit tests that define the expected behavior:

• Follow the project's test conventions
• Cover the happy path, edge cases, and error conditions
• Place tests in the appropriate directory mirroring the source structure

9. Verify Tests Fail Correctly

Run the new tests: uv run pytest <test_file> -v

Confirm they fail because the feature doesn't exist, not due to infrastructure issues.

10. Commit and Push Tests

git add <test_files>
git commit -m "test: add failing tests for <feature>"
git push

11. Report

Ready to implement:
  Worktree:      <path>
  Branch:        <branch>
  PR (draft):    <URL>
  Trello:        <card URL — moved to In Progress / not linked>
  Failing tests: <N tests in M files>

The tests define what "done" looks like. Implement until they pass.