atxtechbro / atxtechbro/dotfiles
docs: establish pattern for capturing unwritten assumptions
- Dominant language
- Shell
- Stars
- 27
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
## Context
Need a lightweight way to capture emerging assumptions and patterns before they're ready for formal documentation. As discussed: "Q&A-based documentation is more important than it all being in one place."
## Problem
Assumptions emerge during development but aren't always ready for the knowledge base. We need a low-friction way to capture these insights without cluttering the main codebase or going through PR process for every thought.
## Three Competing Approaches
### 1. Local ASSUMPTIONS.md (gitignored)
```bash
# In .gitignore
ASSUMPTIONS.local.md
# Usage
$EDITOR ASSUMPTIONS.local.md # Quick local edits
```
**Pros**:
- Zero friction, instant updates
- Private experimentation space
- No PR process
**Cons**:
- Not backed up
- Can't share with team
- Lost on machine switch
### 2. GitHub Wiki
```bash
gh repo edit --enable-wiki
git clone https://github.com/atxtechbro/dotfiles.wiki.git wiki
```
**Pros**:
- Version controlled
- No PR process
- Accessible from anywhere
**Cons**:
- Separate from main codebase
- AI agents might not discover it
- Another thing to maintain
### 3. Syntactic Prefix Comments
```bash
# ASSUMPTION: Q&A-based docs > single source of truth
```
```python
# TODO(assumption): This pattern assumes AI agents will be primary readers
```
```
git commit -m "feat: add search" -m "Assumption: breadcrumbs > hierarchy"
```
**Pros**:
- Lives with the code
- AI-discoverable in context
- Shows up in git history
**Cons**:
- Scattered across codebase
- No central list
- Can clutter code
## Recommendation
Start with **syntactic prefix comments** as the primary approach:
- Use `# ASSUMPTION:` for inline documentation
- Use `Assumption:` git commit trailers for commit-level insights
- Keep assumptions close to where they apply
If we need centralization later, we can grep for `ASSUMPTION:` patterns and extract them.
## Examples from Current Codebase
- OSE principle: "Grant broad tool permissions - just as managers don't want employees asking permission to staple papers"
- Permission philosophy: Now in knowledge base after starting as JSON comments
- Q&A documentation: This very assumption about modern workflows
What approach resonates with the team?
Principle: versioning-mindset
Contributor guide
No contributing guide indexed for this repository
Research direction
No repository file, test, or entry point is identified. Review the three proposed approaches and the recommendation in the issue, then determine whether the team has chosen a convention. Done means the decision and resulting assumption-capture pattern are documented and agreed upon.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, github
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100