notetaker-fundamentals

What this skill does

# Note-Taking Fundamentals for AI-Assisted Development

Effective note-taking patterns for AI assistants to leave meaningful context in codebases.

## Philosophy

When AI assistants make changes to code, they should leave breadcrumbs for future AI assistants and human developers. Notes should:

- **Preserve context** about why decisions were made
- **Signal uncertainty** where alternative approaches exist
- **Mark incomplete work** that needs follow-up
- **Link to relevant context** (issues, PRs, documentation)
- **Explain non-obvious patterns** that might confuse readers

## Note Formats

### AI Development Notes

Special comment format for AI-to-AI communication:

```typescript
// AI-DEV-NOTE: This function uses a cache-first strategy because
// the data rarely changes and network calls were causing performance
// issues. See performance profiling in PR #123.
```

```python
# AI-DEV-NOTE: The validation order matters here - we must check
# authentication before authorization to avoid leaking user existence.
# Alternative approach using middleware was considered but rejected
# due to increased complexity.
```

**When to use:**

- Explaining non-obvious implementation decisions
- Documenting alternative approaches that were considered
- Linking to related context (PRs, issues, discussions)
- Warning about subtle bugs or edge cases
- Preserving rationale for future refactoring decisions

### Structured TODO Comments

Enhanced TODO format with context:

```javascript
// TODO(ai/context): Extract this validation logic into a separate
// validator class. Currently duplicated in 3 places:
// - src/api/users.ts:45
// - src/api/auth.ts:78
// - src/validators/user.ts:12
// Blocked by: Waiting for PR #456 to merge validator base class
```

```go
// TODO(ai/performance): This O(n²) loop should be optimized.
// Profiling shows 45% of request time spent here when n > 100.
// Consider: hash map lookup or binary search after sorting.
// Impact: High - affects main user flow
// Effort: Medium - 2-3 hours estimated
```

**TODO Format Structure:**

```
// TODO(ai/<category>): <Brief description>
// <Additional context>
// <Alternative approaches>
// <Blockers/Dependencies>
// <Impact/Priority>
```

**Common categories:**

- `ai/refactor` - Code structure improvements
- `ai/performance` - Optimization opportunities
- `ai/security` - Security considerations
- `ai/accessibility` - A11y improvements
- `ai/testing` - Test coverage gaps
- `ai/docs` - Documentation needs
- `ai/context` - Context preservation
- `ai/edge-case` - Unhandled edge cases

### Decision Records

Inline decision records for significant choices:

```rust
// DECISION: Using Arc<RwLock<T>> instead of Mutex<T>
// RATIONALE: Read-heavy workload (95% reads, 5% writes) benefits
// from RwLock's concurrent read access. Benchmarks showed 3x throughput
// improvement with RwLock under typical load patterns.
// ALTERNATIVES_CONSIDERED:
//   - Mutex<T>: Simpler but slower for read-heavy workload
//   - atomic types: Not suitable for complex state
// DATE: 2025-12-04
// AUTHOR: Claude (AI Assistant)
```

**When to use decision records:**

- Choosing between competing patterns/libraries
- Performance trade-offs (memory vs speed, etc.)
- Architecture decisions affecting multiple files
- Security-sensitive choices
- Decisions that will be questioned later

### Context Preservation

Leaving breadcrumbs for future understanding:

```typescript
// CONTEXT: This weird-looking workaround is necessary because Safari
// doesn't support the standard API (as of v17.2). Filed webkit bug:
// https://bugs.webkit.org/show_bug.cgi?id=123456
// Remove this when Safari support lands (check caniuse.com)
if (isSafari) {
  // Fallback implementation
}
```

```python
# CONTEXT: Database migration added 'deleted_at' column (migration_003)
# but we're still using 'is_deleted' for backward compatibility during
# the transition period. Can remove 'is_deleted' after 2025-12-31
# when all old records are migrated.
```

### Uncertainty Markers

Signaling areas where AI is uncertain:

