atxtechbro / atxtechbro/dotfiles

docs: establish pattern for capturing unwritten assumptions

Open
#983 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.