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.