nixos/shared/linked-dotfiles/opencode/skills/do-job/SKILL.md

---
name: do-job
description: Use when starting work on Jira tickets - fetches To Do tickets, creates git worktrees with proper PI-XXXXX naming, implements features using TDD (test-first), commits with ticket references, creates draft PRs, validates work with PR review, and transitions tickets through workflow to Testing
---

# Do Job

Complete developer workflow from ticket selection to validated draft PR using TDD and git worktrees.

## When to Use This Skill

Use when:
- Starting work on a new Jira ticket
- Implementing features using test-driven development
- Creating PRs for Jira-tracked work

## Workflow Selection

**CRITICAL: Choose workflow based on ticket type**

- **Regular tickets (Story, Task, Bug)**: Use Standard Implementation Workflow below
- **SPIKE tickets (Investigation/Research)**: Use SPIKE Investigation Workflow

To determine ticket type, check the `issueTypeName` field when fetching the ticket.

## Standard Implementation Workflow

Copy and track progress:

```
Ticket Workflow Progress:
- [ ] Step 1: Fetch and select To Do ticket
- [ ] Step 2: Move ticket to In Progress
- [ ] Step 3: Set up git worktree
- [ ] Step 4: Write failing tests (TDD)
- [ ] Step 5: Implement feature/fix
- [ ] Step 6: Verify tests pass
- [ ] Step 7: Review work with developer
- [ ] Step 8: Commit with PI-XXXXX reference
- [ ] Step 9: Push branch
- [ ] Step 10: Create draft PR
- [ ] Step 11: Review work with PR reviewer
- [ ] Step 12: Link PR to ticket
- [ ] Step 13: Session reflection
```

## SPIKE Investigation Workflow

**Use this workflow when ticket type is SPIKE**

SPIKE tickets are for investigation and research only. No code changes, no PRs.

```
SPIKE Workflow Progress:
- [ ] Step 1: Fetch and select SPIKE ticket
- [ ] Step 2: Move ticket to In Progress
- [ ] Step 3: Add investigation start comment
- [ ] Step 4: Invoke investigate agent for research
- [ ] Step 5: Review findings with developer
- [ ] Step 6: Document findings in ticket
- [ ] Step 7: Create follow-up tickets (with approval)
- [ ] Step 8: Link follow-up tickets to SPIKE
- [ ] Step 9: Move SPIKE to Done
- [ ] Step 10: Session reflection
```

**Jump to SPIKE Workflow Steps section below for SPIKE-specific instructions.**

## Prerequisites

Verify environment:

```bash
# Check Jira access
atlassian-mcp-server_getAccessibleAtlassianResources

# Check GitHub CLI
gh auth status

# Verify in repos root directory
ls -d */
```

## Step 1: Fetch and Select Ticket

```bash
# Get To Do tickets
atlassian-mcp-server_searchJiraIssuesUsingJql \
  cloudId="<cloud-id>" \
  jql="assignee = currentUser() AND status = 'To Do' ORDER BY priority DESC, updated DESC" \
  fields='["summary", "description", "status", "priority"]'
```

Review tickets and select one based on priority and description.

## Step 2: Move Ticket to In Progress

```bash
atlassian-mcp-server_transitionJiraIssue \
  cloudId="<cloud-id>" \
  issueIdOrKey="PI-XXXXX" \
  transition='{"id": "41"}'  # In Progress transition ID
```

Add comment explaining work start:

```bash
atlassian-mcp-server_addCommentToJiraIssue \
  cloudId="<cloud-id>" \
  issueIdOrKey="PI-XXXXX" \
  commentBody="Starting work on this ticket using TDD approach"
```

## Step 3: Set Up Git Worktree

**CRITICAL: All branches and commits MUST include PI-XXXXX ticket number**

### Identify Repository

From repos root directory, determine which repo based on ticket description and summary.

### Create Worktree

```bash
# Navigate to develop branch of target repo
cd <repo-name>/develop

# Pull latest changes
git pull

# Create worktree with proper naming
# Pattern: ../<descriptive-name> with branch nate/PI-XXXXX_descriptive-name
git worktree add ../<descriptive-name> -b nate/PI-XXXXX_descriptive-name

# Navigate to new worktree
cd ../<descriptive-name>
```

**Naming conventions:**
- Directory: Short descriptive name (e.g., `rename-folder-fix`)
- Branch: `nate/PI-XXXXX_descriptive-name` (e.g., `nate/PI-70535_rename-folder-fix`)
- **MUST include PI-XXXXX** in branch name

