/sdd:story-ship

Definition

Purpose: Deploy a QA-validated story to production by merging to main branch, creating releases, deploying to production environment, performing post-deployment validation, and completing story archival.

Syntax: /sdd:story-ship <story_id> [--skip-tests] [--dry-run]

Parameters

Parameter	Type	Required	Default	Description	Validation
story_id	string	Yes	-	Story identifier (e.g., "STORY-2025-001")	Must match pattern STORY-\d{4}-\d{3}
--skip-tests	flag	No	false	Skip running tests on merged code (not recommended)	Boolean flag
--dry-run	flag	No	false	Simulate deployment without executing	Boolean flag

INSTRUCTION: Ship Story to Production

INPUTS

story_id: Story identifier from /docs/stories/qa/
Story file with QA validation data
Git repository with feature branch
Project context from /docs/project-context/

PROCESS

Phase 1: Pre-Flight Checks

VERIFY story location:
- CHECK story is in /docs/stories/qa/ directory
- IF NOT in qa:
  - CHECK /docs/stories/review/ - suggest running /sdd:story-qa first
  - CHECK /docs/stories/development/ - suggest completing review and QA
  - EXIT with appropriate guidance
VALIDATE story readiness:
- READ story file and verify:
  - ALL Success Criteria marked [x]
  - ALL Implementation Checklist items marked [x]
  - ALL QA Checklist items marked [x] (or marked N/A)
  - QA validation section completed
  - Test results documented
  - Performance benchmarks met
- IF any required items unchecked:
  - DISPLAY incomplete items
  - OFFER to mark as complete if user confirms
  - EXIT if critical items missing
CHECK git status:
- VERIFY on feature branch
- ENSURE all changes committed
- CHECK branch is up to date with remote
- IF uncommitted changes exist:
  - DISPLAY uncommitted files
  - OFFER to commit with auto-generated message
  - EXIT if user declines
RUN pre-merge tests (unless --skip-tests):
- Execute test suite on feature branch
- VERIFY all tests pass
- IF tests fail:
  - DISPLAY failed tests
  - SUGGEST fixing issues before shipping
  - EXIT and keep story in QA

DISPLAY pre-flight summary:

✈️ PRE-FLIGHT CHECK
═══════════════════

Story: [STORY-ID] - [Title]
Branch: [branch-name]
Status: Ready for deployment

✅ Story in QA directory
✅ All checklists complete
✅ All changes committed
✅ Tests passing ([count] tests)
✅ QA validation complete

Ready to ship to production.

Phase 2: Branch Merge

LOAD project context:
- READ /docs/project-context/development-process.md for merge strategy
- IDENTIFY main branch name (main/master)
- CHECK for branch protection rules
SWITCH to main branch:
- RUN: git checkout main (or master)
- PULL latest changes: git pull origin main
- VERIFY clean state
MERGE feature branch:
- ATTEMPT merge: git merge --no-ff [branch-name]
- IF conflicts detected:
  - DISPLAY conflicting files
  - PROVIDE merge conflict resolution guide
  - OFFER interactive conflict resolution
  - VERIFY resolution with user
- IF merge successful:
  - SHOW merge commit details
  - NOTE files changed and lines added/removed
RUN tests on merged code (unless --skip-tests):
- Execute full test suite on main branch
- VERIFY all tests still pass
- IF tests fail after merge:
  - DISPLAY failed tests
  - OFFER to abort merge
  - SUGGEST investigating merge conflicts
  - EXIT if user chooses to abort

DISPLAY merge summary:

🔀 MERGE COMPLETE
═════════════════

Merged: [branch-name] → main
Commit: [commit-hash]
Files changed: [count]
Tests: [count] passing

Phase 3: Release Creation

DETERMINE version strategy:
- CHECK for existing version file (package.json, composer.json, etc.)
- IF versioning used:
  - READ current version
  - SUGGEST next version (semantic versioning)
  - PROMPT user for version number
- IF no versioning:
  - USE story ID as release identifier
  - CREATE date-based version: v[YYYY.MM.DD]
GENERATE changelog entry:
- EXTRACT from story file:
  - Story title and description
  - Success criteria achieved
  - Technical changes made
  - Known issues or limitations
- FORMAT as changelog entry with version
CREATE git tag:
- IF versioning used:
  - CREATE annotated tag: git tag -a v[version] -m "[Story title]"
