# Contributing to AI Software Development Knowledge Base

This repository is designed for quick, iterative note-taking as you learn and develop software with AI assistance.

## ⚠️ CRITICAL: Non-Negotiable Standards

### 0. Documentation is NOT Optional

**Every PR must include documentation updates. No exceptions.**

Documentation keeps the project maintainable and helps both human developers and AI assistants work effectively. Code without documentation creates confusion, slows onboarding, and leads to knowledge loss.

#### What Counts as Documentation?
- **PR description**: Clear "what" and "why" explanation
- **Inline docstrings**: All functions/classes must have docstrings
- **Code comments**: Complex logic needs explanatory comments
- **README.md**: User-facing changes must update README
- **API docs**: Endpoint/interface changes must update API documentation
- **Architecture docs**: Design pattern changes must update architecture documentation
- **CHANGELOG**: Version changes must be documented (if maintained)

#### When is Documentation Required?

**Always required:**
- New public APIs, functions, or classes
- Changed function signatures or behavior
- New user-facing features or commands
- Breaking changes
- Complex algorithms or business logic
- New configuration options

**Sometimes required:**
- Bug fixes (if behavior changed noticeably)
- Refactoring (if API or usage changed)
- Performance optimizations (if user-visible)

**Not required (but docstrings still are):**
- Internal-only code changes
- Test-only changes
- Trivial fixes (typos in code, not user-facing)

#### Documentation Workflow

```bash
# 1. Before writing code: Check what docs exist
cat README.md
ls docs/

# 2. Make code changes + update docs together
# Edit src/api.py
# Edit docs/api.md
# Update docstrings in code

# 3. Commit code and docs together
git add src/api.py docs/api.md
git commit -m "feat: add user endpoint

- Add new /api/users endpoint
- Update API documentation
- Add docstrings to UserService class

Co-Authored-By: Your Name <email@example.com>"

# 4. PR checklist will verify docs are updated
```

#### Common Documentation Scenarios

**Adding a new feature:**
- ✅ Update README if user-facing
- ✅ Add docstrings to new functions
- ✅ Update API docs if endpoints added
- ✅ Add architecture docs if new patterns introduced
- ✅ Include examples if helpful

**Fixing a bug:**
- ✅ Update docstring if behavior changed
- ✅ Add comment explaining the fix (if non-obvious)
- ✅ Update README if user-visible fix
- ✅ Document root cause if it helps prevent future issues

**Refactoring:**
- ✅ Update comments to match new structure
- ✅ Update architecture docs if patterns changed
- ✅ Ensure docstrings still accurate
- ✅ Update examples if they use refactored code

**Documentation-only changes:**
- ✅ Use `docs:` prefix in commit/PR title
- ✅ Still follow PR template
- ✅ Explain what docs improved and why

#### Docstring Requirements

All functions must have Google-style docstrings:

```python
def process_data(
    data: pd.DataFrame,
    threshold: float = 0.8,
    normalize: bool = True
) -> tuple[pd.DataFrame, list[str]]:
    """Process dataframe and return results with errors.

    Args:
        data: Input dataframe to process
        threshold: Minimum quality threshold (0.0 to 1.0)
        normalize: Whether to normalize values before processing

    Returns:
        Tuple of (processed_dataframe, error_messages)

    Raises:
        ValueError: If threshold is not between 0.0 and 1.0
        DataValidationError: If data fails validation checks

    Example:
        >>> df = pd.DataFrame({'value': [1, 2, 3]})
        >>> result, errors = process_data(df, threshold=0.9)
        >>> print(len(errors))
        0
    """
    ...
```

#### PR Template Checklist

Every PR has a documentation checklist. You must:
- [ ] Check which docs are affected
- [ ] Update all affected documentation
- [ ] Verify docs match code changes
- [ ] OR check "No documentation needed" and explain why

The PR template will guide you through this process.

#### Why This Matters

- **Onboarding**: New contributors need docs to understand the codebase
- **Maintenance**: Future maintainers need docs to make changes safely
- **AI Assistants**: Claude and other AI tools rely on docs for context
- **Users**: End users need docs to use features correctly
- **Reviewers**: Code reviewers use docs to verify intent

**Documentation is not an afterthought. It's part of the code.**

---

### 1. Pull Request Requirement

**ALWAYS use pull requests. NEVER push directly to main. No exceptions.**

This applies to ALL changes:
- Code changes
- Documentation updates (even one-line fixes)
- Configuration changes
- Everything

**Workflow:**
1. Create a feature branch: `git checkout -b feature/your-change`
2. Make your changes
3. Push the branch: `git push -u origin feature/your-change`
4. Create a PR for review
5. Merge only after approval and CI checks pass

