atxtechbro / atxtechbro/dotfiles

feat(principles): add "principle-of-least-surprise" for clean PR workflows

Open
#703 1 comment 0 reactions 0 assignees View on GitHub
documentation enhancement workflow
Dominant language
Shell
Stars
27
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Summary
Add the Principle of Least Surprise to ensure clean, predictable GitHub PR diffs that maintain productivity in AI-assisted workflows.

## Problem Statement
When GitHub PR diffs show unexpected changes (whitespace, unrelated files, formatting noise), it:
- Breaks cognitive flow during visual code review
- Obscures the actual changes being made
- Creates distrust in the AI's work
- Wastes time investigating phantom changes
- Reduces throughput by adding cognitive overhead

## Proposed Principle: Principle of Least Surprise

```markdown
# Principle of Least Surprise

The expectation that system outputs match mental models, especially in collaborative AI-human workflows where visual review is essential.

## Core Tenets
1. **PR diffs show only intended changes** - No phantom whitespace, no unexpected files
2. **Changes match their description** - What you say you're changing is what changes
3. **Clean start, clean finish** - PRs begin and end in predictable states
4. **Noise kills productivity** - Even one unexplained line derails review flow

## In Practice
- Run `git diff --cached` before every commit to verify changes
- Use `git add -p` for surgical staging when needed
- Configure editors to respect existing formatting
- Test that PR descriptions match actual diffs
- Treat unexpected changes as bugs, not annoyances

## Why This Matters
- GitHub visual diff is part of the essential AI-human feedback loop
- Trust requires predictability
- Cognitive buffer is limited - don't waste it on surprises
- Clean PRs = faster reviews = higher throughput

## Red Flags
- "Why is this file in the diff?"
- "I didn't change that line"
- "This should be a one-line change but shows 50"
- Whitespace or formatting changes in unrelated files
- Binary files appearing unexpectedly

## Connection to Other Principles
- Supports **Throughput Definition** - removes friction from the review cycle
- Enables **Transparency in Agent Work** - clear diffs show clear intent
- Upholds **Systems Stewardship** - predictable systems are maintainable systems
```

## Implementation Notes
- Add pre-commit hooks to catch formatting issues
- Configure AI tools to respect existing code style
- Document expected PR patterns in CONTRIBUTING.md
- Consider git aliases for checking diff cleanliness

## Example Violations
1. AI reformats entire file when changing one function
2. Line ending changes pollute the diff
3. Auto-generated files appear without explanation
4. Import reordering when not requested
5. Trailing whitespace modifications in unchanged sections

This principle ensures that the visual GitHub PR review remains a productive part of the AI-assisted development workflow.

Principle: systems-stewardship

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating the repository's existing principle documents and CONTRIBUTING.md, then inspect the current pre-commit setup. Confirm whether this issue covers only the principle text or also the listed hooks, AI-tool configuration, and git aliases. Done means the agreed scope is documented and any included checks have clear verification steps.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, github
Domain
developer-experience, documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.