- IF no versioning:
  - CREATE annotated tag: git tag -a [story-id] -m "[Story title]"
- PUSH tag to remote: git push origin --tags
UPDATE version files (if applicable):
- UPDATE package.json, composer.json, etc.
- COMMIT version bump
- PUSH to remote

DISPLAY release summary:

📦 RELEASE CREATED
══════════════════

Version: [version]
Tag: v[version]
Story: [STORY-ID]
Date: [YYYY-MM-DD]

Changelog entry created
Version files updated

Phase 4: Production Deployment

DETECT deployment configuration:
- CHECK for deployment scripts in project
- COMMON locations:
  - scripts/deploy.sh
  - .github/workflows/deploy.yml
  - composer deploy / npm run deploy
  - deployer.phar
- READ /docs/project-context/technical-stack.md for deployment method
EXECUTE deployment (unless --dry-run):
- IF automated deployment configured:
  - RUN deployment command
  - STREAM output to user
  - TRACK deployment progress
- IF no automation:
  - PROVIDE manual deployment instructions
  - CHECKLIST deployment steps
  - WAIT for user confirmation
MONITOR deployment:
- WATCH for deployment completion
- TRACK any errors or warnings
- LOG deployment output
- IF deployment fails:
  - CAPTURE error details
  - SUGGEST rollback
  - EXIT to Phase 9 (Rollback Handling)

DISPLAY deployment status:

🚀 DEPLOYING TO PRODUCTION
═══════════════════════════

Environment: production
Version: [version]
Method: [deployment-method]

[Real-time deployment output...]

✅ Deployment successful

Phase 5: Post-Deployment Validation

RUN smoke tests:
- LOAD test configuration from project context
- EXECUTE critical path tests:
  - Homepage loads
  - Authentication works
  - Core features functional
  - APIs responding
- IF smoke tests fail:
  - CAPTURE test failures
  - SUGGEST immediate rollback
  - EXIT to Phase 9 (Rollback Handling)
CHECK application health:
- VERIFY application is running
- CHECK health endpoints (if available)
- VALIDATE database connectivity
- CONFIRM cache is functioning
- TEST key integrations
MONITOR initial metrics:
- CHECK error rates (first 5 minutes)
- VERIFY response times
- WATCH for exceptions/crashes
- MONITOR resource usage
- IF metrics anomalous:
  - ALERT user to issues
  - SUGGEST monitoring plan
  - OFFER rollback option
VALIDATE story-specific functionality:
- TEST features from Success Criteria
- VERIFY changes are live
- CHECK user-facing improvements
- VALIDATE data integrity
- TEST critical user paths

DISPLAY validation results:

✅ POST-DEPLOYMENT VALIDATION
═════════════════════════════

Smoke Tests: [X/Y] passed
Health Checks: All systems operational
Metrics: Within normal ranges
Story Features: Validated and live

Application healthy and ready for users.

Phase 6: Story Completion

VERIFY all checklists one final time:
- CHECK all Success Criteria marked [x]
- CHECK all Implementation items marked [x]
- CHECK all QA items marked [x]
- IF any unchecked:
  - MARK as complete with timestamp
  - NOTE completion in progress log
UPDATE story file:
- SET status to "complete"
- ADD completion date: today's date
- ADD deployment information:
  - Deployed version
  - Deployment timestamp
  - Production environment
- ADD progress log entry: "Shipped to production - [timestamp]"
- RECORD final metrics:
  - Total development time
  - Total commits
  - Final test coverage
ENSURE completed directory exists:
- CREATE /docs/stories/completed/ if missing
- ADD .gitkeep if directory created
MOVE story file:
- FROM: /docs/stories/qa/[story-id].md
- TO: /docs/stories/completed/[story-id].md
- VERIFY move successful
COMMIT story completion:
- ADD moved file to git
- COMMIT with message: "chore: ship [story-id] to production"
- PUSH to main branch

Phase 7: Release Notes Generation

COMPILE release notes:
- EXTRACT from story file:
  - What's New (user-facing changes)
  - Technical Changes (developer-facing)
  - Bug Fixes (if applicable)
  - Known Issues or Limitations
  - Upgrade Instructions (if needed)

FORMAT release notes:

📦 RELEASE NOTES
════════════════
Version: [version]
Date: [YYYY-MM-DD]
Story: [STORY-ID] - [Title]