## Step 4: Build Implementation Plan

Analyze ticket requirements and create TDD plan:

1. **Understand requirements** from ticket description
2. **Identify affected code** areas
3. **Plan test cases** covering:
   - Happy path
   - Edge cases
   - Error conditions
4. **Plan implementation** approach

## Step 5: TDD Implementation

### Write Failing Tests First

**CRITICAL: Write tests BEFORE implementation**

```bash
# Identify test framework from repo
ls *_test.* test/ tests/ __tests__/

# Create or modify test file
# Write test that validates missing functionality
```

Test should:
- Clearly describe expected behavior
- Cover the specific bug/feature from ticket
- **Fail initially** (validates test is working)

### Run Failing Tests

```bash
# Verify test fails (proves test is valid)
<run-test-command>
```

Expected: Test fails with clear error showing missing functionality.

### Implement Feature/Fix

Write minimal code to make test pass:

```bash
# Implement the feature or fix
# Focus on making test pass, not perfection
```

### Run Tests Again

```bash
# Verify test now passes
<run-test-command>
```

Expected: All tests pass.

### Refactor (if needed)

Clean up implementation while keeping tests passing:

- Improve code clarity
- Remove duplication
- Follow project conventions
- **Keep tests passing**

## Step 6: Verify Complete Solution

```bash
# Run full test suite
<full-test-command>

# Run linting (if available)
<lint-command>

# Run type checking (if available)
<typecheck-command>
```

All checks must pass before proceeding.

## Step 7: Commit Changes

**CRITICAL: Commit message MUST include PI-XXXXX**

```bash
# Stage changes
git add .

# Commit with ticket reference
git commit -m "PI-XXXXX: <concise description>

<detailed explanation of changes>
- What was changed
- Why it was changed
- How it addresses the ticket"
```

**Commit message format:**
- First line: `PI-XXXXX: <summary>` (50 chars max)
- Blank line
- Detailed description explaining the why and how
- Reference ticket number (PI-XXXXX) in first line

## Step 8: Push Branch

```bash
# Push to remote
git push -u origin nate/PI-XXXXX_descriptive-name
```

## Step 9: Create Draft PR

```bash
# Create draft PR with gh CLI
gh pr create \
  --draft \
  --title "PI-XXXXX: <descriptive title>" \
  --body "$(cat <<'PRBODY'
## Summary
- Fixes issue described in PI-XXXXX
- Implements <feature/fix> using TDD approach

## Changes
- Added tests for <functionality>
- Implemented <feature/fix>
- Verified all tests pass

## Testing
- [x] Unit tests added and passing
- [x] Linting passes
- [x] Manual testing completed

## Jira
Related ticket: PI-XXXXX

## Notes
Ready for review. Once approved, will move ticket to Pull Request status.
PRBODY
)"
```

**Save PR URL** returned by command for next steps.

## Step 10: Review Work with PR Reviewer

**CRITICAL: Invoke @pr-reviewer subagent to validate work before linking to ticket**

```bash
# Invoke the pr-reviewer subagent
@pr-reviewer please review the PR I just created
```

The pr-reviewer will:
- Verify the repository is compatible (Go with Makefile)
- Run all validation commands (tests, linting, type checking)
- Review code quality against project standards
- Check for security issues and best practices
- Provide verdict: Ready for review OR needs work

**If pr-reviewer finds issues:**
1. Address the critical issues identified
2. Re-run tests and validations
3. Commit fixes with `PI-XXXXX: Address PR review feedback`
4. Push updates
5. Invoke @pr-reviewer again to re-validate

**Only proceed to Step 11 when pr-reviewer gives approval.**

## Step 11: Link PR to Ticket

```bash
# Add PR link to Jira ticket
atlassian-mcp-server_addCommentToJiraIssue \
  cloudId="<cloud-id>" \
  issueIdOrKey="PI-XXXXX" \
  commentBody="Draft PR created: <pr-url>

Implementation complete using TDD approach. Ready for code review."
```

## Step 12: Session Reflection and Optimization

**CRITICAL: After completing the ticket workflow, reflect and optimize the system**

### Two-Stage Process

**Stage 1: Analysis** - Use `learn_skill(reflect)` for session analysis
- Reviews conversation history and workflow
- Identifies preventable friction (auth issues, environment setup, missing docs)
- Distinguishes from expected development work (debugging, testing)
- Provides structured findings with 1-3 high-impact improvements

