sbarrondocs

Production Workflows

Systematic approaches for production environments to ensure accuracy and prevent mistakes.

Production Error Workflow

CRITICAL: Follow this exact sequence when production errors occur.

Step 1: Check Flare FIRST

~/.claude/check_flare_errors.sh

Purpose: Get complete error context before diving into code Provides:

  • Full stack trace
  • User session data
  • Environment variables
  • Error frequency and patterns

DO NOT skip this step

Step 2: Check Configuration

# Check .env file
ssh server "cat /path/to/project/.env | grep -E 'APP_URL|APP_ENV|DB_|CACHE'"

# Verify loaded config
ssh server "cd /path/to/project && php artisan tinker --execute='echo config(\"app.url\")'"

Common Issues:

  • APP_URL http/https mismatch (#1 cause of production issues)
  • Missing environment variables
  • Wrong database credentials
  • Cache misconfiguration

Step 3: Check Application State

# Database connectivity
ssh server "cd /path/to/project && php artisan tinker --execute='DB::connection()->getPdo()'"

# Cache status
ssh server "cd /path/to/project && php artisan cache:clear"

# Logs
ssh server "tail -100 /path/to/project/storage/logs/laravel.log"

Step 4: Fix and Verify

NEVER claim "ready" or "fixed" without verification

# Make fix
# ...

# Verify via browser (ALWAYS Chrome)
# Take screenshot
# Check Flare for new errors
# Monitor for 5-10 minutes

Laravel Production Workflow

Password Management (Laravel 12+)

CRITICAL: Laravel 12 has 'password' => 'hashed' cast that auto-hashes

// WRONG (double hash):
$user->password = bcrypt('password');
$user->save(); // Cast will hash again!

// CORRECT Option 1:
$user->password = Hash::make('password');
$user->saveQuietly(); // Bypass cast

// CORRECT Option 2:
DB::table('users')->update(['password' => Hash::make('password')]);

// ALWAYS VERIFY:
password_verify('plaintext', $user->password); // Must return true

Deployment Workflow

# 1. Pull latest code
ssh server "cd /path/to/project && git pull"

# 2. Install dependencies
ssh server "cd /path/to/project && composer install --no-dev --optimize-autoloader"

# 3. Run migrations
ssh server "cd /path/to/project && php artisan migrate --force"

# 4. Clear caches
ssh server "cd /path/to/project && php artisan config:clear && php artisan cache:clear && php artisan view:clear"

# 5. Restart services if needed
ssh server "sudo systemctl restart php8.2-fpm"

# 6. Verify deployment
# Open in Chrome, test critical paths, check Flare

No Dev Servers

NEVER use php artisan serve in development

Herd auto-serves all Laravel projects at:

Browser Testing

ALWAYS use Chrome (never Safari) ALWAYS take screenshots for verification ALWAYS check browser console for JS errors

Git Commit Workflow

When to Commit

Only create commits when requested by the user

If unclear, ask first.

Git Safety Protocol

NEVER:

  • Update git config
  • Run destructive commands (force push, hard reset) without explicit request
  • Skip hooks (--no-verify, --no-gpg-sign) without explicit request
  • Force push to main/master (warn user)
  • Amend commits without checking authorship
  • Commit without explicit user request

Commit Creation Steps

  1. Run in parallel:
git status
git diff --staged
git diff
git log --oneline -10
  1. Analyze changes and draft message:
  • Summarize nature (feature, enhancement, bug fix, refactoring)
  • Ensure message reflects changes accurately
  • Focus on "why" not "what"
  • Do not commit secrets (.env, credentials.json, etc.)
  1. Add and commit:
# Add relevant files
git add file1.php file2.js

# Create commit with proper format
git commit -m "$(cat <<'EOF'
Add user authentication system

Implements secure login/logout with session management
and password reset functionality.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

# Verify
git status
  1. Handle pre-commit hook failures:
  • If commit fails due to hook changes, retry ONCE
  • Check authorship: git log -1 --format='%an %ae'
  • Check not pushed: git status shows "Your branch is ahead"
  • If both true: safe to amend
  • Otherwise: create NEW commit

DO NOT Push

Unless user explicitly asks, never push to remote

Pull Request Workflow

When User Requests PR

  1. Understand full context (run in parallel):
git status
git diff --staged
git diff
git log [base-branch]...HEAD
git diff [base-branch]...HEAD
  1. Analyze ALL commits:
  • Look at FULL commit history from branch divergence
  • NOT just latest commit
  • Understand complete changes for PR
  1. Draft PR summary:
  • 1-3 bullet points summarizing changes
  • Test plan checklist
  • Based on ALL commits, not just latest
  1. Create PR (run in parallel if needed):
# Create branch if needed
git checkout -b feature-branch

# Push with -u flag
git push -u origin feature-branch

# Create PR with gh CLI
gh pr create --title "PR title" --body "$(cat <<'EOF'
## Summary
- Bullet point 1
- Bullet point 2

## Test plan
- [ ] Test step 1
- [ ] Test step 2

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
  1. Return PR URL

Time Estimation

Reality Check

Basic Laravel CRUD = 2-4 hours (NOT days) Job board with auth/uploads = 90 minutes (NOT "a week") Simple trivia game = Afternoon project

If simpler than WebSocket trivia game = < 2 hours

Complexity Factors

  • CRUD operations: 2h base
  • Authentication: +0.5h
  • File uploads: +0.5h
  • Relationships: ×1.3 multiplier
  • Real-time features: ×1.5 multiplier
  • Third-party integrations: ×1.2 multiplier

Verification Protocol

Before Claiming Complete

File Operations:

  • Cite path:line references
  • Show actual file content

Tests:

  • Show command output
  • Include pass/fail status

UI Changes:

  • Take screenshots
  • Show in Chrome
  • Check browser console
  • Test user flows

Deployments:

  • Run verification command
  • Check Flare for errors
  • Monitor for 5-10 minutes

Evidence Types

Acceptable:

  • Actual command output
  • Real screenshots
  • Path:line citations
  • Test results

NOT Acceptable:

  • "Should work"
  • "Probably"
  • "Looks good"
  • Untested claims

Status: Critical protocols for production safety Last Updated: 2025-10-17

Was this page helpful?