WHAT'S NEW:
- [User-facing feature 1]
- [User-facing feature 2]
- [User-facing improvement 3]

TECHNICAL CHANGES:
- [Implementation detail 1]
- [API change 2]
- [Database migration 3]
- [Configuration change 4]

BUG FIXES:
- [Bug fix 1]
- [Bug fix 2]

KNOWN ISSUES:
- [Limitation 1]
- [Known issue 2]

UPGRADE NOTES:
- [Special instruction 1]
- [Migration step 2]

ROLLBACK PLAN:
See story file for detailed rollback procedure.

PUBLISH release notes:
- ADD to CHANGELOG.md (if exists)
- CREATE GitHub release (if using GitHub)
- UPDATE documentation site (if applicable)
- NOTIFY team/stakeholders (if configured)

Phase 8: Documentation and Cleanup

UPDATE documentation:
- ADD features to README (if user-facing)
- UPDATE API documentation (if API changes)
- REFRESH user guides (if workflows changed)
- UPDATE architecture docs (if structure changed)
CLEAN UP branches:
- DELETE local feature branch: git branch -d [branch-name]
- DELETE remote feature branch: git push origin --delete [branch-name]
- VERIFY branches deleted
- KEEP main branch clean
ARCHIVE temporary files:
- REMOVE build artifacts
- CLEAN up test recordings (unless needed)
- COMPRESS large logs
- REMOVE temporary screenshots
VERIFY repository state:
- CHECK git status is clean
- ENSURE on main branch
- VERIFY all changes pushed
- CONFIRM no uncommitted files
UPDATE project tracking:
- MARK story complete in project board (if applicable)
- UPDATE story count in metrics
- RECORD deployment in tracking system
- NOTIFY relevant stakeholders

Phase 9: Success Summary (or Rollback Handling)

IF deployment successful:

GENERATE success summary:

🚀 SUCCESSFULLY SHIPPED!
════════════════════════
Story: [STORY-ID] - [Title]

DEPLOYMENT:
• Environment: production
• Version: [version]
• Deployed: [timestamp]
• Duration: [development time]

VALIDATION:
• Smoke tests: ✅ Passed
• Health checks: ✅ Operational
• Metrics: ✅ Normal
• Features: ✅ Live

MONITORING:
• Application logs: [link or command]
• Error tracking: [link or command]
• Performance dashboard: [link]

ROLLBACK PLAN:
Available in story file at:
/docs/stories/completed/[story-id].md

NEXT STEPS:
1. Monitor application for 24 hours
2. Watch for user feedback and issues
3. Review metrics and performance
4. Run /sdd:story-complete [story-id] to archive with learnings
5. Celebrate the successful deployment! 🎉

SUGGESTED MONITORING PERIOD:
• First hour: Active monitoring
• First 24 hours: Regular checks
• First week: Periodic validation

IF deployment failed or validation failed:

CAPTURE failure details
DISPLAY error information

SUGGEST rollback:

❌ DEPLOYMENT FAILED
════════════════════
Story: [STORY-ID] - [Title]

FAILURE DETAILS:
• Phase: [deployment/validation]
• Error: [error-message]
• Timestamp: [timestamp]

CURRENT STATE:
• Code: Merged to main
• Deployment: Failed or unstable
• Story: Kept in QA directory

RECOMMENDED ACTION:
/sdd:story-rollback [story-id]

This will:
1. Revert the merge commit
2. Remove the release tag
3. Rollback deployment (if possible)
4. Move story back to appropriate stage

Do you want to rollback now? (y/n)

IF user confirms rollback:
- EXECUTE /sdd:story-rollback command
- EXIT with rollback results
IF user declines:
- KEEP story in QA
- LOG incident in story file
- EXIT with manual resolution guidance

OUTPUTS

/docs/stories/completed/[story-id].md - Completed story with deployment data
Git merge commit on main branch
Git release tag (v[version] or [story-id])
Updated CHANGELOG.md (if exists)
Release notes (displayed and optionally published)
Deleted feature branch (local and remote)
Clean repository state

RULES

MUST verify story is in /docs/stories/qa/ before proceeding
MUST validate all checklists complete (or prompt user)
MUST run tests on merged code (unless --skip-tests)
MUST create release tag for traceability
MUST perform post-deployment validation
MUST move story to /docs/stories/completed/ on success
MUST cleanup feature branches after successful merge
SHOULD generate comprehensive release notes
SHOULD update relevant documentation
NEVER force push to main branch
ALWAYS provide rollback option on failure
MUST commit story move with descriptive message
MUST push all changes to remote repository