**Stage 2: Implementation** - Invoke `@optimize` agent to take action
- Takes reflection findings and implements changes automatically
- Updates CLAUDE.md/AGENTS.md with missing commands/docs
- Creates or updates skills based on patterns identified
- Adds shell alias recommendations for repeated commands
- Commits all changes with clear messages

**Only proceed with reflection after:**
- PR is created and validated
- PR review subagent gives go ahead

**No Improvements is OK**

Do not reach for fixing things that are already solved. If there are systemic problems, then address them, otherwise, continue on.

**Example workflow**:
```
1. learn_skill(reflect) → produces analysis
2. Review findings
3. @optimize → implements improvements automatically
4. System is now better for next session
```

---

## SPIKE Workflow Steps

**These steps apply only to SPIKE tickets (investigation/research)**

### Step 1: Fetch and Select SPIKE Ticket

Same as standard workflow Step 1 - fetch To Do tickets and select one.

Verify it's a SPIKE by checking `issueTypeName` field.

### Step 2: Move Ticket to In Progress

Same as standard workflow Step 2.

```bash
atlassian-mcp-server_transitionJiraIssue \
  cloudId="<cloud-id>" \
  issueIdOrKey="PI-XXXXX" \
  transition='{"id": "41"}'
```

### Step 3: Add Investigation Start Comment

```bash
atlassian-mcp-server_addCommentToJiraIssue \
  cloudId="<cloud-id>" \
  issueIdOrKey="PI-XXXXX" \
  commentBody="Starting SPIKE investigation - will explore multiple solution approaches and document findings"
```

### Step 4: Invoke Investigate Agent

**CRITICAL: Use @investigate subagent for creative exploration**

The investigate agent has higher temperature (0.8) for creative thinking.

```bash
@investigate

Context: SPIKE ticket PI-XXXXX
Summary: <ticket summary>
Description: <ticket description>

Please investigate this problem and:
1. Explore the current codebase to understand the problem space
2. Research 3-5 different solution approaches
3. Evaluate trade-offs for each approach
4. Document findings with specific code references (file:line)
5. Recommend the best approach with justification
6. Break down into actionable implementation task(s) - typically just 1 ticket
```

The investigate agent will:
- Explore codebase thoroughly
- Research multiple solution paths (3-5 approaches)
- Consider creative/unconventional approaches
- Evaluate trade-offs objectively
- Document specific code references
- Recommend best approach with justification
- Propose implementation plan (typically 1 follow-up ticket)

### Step 5: Document Findings

Create comprehensive investigation summary in Jira ticket:

```bash
atlassian-mcp-server_addCommentToJiraIssue \
  cloudId="<cloud-id>" \
  issueIdOrKey="PI-XXXXX" \
  commentBody="## Investigation Findings

### Problem Analysis
<summary of problem space with code references>

### Approaches Considered

1. **Approach A**: <description>
   - Pros: <benefits>
   - Cons: <drawbacks>
   - Effort: <S/M/L/XL>
   - Code: <file:line references>

2. **Approach B**: <description>
   - Pros: <benefits>
   - Cons: <drawbacks>
   - Effort: <S/M/L/XL>
   - Code: <file:line references>

3. **Approach C**: <description>
   - Pros: <benefits>
   - Cons: <drawbacks>
   - Effort: <S/M/L/XL>
   - Code: <file:line references>

[Continue for all 3-5 approaches]

### Recommendation
**Recommended Approach**: <approach name>

**Justification**: <why this is best>

**Risks**: <potential issues and mitigations>

**Confidence**: <Low/Medium/High>

### Proposed Implementation

Typically breaking this down into **1 follow-up ticket**:

**Summary**: <concise task description>

**Description**: <detailed implementation plan>

**Acceptance Criteria**:
- [ ] <criterion 1>
- [ ] <criterion 2>
- [ ] <criterion 3>

**Effort Estimate**: <S/M/L/XL>

### References
- <file:line references>
- <documentation links>
- <related tickets>
- <external resources>"
```

### Step 6: Review Findings with Developer

**CRITICAL: Get developer approval before creating tickets**

Present investigation findings and proposed follow-up ticket(s) to developer:

```
Investigation complete for PI-XXXXX.

Summary:
- Explored <N> solution approaches
- Recommend: <approach name>
- Propose: <N> follow-up ticket(s) (typically 1)

Proposed ticket:
- Summary: <task summary>
- Effort: <estimate>

Would you like me to create this ticket, or would you like to adjust the plan?
```

**Wait for developer confirmation before proceeding.**

