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

name	description
do-job	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:

# 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

# 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

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

Add comment explaining work start:

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

# 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

# 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

# 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:

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

Run Tests Again

# 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

# 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

# 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

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

Step 9: Create Draft PR

# 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

# 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

# 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.

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

Step 3: Add Investigation Start Comment

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.

@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:

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.

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

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

# 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.