Examples

Example 1: Successful Deployment

INPUT:
/sdd:story-ship STORY-2025-001

PROCESS:
→ Pre-flight checks...
→ Story: STORY-2025-001 in /docs/stories/qa/
→ Validating checklists... ✅
→ Checking git status... ✅
→ Running tests... ✅ (156 tests passed)

→ Switching to main branch...
→ Merging feature/auth-001-login-form...
→ Merge successful - 12 files changed
→ Running tests on merged code... ✅

→ Creating release...
→ Version: v1.1.0
→ Tag created: v1.1.0
→ Changelog updated

→ Deploying to production...
→ Running: composer deploy
→ [deployment output...]
→ Deployment successful ✅

→ Post-deployment validation...
→ Smoke tests: 8/8 passed ✅
→ Health checks: All operational ✅
→ Metrics: Normal ✅

→ Completing story...
→ Moving to /docs/stories/completed/STORY-2025-001.md
→ Cleaning up feature branch...
→ Generating release notes...

OUTPUT:
🚀 SUCCESSFULLY SHIPPED!
════════════════════════
Story: STORY-2025-001 - User Authentication System

DEPLOYMENT:
• Environment: production
• Version: v1.1.0
• Deployed: 2025-03-15 14:32:18 UTC
• Duration: 9 working days

VALIDATION:
• Smoke tests: ✅ Passed (8/8)
• Health checks: ✅ Operational
• Metrics: ✅ Normal
• Features: ✅ Live

MONITORING:
• Application logs: php artisan pail
• Error tracking: Check Sentry dashboard
• Performance: Watch response times

ROLLBACK PLAN:
Available in story file at:
/docs/stories/completed/STORY-2025-001.md

NEXT STEPS:
1. Monitor application for 24 hours
2. Watch for user feedback and issues
3. Review metrics and performance
4. Run /sdd:story-complete STORY-2025-001 to archive
5. Celebrate the successful deployment! 🎉

📦 RELEASE NOTES
════════════════
Version: v1.1.0
Date: 2025-03-15
Story: STORY-2025-001 - User Authentication System

WHAT'S NEW:
- User registration with email verification
- Secure login with session management
- Password reset functionality
- Remember me option for convenience

TECHNICAL CHANGES:
- Added AuthMiddleware for route protection
- Implemented JWT token handling
- Created authentication test suite
- Added password hashing with bcrypt

ROLLBACK PLAN:
See /docs/stories/completed/STORY-2025-001.md

Example 2: Deployment with Manual Steps

INPUT:
/sdd:story-ship STORY-2025-002

PROCESS:
→ Pre-flight checks... ✅
→ Merging to main... ✅
→ Creating release v1.2.0... ✅

→ Detecting deployment configuration...
→ No automated deployment found

OUTPUT:
📋 MANUAL DEPLOYMENT REQUIRED
══════════════════════════════

Story: STORY-2025-002 - Profile Management
Version: v1.2.0

Please complete the following deployment steps:

1. [ ] SSH into production server
2. [ ] Pull latest changes: git pull origin main
3. [ ] Install dependencies: composer install --no-dev
4. [ ] Run migrations: php artisan migrate --force
5. [ ] Clear caches: php artisan cache:clear
6. [ ] Restart services: sudo systemctl restart php-fpm
7. [ ] Verify application is running

Have you completed all deployment steps? (y/n)
> y

→ Running post-deployment validation...
→ Smoke tests: 10/10 passed ✅
→ Completing story...

[Success summary displayed]

Example 3: Deployment Failure with Rollback

INPUT:
/sdd:story-ship STORY-2025-003

PROCESS:
→ Pre-flight checks... ✅
→ Merging to main... ✅
→ Creating release v1.3.0... ✅
→ Deploying to production...
→ Error: Database migration failed

OUTPUT:
❌ DEPLOYMENT FAILED
════════════════════
Story: STORY-2025-003 - Payment Integration

FAILURE DETAILS:
• Phase: deployment
• Error: Database migration "add_payment_columns" failed
• Timestamp: 2025-03-16 10:15:42 UTC
• Exit code: 1

ERROR MESSAGE:
SQLSTATE[42S21]: Column already exists: 1060 Duplicate column name 'payment_status'

