atxtechbro / atxtechbro/dotfiles
feat(principles): add "principle-of-least-surprise" for clean PR workflows
- 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