Best Practices

This guide outlines recommended practices for using gith effectively in your development workflow.

When to Use Human Certification

✅ Appropriate Use Cases

Use gith commit --human for content that is genuinely created without AI assistance:

# ✅ Good - You wrote this logic yourself
gith commit --human -m "Implement binary search algorithm"

# ✅ Good - Original architectural decisions
gith commit --human -m "Design database schema for user management"

# ✅ Good - Hand-crafted business logic
gith commit --human -m "Add payment processing workflow"

❌ Inappropriate Use Cases

Avoid flagging AI-assisted work as human-generated:

# ❌ Avoid - Don't flag AI-assisted work as human
gith commit --human -m "Add code generated by ChatGPT"

# ❌ Avoid - Mixed human/AI content
gith commit --human -m "Refactor with AI suggestions"

# ❌ Avoid - Uncertainty about origin
gith commit --human -m "Update code (not sure if I used AI)"

Establishing Team Conventions

Define Clear Policies

Create team-wide standards for human certification:

# Example team policy documented in project
cat >> CONTRIBUTING.md << 'EOF'
## Human-Generated Content Policy

- **Core business logic**: Always human-flagged
- **Security-sensitive code**: Human-flagged when possible
- **Bug fixes**: Human-flagged if significant algorithmic changes
- **Documentation**: Mixed (flag original content as human)
- **Tests**: Mixed (flag hand-written test logic as human)
- **Configuration**: Regular commits unless custom logic involved

To view certified human content: `gith list-human`
EOF

Consistent Workflow

Establish predictable patterns:

# Consistent approach for feature development
gith checkout -b feature/user-auth

# 1. Design phase (human)
gith commit --human -m "feat: design authentication architecture"

# 2. Implementation (mixed - be honest)
gith commit --human -m "feat: implement JWT token validation"
gith commit -m "feat: add error handling with AI assistance"

# 3. Testing (mixed)
gith commit --human -m "test: add comprehensive auth tests"
gith commit -m "test: add edge cases from AI suggestions"

Documentation Standards

Project-Level Documentation

Document your human-generation policy:

echo "## Human-Generated Content Policy

This project uses gith to track human-generated content.

### Our Standards
- Original algorithms and business logic: Human-flagged
- Architectural decisions: Human-flagged
- Security implementations: Human-flagged when possible
- Bug fixes: Case-by-case basis
- Generated code: Never human-flagged
- Boilerplate: Regular commits