CURRENT STATE:
• Code: Merged to main (commit abc123)
• Deployment: Failed during migrations
• Story: Kept in QA directory

RECOMMENDED ACTION:
/sdd:story-rollback STORY-2025-003

This will:
1. Revert the merge commit
2. Remove the release tag v1.3.0
3. Rollback deployment (revert to v1.2.0)
4. Move story back to QA for fixes

Do you want to rollback now? (y/n)
> y

→ Executing rollback...
[Rollback process initiated]

Example 4: Dry Run

INPUT:
/sdd:story-ship STORY-2025-004 --dry-run

PROCESS:
→ DRY RUN MODE - No changes will be made
→ Pre-flight checks... ✅
→ Would merge feature/notifications to main
→ Would create release v1.4.0
→ Would deploy to production
→ Would run post-deployment validation
→ Would move story to completed

OUTPUT:
🔍 DRY RUN COMPLETE
═══════════════════

Story: STORY-2025-004 - Push Notifications

SIMULATED ACTIONS:
✓ Merge feature/notifications → main
✓ Create release tag v1.4.0
✓ Deploy to production
✓ Run smoke tests
✓ Move to /docs/stories/completed/
✓ Delete feature branch

ESTIMATED DURATION: ~5 minutes

No actual changes were made.
Run without --dry-run to execute deployment.

Edge Cases

Incomplete Checklists

DETECT unchecked Success Criteria or Implementation items
DISPLAY incomplete items with context
OFFER to mark as complete if user confirms
WARN about shipping with incomplete items
EXIT if critical items missing (user decides what's critical)

Merge Conflicts

DETECT conflicts during merge
DISPLAY conflicting files and conflict markers
PROVIDE merge conflict resolution guide
OFFER interactive conflict resolution
VERIFY resolution with user before continuing
RE-RUN tests after conflict resolution

Failed Tests After Merge

CAPTURE test failures on merged code
DISPLAY failed test details
SUGGEST investigating merge-related issues
OFFER to abort merge and reset
KEEP story in QA if merge aborted
LOG incident in story progress log

Deployment Timeout

MONITOR deployment progress
DETECT if deployment hangs or times out
PROVIDE option to continue waiting or abort
LOG timeout incident
SUGGEST checking deployment logs manually
OFFER rollback option

Failed Smoke Tests

CAPTURE smoke test failures
DISPLAY which tests failed and why
ASSESS severity of failures
OFFER immediate rollback for critical failures
ALLOW user to investigate for non-critical failures
LOG post-deployment issues in story file

No Version Management

DETECT absence of version files
USE story ID as release identifier
CREATE date-based version as alternative
SUGGEST implementing semantic versioning
CONTINUE with story-based releases

Error Handling

Story ID missing: Return "Error: Story ID required. Usage: /sdd:story-ship <story_id>"
Invalid story ID format: Return "Error: Invalid story ID format. Expected: STORY-YYYY-NNN"
Story not in QA: Report current location and suggest appropriate next step
Uncommitted changes: Display files and offer to commit or exit
Test failures: Display failures, offer to fix or abort
Merge conflicts: Provide resolution guide and interactive help
Deployment failure: Capture details, suggest rollback, log incident
Validation failure: Assess severity, offer rollback for critical issues
Git errors: Display error, suggest manual resolution, provide recovery steps

Performance Considerations

Run tests in parallel when possible
Stream deployment output in real-time
Cache git operations during session
Perform post-deployment validation concurrently
Generate release notes asynchronously
Cleanup branches in background after success

Related Commands

/sdd:story-qa - Move story to QA before shipping
/sdd:story-rollback - Rollback failed deployment
/sdd:story-complete - Archive story after successful deployment
/sdd:story-validate - Run final validation before shipping
/sdd:project-status - View all project stories

Constraints

✅ MUST verify story in QA directory
✅ MUST validate checklists complete
✅ MUST run tests on merged code
🔀 MUST merge to main branch (no fast-forward)
🏷️ MUST create release tag
🚀 MUST deploy to production environment
✔️ MUST perform post-deployment validation
📝 MUST generate release notes
🧹 MUST cleanup feature branches
💾 MUST move story to completed on success
🚫 NEVER force push to main
↩️ ALWAYS provide rollback option on failure
📊 MUST update story with deployment data

/story-ship