atxtechbro / atxtechbro/dotfiles
feat(retro): incorporate Brooksian documentation principles into post-PR retros
- Dominant language
- Shell
- Stars
- 27
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
Our post-PR retros focus well on systems improvement but could benefit from Fred Brooks' wisdom about documentation tradeoffs. We're missing opportunities to capture architectural insights and balance precision with communicativeness.
## Proposed Enhancement
Enhance the post-PR mini retro procedure with Brooks-inspired questions that examine our documentation and communication practices.
## Suggested Retro Additions
### Documentation Tradeoffs Section
Add these prompts to the retro procedure:
**Brooks' Precision vs. Communicativeness Check:**
- Where were we overly precise but hard to understand?
- Where did we favor clarity but risk important ambiguity?
- Did our documentation capture the "why" or just the "what"?
**Architectural Discovery:**
- What assumptions were invalidated during implementation?
- What would we tell someone implementing this feature next time?
- Should this learning be captured in architecture decisions?
**Documentation Debt:**
- What knowledge is still tribal/in our heads?
- What diagrams would have helped?
- Where did we discover the docs were wrong?
## Implementation Ideas
1. **Create docs/architecture-decisions/ directory**
- Capture "why" not just "what"
- Use ADR (Architecture Decision Record) format
- Include discovery stories
2. **Add "Lessons Learned" to PR template**
- What we thought vs. what we learned
- Architectural insights discovered
- Documentation that needs updating
3. **Monthly "Mythical Man-Month" principle**
- Rotate Brooks quotes/principles in retros
- Apply them to current work
- Build a culture of reflective documentation
## Example Brooks Principles for Retros
- "The bearing of a child takes nine months, no matter how many women are assigned"
- "Plan to throw one away; you will, anyhow"
- "Adding manpower to a late software project makes it later"
- "The documentary hypothesis: Writing decisions down is essential"
## Why This Matters
Per the Snowball Method, 20% of our time should improve systems. Documentation *is* a system - one that compounds knowledge over time. Brooks teaches us that good documentation isn't about being exhaustive; it's about finding the sweet spot between precision and understanding.
## Success Criteria
- Retros capture more "aha\!" moments
- Fewer repeated mistakes across PRs
- Documentation that future us (and future AI agents) can actually use
- Balance between "accurate" and "understandable"
Principle: systems-stewardship
Principle: transparency-in-agent-work
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating the post-PR mini retro procedure and PR template referenced by the issue, then review whether a docs/architecture-decisions/ directory already exists. Define the implementation scope before changing anything; done should include an agreed way to capture documentation tradeoffs, architectural discoveries, and lessons learned in retros.
Written by the indexing model from the issue text.
Assessment
- Domain
- developer-experience, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100