start-work-on-story

name	start-work-on-story
description	Start development work on a Shortcut story. Creates a branch, analyzes requirements, sets up the environment, and plans implementation.
argument-hint	[story-id]

Start Work on Story Instructions

Story/Ticket ID: $ARGUMENTS

Task: Begin Development Work on Story

Follow this workflow to start working on a new story or ticket efficiently and safely.

1. Branch Creation & Setup

Branch Naming Convention:

Name the ticket after the shortcut ticket being worked on

# For new features
git checkout -b feat/sc-xxxx-brief-description

# For bug fixes
git checkout -b fix/sc-yyyy-brief-description

# For documentation
git checkout -b docs/sc-xxxx-brief-description

# For refactoring/technical work
git checkout -b refactor/sc-xxxx-brief-description

Initial Setup:

# Ensure you're on latest main
git checkout main
git pull origin main

# Create and switch to new branch
git checkout -b [branch-name]

# Verify clean working directory
git status

2. Story Analysis & Planning

Requirements Review:

• Read the full story/ticket description
• Identify all acceptance criteria
• Note any dependencies or prerequisites
• Check for related stories or technical debt
• Understand the user impact and business value

Technical Planning:

• Identify minimum viable changes needed for acceptance criteria
• Map out affected files and components
• Consider integration points (APIs, services, etc.)
• Plan testing strategy (unit, integration, manual)
• Estimate complexity and potential blockers

3. Development Environment

Pre-Development Checks:

# Install/update dependencies
bun install

# Run type checking
bun run build

# Start development server
bun run dev

Project-Specific Setup:

• Verify MCP server configuration
• Check environment variables (.env file)
• Ensure API endpoints are accessible
• Review relevant TypeScript types in src/types/
• If you are calling the Narrative API, are you using the integrated Narrative SDK @narrative.io/data-collaboration-sdk-ts ?

4. Implementation Strategy

Start Small & Iterative:

1. Skeleton First: Create minimal structure/interfaces
2. Core Logic: Implement the essential functionality
3. Error Handling: Add proper error states and validation
4. Polish: Improve UX, performance, and edge cases

Code Quality Standards:

• Follow existing patterns in the codebase
• Use TypeScript strictly (no any types)
• Add proper error handling and logging
• Keep functions focused and testable
• Update types in src/types/index.ts if needed

5. Testing & Validation

Development Testing:

# Run type checking
bun run build

# Manual testing with MCP client
# Test all acceptance criteria scenarios
# Test error states and edge cases

Testing Checklist:

• Happy Path: Primary user flow works as expected
• Edge Cases: Empty states, invalid inputs, network errors
• Integration: Works with existing features
• Performance: No significant slowdowns
• Type Safety: No TypeScript errors

6. Documentation & Communication

Code Documentation:

• Add JSDoc comments for new functions/classes
• Update README if public APIs changed
• Document any new environment variables
• Add inline comments for complex logic

Progress Communication:

• Update story status in ticket system
• Note any blockers or scope changes
• Document testing steps for reviewers

7. Pre-Commit Checklist

Final Validation:

# Clean build
bun run build

# Final manual test of acceptance criteria
# Check for console errors or warnings

Code Review Prep:

• All acceptance criteria met
• No debugging code left behind
• Meaningful commit messages prepared with Shortcut ticket reference
• Consider if changes need documentation updates

MCP-Specific Considerations

Server Development:

• Test tool registration with MCP client
• Verify resource handlers work correctly
• Check error handling for malformed requests
• Validate JSON schemas for new tools

API Integration:

• Handle network failures gracefully
• Implement proper rate limiting if needed
• Add logging for debugging external API calls
• Consider caching strategies for performance

Quick Reference Commands

# Development workflow
bun run dev          # Start development server
bun run build        # Type check and build
bun run start        # Run built server

# Git workflow
git status           # Check current changes
git add .            # Stage changes
git commit -m "..."  # Commit with conventional format + [sc-xxxxx] or "refs sc-xxxxx"
git push origin [branch-name]  # Push for review

Commit Message Examples with Shortcut Integration:

# Using [sc-xxxxx] format
git commit -m "feat: add dataset search functionality [sc-45538]"
git commit -m "fix: resolve API timeout issue [sc-45539]"
git commit -m "docs: update MCP server documentation [sc-45540]"

# Using "refs sc-xxxxx" format
git commit -m "feat: implement user authentication - refs sc-45538"
git commit -m "refactor: optimize search performance - refs sc-45539"

Success Criteria

Before marking the story complete:

• All acceptance criteria demonstrably met
• Code builds without errors or warnings
• Manual testing completed successfully
• Ready for code review and deployment
• Documentation updated as needed

Remember: Start with the minimum viable implementation that meets acceptance criteria. You can always iterate and improve in follow-up stories.