Basic Workflow Skill
Production-Grade Learning Skill | Version 2.0.0
Master the daily rhythm of Git operations.
Skill Contract
Input Schema
input:
type: object
properties:
workflow_type:
type: string
enum: [solo, feature-branch, quick-fix, team]
default: solo
current_state:
type: object
properties:
has_remote:
type: boolean
has_uncommitted:
type: boolean
current_branch:
type: string
include_push:
type: boolean
default: true
validation:
auto_detect_state: true
Output Schema
output:
type: object
required: [workflow_steps, success]
properties:
workflow_steps:
type: array
items:
type: object
properties:
step: integer
command: string
description: string
safe: boolean
success:
type: boolean
warnings:
type: array
items:
type: string
diagram:
type: string
Error Handling
Retry Logic
retry_config:
max_attempts: 3
backoff_type: exponential
initial_delay_ms: 1000
max_delay_ms: 8000
retryable:
- network_timeout
- remote_connection_failed
Fallback Strategy
fallback:
- trigger: push_rejected
action: suggest_pull_first
- trigger: merge_conflict
action: guide_conflict_resolution
- trigger: authentication_failed
action: check_credentials
The Daily Cycle
┌──────────────────────────────────────────────────────────────┐
│ DAILY GIT WORKFLOW │
├──────────────────────────────────────────────────────────────┤
│ │
│ Morning: git pull ← Get latest from team │
│ │ │
│ ▼ │
│ Work: (make changes) ← Do your development │
│ │ │
│ ▼ │
│ Check: git status ← See what changed │
│ │ │
│ ▼ │
│ Stage: git add ← Prepare for saving │
│ │ │
│ ▼ │
│ Save: git commit ← Save your work │
│ │ │
│ ▼ │
│ Share: git push ← Share with team │
│ │
└──────────────────────────────────────────────────────────────┘
Essential Commands
1. Start Your Day: git pull
# Get the latest changes from remote
git pull origin main
# What it does:
# 1. Fetches changes from remote
# 2. Merges them into your branch
2. Check Status: git status
git status
# Output explains:
# - Modified files (red = not staged)
# - Staged files (green = ready to commit)
# - Untracked files (new files)
3. View Changes: git diff
# See unstaged changes
git diff
# See staged changes
git diff --staged
# See changes for specific file
git diff README.md
4. Stage Changes: git add
# Add specific file
git add README.md
# Add multiple files
git add file1.js file2.js
# Add all files in directory
git add src/
# Add all changes (use carefully!)
git add .
# Interactive staging
git add -p # Review each change
5. Commit Changes: git commit
# Commit with inline message
git commit -m "Add user authentication"
# Commit with detailed message (opens editor)
git commit
# Add and commit in one step (tracked files only)
git commit -am "Quick fix for typo"
6. Share Your Work: git push
# Push to remote
git push origin main
# First push of a new branch
git push -u origin feature-branch
Workflow Patterns
Pattern 1: Solo Work
# Start of day
git pull
# Throughout day
git status
git add .
git commit -m "Feature: Add login form"
git push
Pattern 2: Feature Development
# Create feature branch
git checkout -b feature/user-settings
# Work and commit multiple times
git add src/settings.js
git commit -m "Add settings page structure"
git add src/settings.css
git commit -m "Style settings page"
# Push branch
git push -u origin feature/user-settings
Pattern 3: Quick Fix
git checkout main
git pull
git add fix.js
git commit -m "Fix: Button alignment on mobile"
git push
The Perfect Commit
What Makes a Good Commit?
| Attribute | Description | Example | |-----------|-------------|---------| | Atomic | One logical change | "Add login button" | | Complete | Tests pass, code works | All tests green | | Descriptive | Clear message | "Fix: Navbar overlap on mobile" | | Small | Easier to review/revert | < 200 lines ideal |
Commit Message Format
type: subject line (50 chars max)
body: detailed explanation (optional)
- what you did
- why you did it
- any side effects
Closes #123 (optional: reference issues)
Types
feat:New featurefix:Bug fixdocs:Documentation onlystyle:Formatting (no code change)refactor:Code restructuretest:Adding testschore:Maintenance
Common Scenarios
Scenario 1: "Oops, wrong file!"
# Remove from staging (keep file)
git restore --staged accidental-file.txt
# Or the older syntax
git reset HEAD accidental-file.txt
Scenario 2: "I want to undo my changes"
# Undo changes in working directory (DESTRUCTIVE!)
git restore file.txt
# Or restore all files
git restore .
Scenario 3: "I forgot to add a file to last commit"
git add forgotten-file.txt
git commit --amend --no-edit
# Note: Only do this BEFORE pushing!
Scenario 4: "I need to see what I did yesterday"
git log --oneline --since="yesterday"
git log --oneline -10 # Last 10 commits
git log --oneline --author="Your Name"
Quick Reference Card
┌─────────────────────────────────────────────────────────┐
│ DAILY WORKFLOW CHEATSHEET │
├─────────────────────────────────────────────────────────┤
│ │
│ START DAY git pull │
│ │
│ CHECK WORK git status │
│ git diff │
│ │
│ SAVE WORK git add <files> │
│ git commit -m "message" │
│ │
│ SHARE WORK git push │
│ │
│ VIEW HISTORY git log --oneline │
│ │
│ UNDO STAGING git restore --staged <file> │
│ │
│ UNDO CHANGES git restore <file> │
│ │
└─────────────────────────────────────────────────────────┘
Troubleshooting Guide
Debug Checklist
□ 1. Remote configured? → git remote -v
□ 2. Upstream set? → git branch -vv
□ 3. Clean working tree? → git status
□ 4. Authentication ok? → git fetch (test)
Common Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| "rejected non-fast-forward" | Remote has new commits | git pull then push |
| "nothing to commit" | No changes or all staged | Check status |
| "unmerged files" | Conflict not resolved | Resolve conflicts first |
| "authentication failed" | Bad credentials | Re-authenticate |
Log Patterns
# Successful push
To github.com:user/repo.git
abc1234..def5678 main -> main
# Rejected push (need pull)
! [rejected] main -> main (non-fast-forward)
hint: Updates were rejected...
Unit Test Template
#!/bin/bash
# test_workflow.sh
test_pull_updates_local() {
# Setup: create remote with commit
# Action: git pull
# Assert: local has new commit
}
test_push_sends_changes() {
# Setup: create local commit
# Action: git push
# Assert: remote has new commit
}
test_status_shows_changes() {
# Setup: modify file
# Action: git status
# Assert: file shown as modified
}
Observability
logging:
level: INFO
events:
- workflow_started
- pull_completed
- changes_staged
- commit_created
- push_completed
- error_occurred
metrics:
- commits_per_day
- push_frequency
- conflict_rate
- workflow_completion_rate
Avoiding Common Mistakes
| Mistake | Prevention | Recovery |
|---------|------------|----------|
| Committing sensitive data | Use .gitignore, review before commit | Remove from history (complex) |
| Giant commits | Commit frequently, one change at a time | Split later with rebase -i |
| Vague messages | Follow commit message format | Amend if not pushed |
| Forgetting to pull | Always pull before starting work | Pull and merge/rebase |
| Pushing broken code | Test before pushing | Revert or fix-forward |
Next Steps
After mastering basic workflow:
- branching - Work on features in isolation
- collaboration - Work with team members
- advanced-git - Power user operations
"Consistent workflow leads to reliable code history."