### Verification
- View certified content: \`gith list-human\`
- Monthly reports generated automatically
- Code review includes human-generation verification

### Questions?
Contact the maintainers for clarification on certification standards.
" >> README.md

gith add README.md
gith commit --human -m "docs: add human-generation policy"

Commit Message Standards

Use clear, descriptive commit messages:

# ✅ Good - Clear about human contribution
gith commit --human -m "implement custom caching algorithm for user sessions"

# ✅ Good - Specific about what's human-generated
gith commit --human -m "design API endpoint structure for payment processing"

# ❌ Avoid - Vague about content
gith commit --human -m "update stuff"

# ❌ Avoid - Unclear about generation method
gith commit --human -m "fix things"

Code Review Integration

Review Process

Include human-generation verification in code reviews:

# Reviewer checklist
echo "## Code Review Checklist

### Human-Generation Verification
- [ ] Human-flagged commits contain genuinely human-generated content
- [ ] No AI-assisted work incorrectly flagged as human
- [ ] Commit messages accurately describe contribution type
- [ ] License implications understood and appropriate

### Technical Review
- [ ] Code quality meets standards
- [ ] Tests included and passing
- [ ] Documentation updated
- [ ] No security vulnerabilities

Use: \`gith list-human --commits-only\` to review human-certified changes
" > .github/pull_request_template.md

Verification Commands

Use these commands during review:

# Review human-certified commits in PR
git log --grep="Human-Flag: true" origin/main..HEAD

# Check specific commit details
git show --show-signature <commit-hash>

# View all human content in branch
gith list-human --commits-only

Security Considerations

Sensitive Code

Be especially careful with security-related code:

# Security implementations should be human when possible
gith commit --human -m "implement password hashing with bcrypt"
gith commit --human -m "add JWT signature verification"

# But be honest about AI assistance
gith commit -m "add rate limiting with AI-suggested parameters"

Access Control

Consider who can make human-certified commits:

# Example pre-commit hook for verification
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
if git log -1 --pretty=%B | grep -q "Human-Flag: true"; then
    echo "⚠️  Human-certified commit detected"
    echo "Please verify this content is entirely human-generated"
    echo "Continue? (y/n)"
    read -r response
    if [[ ! "$response" =~ ^[Yy]$ ]]; then
        exit 1
    fi
fi
EOF
chmod +x .git/hooks/pre-commit

Workflow Integration

Development Branches

Organize branches with human-generation in mind:

# Feature development
gith checkout -b feature/payment-system

# Separate human-designed architecture
gith commit --human -m "design: payment system architecture"

# Implement with mixed approaches
gith commit --human -m "implement: core payment processing logic"
gith commit -m "implement: error handling and validation"

# Separate branch for generated code if needed
gith checkout -b feature/payment-system-generated
# ... add AI-generated boilerplate ...
gith commit -m "add: payment service boilerplate"

Continuous Integration

Integrate verification into CI/CD:

# .github/workflows/verify-human.yml
name: Verify Human Content
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install gith
        run: cargo install gith
      - name: Report human content
        run: |
          echo "## Human-Certified Content in PR" >> $GITHUB_STEP_SUMMARY
          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
          gith list-human --commits-only | head -10 >> $GITHUB_STEP_SUMMARY
          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

Maintenance and Monitoring

Regular Audits

Periodically review human-generation patterns:

# Monthly human content report
cat > scripts/human_report.sh << 'EOF'
#!/bin/bash
echo "=== Human Content Report - $(date +%B\ %Y) ==="
echo ""

total_commits=$(git rev-list --count HEAD)
human_commits=$(gith list-human --commits-only | grep -v "Human-Generated Commits" | grep -v "=" | wc -l)

echo "Statistics:"
echo "- Total commits: $total_commits"
echo "- Human-certified: $human_commits"
echo "- Percentage: $(( human_commits * 100 / total_commits ))%"
echo ""

echo "Recent human-certified commits:"
gith list-human --commits-only | head -10
EOF

chmod +x scripts/human_report.sh

Quality Assurance

Monitor for inconsistencies:

# Check for potential issues
cat > scripts/audit_human.sh << 'EOF'
#!/bin/bash
echo "Checking for potential human-generation inconsistencies..."

# Look for AI-related keywords in human-flagged commits
git log --grep="Human-Flag: true" --pretty=format:"%h %s" | \
    grep -i -E "(chatgpt|copilot|ai|generated|gpt)" && \
    echo "⚠️  Found AI-related terms in human-flagged commits"

# Check for very short intervals between human commits
git log --grep="Human-Flag: true" --pretty=format:"%h %at %s" | \
    sort -k2 -n | \
    awk '{
        if (prev && ($2 - prev) < 60) {
            print "⚠️  Rapid human commits: " prev_hash " and " $1
        }
        prev = $2; prev_hash = $1
    }'
EOF

chmod +x scripts/audit_human.sh

Common Pitfalls to Avoid

Over-Certification

Don't flag everything as human:

# ❌ Bad - Over-flagging trivial changes
gith commit --human -m "fix typo in comment"
gith commit --human -m "update dependency version"

# ✅ Good - Reserve for meaningful human contributions
gith commit -m "fix typo in comment"
gith commit --human -m "refactor core algorithm for better performance"

Under-Certification

Don't miss significant human contributions:

# ❌ Bad - Missing human contribution
gith commit -m "implement advanced search algorithm"  # Should be --human

# ✅ Good - Proper certification
gith commit --human -m "implement advanced search algorithm"

Inconsistent Standards

Maintain consistent certification criteria:

# Document decisions for consistency
echo "# Human Certification Decisions Log

## 2024-01-15
- Decision: All custom algorithms flagged as human
- Decision: Configuration files are regular commits unless custom logic
- Decision: Generated migrations are regular commits

## 2024-01-20
- Decision: Security implementations prioritized for human flagging
- Decision: Test utilities can be mixed based on complexity
" > docs/certification_log.md

Following these best practices ensures that your use of gith provides accurate, consistent, and valuable tracking of human-generated content in your projects.