hub/docs/DEV_NOTES_README.md

Developer Personal Notes

Purpose

This directory pattern allows developers to keep personal notes, TODOs, and scratch documentation locally without polluting the shared repository.

---

What Goes Here

✅ Personal Developer Notes

• Work-in-progress thoughts
• Personal TODOs and task lists
• Debugging notes
• Feature brainstorming
• Learning notes about the codebase
• Temporary documentation while working
• Meeting notes
• Personal reminders

❌ Not Personal Notes (belongs in shared docs)

• Architectural decisions (→ SYSTEM_ARCHITECTURE.md)
• Implementation guides (→ docs/supplements/)
• Security patterns (→ SYSTEM_ARCHITECTURE.md)
• Team-wide decisions (→ proper docs/)

---

File Naming Patterns

All these patterns are automatically ignored by git:

1. /docs/dev-notes/ Directory

Create your own folder:

mkdir -p docs/dev-notes/kelly/
mkdir -p docs/dev-notes/john/

Put any notes here:

docs/dev-notes/kelly/processing-refactor.md
docs/dev-notes/kelly/database-optimization-ideas.md
docs/dev-notes/john/ui-improvements.md

Git status: Completely ignored, never committed

2. *.dev.md Files

Any file ending in .dev.md is ignored:

PROCESSING_REFACTOR.dev.md
API_CHANGES.dev.md
my-thoughts.dev.md

Use case: Quick notes anywhere in the repo

3. Standard Personal Files

These common filenames are ignored:

NOTES.md                  # General scratchpad
TODO.personal.md          # Your personal TODOs

Use case: Quick notes in project root

---

Recommended Workflow

For Quick Scratch Notes

# Create a quick scratchpad in root
echo "# My Current Work" > NOTES.md
echo "- Fix product scoping bug" >> NOTES.md
echo "- Update department filters" >> NOTES.md

This file stays on your machine only.

For Organized Notes by Topic

# Create your personal dev-notes folder
mkdir -p docs/dev-notes/$(whoami)/

# Create topic-specific notes
vim docs/dev-notes/$(whoami)/department-refactor.md
vim docs/dev-notes/$(whoami)/performance-todos.md

Organize however you want - it won't be committed.

For Feature Branch Work

# While working on a feature
vim feature-social-media.dev.md

# Write down:
# - Implementation thoughts
# - Edge cases to test
# - Questions for review
# - Refactoring ideas

When feature is done:

• If notes are still useful → move important parts to proper docs
• Otherwise → delete the .dev.md file

---

Example Personal Note Structure

File: docs/dev-notes/kelly/product-refactor.md

# Product Refactor - Personal Notes

## Current Problems
- Products table is missing batch_id scoping
- N+1 queries in marketplace

## My TODO
- [x] Add batch_id to products table
- [ ] Update ProductPolicy for batch access
- [ ] Test with multiple businesses

## Questions for Team
- Should we cascade delete batches when product deleted?
- What about historical order_items?

## Resources
- See SYSTEM_ARCHITECTURE.md Section 11 for patterns
- Batch system docs: docs/supplements/batch-system.md

## Ideas for Future
- Maybe add batch_id index?
- Consider eager loading batches by default

---

When to Promote Notes to Shared Docs

If your personal notes contain:

🔄 Promote to Shared Docs:

• Architectural decisions → Update SYSTEM_ARCHITECTURE.md
• New patterns everyone should follow → Update SYSTEM_ARCHITECTURE.md
• Feature implementation details → Create docs/features/FEATURE_NAME.md
• Security patterns → Add to SYSTEM_ARCHITECTURE.md Section 5
• Common mistakes → Add to SYSTEM_ARCHITECTURE.md "Common Mistakes"

🗑️ Delete When Done:

• Temporary debugging notes
• Fixed bugs
• Completed TODOs
• Brainstorming that led nowhere

📁 Keep Local:

• Personal learning notes
• Your preferred workflows
• Reminders for yourself
• Work-in-progress thoughts

---

Benefits

For You:

• ✅ Keep messy notes without shame
• ✅ Don't lose your thoughts
• ✅ Organize your work however you like
• ✅ No merge conflicts with other devs' notes

For the Team:

• ✅ Repo stays clean
• ✅ Shared docs are intentional and high-quality
• ✅ No confusion about what's "official"
• ✅ Each dev can work differently

---

Example: Kelly's Personal Setup

hub/
├── NOTES.md                           ← Quick scratchpad (gitignored)
├── docs/
│   ├── dev-notes/
│   │   └── kelly/
│   │       ├── current-sprint.md      ← Sprint notes
│   │       ├── processing-research.md ← Research notes
│   │       └── database-ideas.md      ← Future ideas
│   │
│   └── (shared docs...)

Git sees NONE of kelly's personal notes.

---

FAQ

Q: What if I accidentally commit personal notes?

A: The .gitignore prevents this. But if you created a file outside the patterns:

git reset HEAD <file>
git checkout <file>

Q: Can I share my personal notes with a teammate?

A: Yes! They're just markdown files on your local machine. Copy/paste or send directly. If the content is valuable for everyone, promote it to shared docs instead.

Q: Should I commit my dev-notes/ folder?

A: NO. It's in .gitignore for a reason. Dev notes are personal.

Q: What if I want to track my notes in git but not share them?

A: Use a personal branch that never gets merged:

git checkout -b personal-notes
# Add your notes
git add docs/dev-notes/
git commit -m "Personal notes"
# Push to your own branch
git push origin personal-notes

But this is overkill for most people. Local files work fine.

---

Summary

The Rule:

• Personal/temporary = Use ignored patterns (dev-notes/, *.dev.md, NOTES.md)
• Team-wide/architectural = Update SYSTEM_ARCHITECTURE.md or docs/supplements/

Keep the repo clean. Keep your thoughts organized.

---

Questions? Check docs/DOC_MAINTENANCE.md for overall documentation strategy.