```java
// AI-UNCERTAIN: This might not handle timezone edge cases correctly
// around DST transitions. Manual review recommended by a developer
// familiar with timezone handling.
```

```swift
// AI-UNCERTAIN: Not sure if this is thread-safe in all scenarios.
// Consider adding synchronization or having a concurrency expert review.
```

## Note Placement Guidelines

### Where to Place Notes

**Good placements:**

```typescript
// AI-DEV-NOTE: Complex business logic follows - this implements the
// three-tier approval workflow described in docs/workflows.md
function processApproval(request: ApprovalRequest) {
  // Implementation...
}
```

**Bad placements:**

```typescript
function processApproval(request: ApprovalRequest) {
  const step1 = validate(request);
  // AI-DEV-NOTE: This whole function is complex
  const step2 = process(step1);
  // Bad - note is buried in implementation details
}
```

### Proximity Rules

- Place notes **immediately before** the code they describe
- For file-level notes, place at the **top after imports**
- For function-level notes, place **immediately before the function**
- For inline notes, place on the **line above** the relevant code

### Note Density

Avoid over-annotation:

```typescript
// ❌ TOO MANY NOTES
// AI-DEV-NOTE: Parsing user input
const input = parseInput(raw);
// AI-DEV-NOTE: Validating the input
const valid = validate(input);
// AI-DEV-NOTE: Processing the result
const result = process(valid);

// ✅ APPROPRIATE DENSITY
// AI-DEV-NOTE: Standard validation pipeline - parse, validate, process
// Each step can throw ValidationError which is handled by middleware
const input = parseInput(raw);
const valid = validate(input);
const result = process(valid);
```

## Cross-Referencing

### Linking to Issues/PRs

```javascript
// AI-DEV-NOTE: Implements user story from issue #1234
// See PR #1245 for discussion on alternative approaches
```

### Linking to Documentation

```python
# AI-DEV-NOTE: Algorithm explained in docs/algorithms/rate-limiting.md
# Based on token bucket algorithm: https://en.wikipedia.org/wiki/Token_bucket
```

### Linking to Other Code

```go
// AI-DEV-NOTE: Mirror of validation logic in api/v2/handlers.go:123
// Keep these in sync or extract to shared validator
```

## Note Maintenance

### Expiration Dates

For temporary notes or workarounds:

```typescript
// AI-DEV-NOTE: Temporary workaround for API v1 compatibility
// REMOVE_AFTER: 2025-12-31 (when v1 API is fully deprecated)
```

```python
# TODO(ai/temporary): Using placeholder implementation
# REPLACE_WHEN: Real authentication service is deployed
```

### Note Updates

When modifying code with existing notes:

```javascript
// AI-DEV-NOTE: [UPDATED 2025-12-04] Originally used synchronous
// processing but switched to async to prevent UI blocking.
// Previous note preserved for context.
// [ORIGINAL 2025-11-15] This processes items synchronously...
```

## Anti-Patterns

### Don't

❌ Leave vague notes

```javascript
// AI-DEV-NOTE: This is important
// Bad - no context about WHY it's important
```

❌ Over-explain obvious code

```python
# AI-DEV-NOTE: This increments the counter by 1
count += 1  # Obvious from code
```

❌ Leave notes without actionable information

```typescript
// TODO: Fix this
// Bad - no context on WHAT needs fixing or HOW
```

❌ Duplicate information already in commit messages

```java
// AI-DEV-NOTE: Added error handling
// Bad - commit message already says this
```

### Do

✅ Provide specific, actionable context

```javascript
// AI-DEV-NOTE: Order validation must happen before inventory check
// to prevent race condition where items are reserved but invalid
```

✅ Explain the "why" not the "what"

```python
# AI-DEV-NOTE: Using binary search instead of linear search because
# the dataset can exceed 10k items (profiling showed 300ms avg latency)
```

✅ Include concrete next steps

```typescript
// TODO(ai/refactor): Ext