See [Development Workflow](docs/ENGINEERING_STANDARDS.md#development-workflow) for full details.

### 2. Python Virtual Environments - ALWAYS Required

**ALWAYS use virtual environments. NEVER modify or install packages to system/global Python. No exceptions.**

This applies to:
- All Python development
- Running any Python scripts or tools
- Installing any Python packages
- Both humans and AI assistants

**PROHIBITED Commands:**
```bash
# ❌ NEVER run these - they modify system Python
pip install <package>
python3 -m pip install --user <package>
sudo pip install <package>
```

**REQUIRED Workflow:**
```bash
# ✅ ALWAYS create and use virtual environment
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
pip install -r requirements.txt
```

**Why This Matters:**
- Protects user's system Python from corruption
- Ensures reproducible development environments
- Prevents dependency conflicts between projects
- Required by modern Python (PEP 668)

See [Python Best Practices](docs/ENGINEERING_STANDARDS.md#python-best-practices) for full details.

---

## Philosophy

**Quick Notes > Perfect Documentation**

The goal is to capture learnings as they happen, not to create perfect documentation. Raw notes, rough drafts, and work-in-progress content are all welcome.

## How to Contribute

### During Development

As you work with AI tools throughout your day, capture insights immediately:

1. **Quick Tips**: Drop a note in `tips-and-tricks/` when you discover something useful
2. **Model Behaviors**: Document AI quirks in `model-nuances/` as you encounter them
3. **Prompt Refinements**: Save effective prompts in `prompts/` for reuse
4. **Process Improvements**: Update playbooks in `playbooks/` when you find better workflows

### Using Claude REPL for Note-Taking

The repository is optimized for quick documentation via Claude or other AI tools:

```
# Jump into Claude and say:

"Add a tip to the tips-and-tricks/debugging folder about [insight I just learned]"

"Document this quirk I found with GPT-4 in the model-nuances section"

"Create a prompt template for [task] based on what I just did successfully"
```

### File Organization

#### Tips and Tricks (`tips-and-tricks/`)
- One tip per file
- Use descriptive filenames: `use-async-await-for-ai-calls.md`
- Include tags for searchability
- Quick format:
  ```markdown
  ## Tip: [Title]
  **Problem**: ...
  **Solution**: ...
  **Example**: ...
  **Tags**: #tag1 #tag2
  ```

#### Model Nuances (`model-nuances/`)
- One file per model or comparison
- Update as you discover new behaviors
- Focus on practical differences

#### Prompts (`prompts/`)
- Reusable prompt templates
- Organize by purpose in subdirectories
- Include variables and examples
- Document when the prompt works best

#### Playbooks (`playbooks/`)
- Step-by-step guides
- Include actual prompts to use
- Update based on experience
- Keep them practical and actionable

#### Methodologies (`methodologies/`)
- Higher-level approaches
- Can be rough drafts initially
- Refine over time

#### Specs (`specs/`)
- Standards and best practices
- Quality guidelines
- Process specifications

## Contribution Workflow

### Standard Workflow (Required)
1. Create a feature branch: `git checkout -b feature/your-change`
2. Make your changes on the feature branch
3. Commit frequently with descriptive messages
4. Push your feature branch: `git push -u origin feature/your-change`
5. Create a pull request for review
6. Address review feedback if needed
7. Merge only after approval

### For Larger Additions
1. Create a new file in the appropriate directory
2. Use existing files as templates
3. Add a README in new subdirectories
4. Link from relevant sections
5. Follow the standard PR workflow above

## Style Guidelines

### Minimal Requirements
- Use Markdown
- Include a title/heading
- Make it searchable (use good filenames and tags)

### Nice to Have
- Examples and code snippets
- Links to related content
- Personal experiences and context
- Tags for searchability

### Don't Worry About
- Perfect formatting
- Complete information
- Grammar and typos (can fix later)
- Organization (can reorganize later)

## Content Types

### ✅ Great Contributions
- "Here's a quirk I found with Claude today..."
- "This prompt worked really well for X"
- "I discovered that Y approach is faster than Z"
- "Gotcha: Watch out for this edge case"
- Raw observations and quick notes

### ✅ Also Great
- Refined guides and playbooks
- Organized documentation
- Comparison matrices
- Detailed examples

### ❌ Not Needed
- Perfect prose
- Complete coverage
- Formal documentation
- Academic rigor

## Tags

Use tags liberally to make content searchable:
- Language tags: `#python` `#javascript` `#java`
- Task tags: `#debugging` `#testing` `#refactoring`
- Model tags: `#claude` `#gpt4` `#copilot`
- Topic tags: `#prompting` `#best-practices` `#gotcha`

## Iterative Improvement

All content can and should be improved over time:

1. Start with rough notes
2. Add examples as you use techniques
3. Refine based on what works
4. Remove or update outdated information

## Questions?

This is a personal knowledge base. Make it work for you. If you want to:
- Add new categories → Go ahead
- Change organization → Do it
- Try different formats → Experiment
- Break conventions → That's fine

The goal is to capture and share knowledge, not to follow strict rules.

## Quick Start for Your Workday

### Morning
- Review recent additions for inspiration
- Check playbooks for today's tasks

### During Development
- Drop notes in relevant directories as you learn
- Save effective prompts immediately
- Document model quirks while fresh

### End of Day
- Quick review of what you learned
- Add any forgotten insights
- Update playbooks if you found better approaches

## Examples of Quick Contributions

### Example 1: Quick Tip (30 seconds)
```markdown
## Tip: Always specify language version

**Problem**: AI uses deprecated syntax
**Solution**: Include version in prompt
**Example**: "Using Python 3.11..." not just "Using Python..."
**Tags**: #prompting #python
```

### Example 2: Model Note (1 minute)
```markdown
# GPT-4 Quirk: Verbose Explanations

Noticed GPT-4 tends to over-explain. 
Good for learning, annoying when you just need code.

Workaround: Add "concise code only" to prompts.
```

### Example 3: Prompt Save (2 minutes)
```markdown
# Quick Bug Fix Prompt

"Here's the error: [error]
Here's the code: [code]
What's wrong and how do I fix it?"

Works great for simple bugs. For complex issues, need more context.
```

## Remember

**Document now, refine later. Raw knowledge is better than lost knowledge.**