Developer may:
- Approve ticket creation as-is
- Request modifications to task breakdown
- Request different approach be pursued
- Decide no follow-up tickets needed
- Decide to handle implementation differently

### Step 7: Create Follow-Up Tickets (With Approval)

**Only proceed after developer approves in Step 6**

Typically create just **1 follow-up ticket**. Occasionally more if investigation reveals multiple independent tasks.

```bash
atlassian-mcp-server_createJiraIssue \
  cloudId="<cloud-id>" \
  projectKey="<project>" \
  issueTypeName="Story" \
  summary="<concise task description from investigation>" \
  description="## Context
From SPIKE PI-XXXXX investigation

## Problem
<problem statement>

## Recommended Approach
<approach name and description from SPIKE>

## Implementation Plan
<detailed steps>

## Acceptance Criteria
- [ ] <criterion 1>
- [ ] <criterion 2>
- [ ] <criterion 3>

## Code References
- <file:line from investigation>
- <file:line from investigation>

## Related Tickets
- SPIKE: PI-XXXXX

## Effort Estimate
<S/M/L/XL from investigation>

## Additional Notes
<any important considerations from SPIKE>"
```

**Note the returned ticket number (e.g., PI-XXXXX) for linking in Step 8.**

If creating multiple tickets (rare), repeat for each task.

### Step 8: Link Follow-Up Tickets to SPIKE

```bash
atlassian-mcp-server_addCommentToJiraIssue \
  cloudId="<cloud-id>" \
  issueIdOrKey="PI-XXXXX" \
  commentBody="## Follow-Up Ticket(s) Created

Implementation task created:
- PI-XXXXX: <task summary>

This ticket is ready for implementation using the recommended <approach name> approach."
```

If multiple tickets created, list all with their ticket numbers.

### Step 9: Move SPIKE to Done

```bash
# Get available transitions
atlassian-mcp-server_getTransitionsForJiraIssue \
  cloudId="<cloud-id>" \
  issueIdOrKey="PI-XXXXX"

# Transition to Done (find correct transition ID from above)
atlassian-mcp-server_transitionJiraIssue \
  cloudId="<cloud-id>" \
  issueIdOrKey="PI-XXXXX" \
  transition='{"id": "<done-transition-id>"}'
```

### Step 10: Session Reflection

Same as standard workflow - use `learn_skill` tool with `skill_name='reflect'` to identify preventable friction.

---

## Post-Workflow Steps (Manual)

**After automated pr-reviewer approval and manual developer review:**

1. Remove draft status from PR
2. Request code review from team
3. Address any additional review comments
4. Get approval
5. **Manual:** Transition ticket to "Pull Request" status (transition ID: 381)
6. **Manual:** After merge, SDET moves to "Testing (Service Stack)" (transition ID: 201)

## Common Mistakes

### Standard Workflow Mistakes

#### Branch Naming
- ❌ `fix-bug` (missing ticket number)
- ❌ `PI70535-fix` (missing hyphen, no username)
- ✅ `nate/PI-70535_rename-folder-fix`

#### Commit Messages
- ❌ `fixed bug` (no ticket reference)
- ❌ `Updated code for PI-70535` (vague)
- ✅ `PI-70535: Fix shared folder rename permission check`

#### TDD Order
- ❌ Write code first, then tests
- ❌ Skip tests entirely
- ✅ Write failing test → Implement → Verify passing → Refactor

#### Worktree Location
- ❌ `git worktree add ./feature` (wrong location)
- ❌ `git worktree add ~/feature` (absolute path)
- ✅ `git worktree add ../feature-name` (parallel to develop)

### SPIKE Workflow Mistakes

#### Investigation Depth
- ❌ Only exploring 1 obvious solution
- ❌ Vague code references like "the auth module"
- ✅ Explore 3-5 distinct approaches with specific file:line references

#### Ticket Creation
- ❌ Creating tickets without developer approval
- ❌ Creating many vague tickets automatically
- ✅ Propose plan, get approval, then create (typically 1 ticket)

#### Code Changes
- ❌ Implementing solution during SPIKE
- ❌ Creating git worktree for SPIKE
- ✅ SPIKE is investigation only - no code, no worktree, no PR

## Jira Transition IDs

Reference for manual transitions:

- To Do: 11
- In Progress: 41
- Pull Request: 381
- Testing (Service Stack): 201
- Done: (varies by project)

## Reference Materials

See references/tdd-workflow.md for detailed TDD best practices.
See references/git-worktree.md for git worktree patterns and troubleshooting.
See references/spike-workflow.md for SPIKE investigation patterns and examples.