MATRIX-NOTE-TAKING-INSTRUCTIONS.mdโข9.58 kB
# Knowledge Matrix Note-Taking Instructions
## Revenue Engine MCP Project
**Version:** 1.0
**Created:** 2025-10-16
**Purpose:** Structured documentation for automated analysis and time tracking
---
## ๐ Overview
The Knowledge Matrix is your session log. These instructions ensure entries are:
1. **Parseable** by automation tools (`matrix_daily_summary`, `matrix_time_analysis`)
2. **Searchable** for historical reference
3. **Actionable** for future sessions
4. **Consistent** across all entries
---
## ๐ Time Format Standards
**CRITICAL:** Always include timestamps and time spent for accurate tracking.
### Entry Timestamps
**Format:** `H:MMpm/am TIMEZONE` at the start of each entry
**Examples:**
- โ
`3:45pm CST ๐ Fixed EMAIL-001`
- โ
`11:30am CST ๐ Updated documentation`
- โ `Fixed a bug` (no timestamp)
- โ `3pm Fixed bug` (no timezone)
### Time Spent Notation
Use square brackets `[TIME]` to indicate duration.
**Accepted formats:**
- `[30m]` - 30 minutes
- `[2h]` - 2 hours
- `[1.5h]` - 1.5 hours (90 minutes)
- `[45min]` - 45 minutes
**Placement:** At the end of the activity description or within it.
**Examples:**
- โ
`3:45pm CST ๐ Fixed EMAIL-001 [30m]`
- โ
`4:15pm CST โ
Built new dashboard feature [2h]`
- โ
`Debugging deployment issues [45min] - found root cause`
- โ `Fixed bug (took about half an hour)` (not parseable)
---
## ๐ท๏ธ Bug UID Format
**Format:** `[CATEGORY]-[NUMBER]`
### Bug Categories
- **EMAIL** - Gmail integration issues
- **DEPLOY** - Deployment and infrastructure issues
- **MATRIX** - Knowledge Matrix system issues
- **PIPELINE** - Lead management issues
- **CALENDAR** - Google Calendar integration issues
- **API** - Apps Script API issues
- **MCP** - MCP server issues
- **AUTH** - Authentication/permissions issues
- **DATA** - Data integrity/corruption issues
- **PERF** - Performance issues
### Number Format
- Always 3 digits: `001`, `002`, `010`, `100`
- Sequential within category
### Full Bug Entry Format
```
[TIME] [BUG-UID] [STATUS] [SEVERITY] Brief description [TIME_SPENT]
- Root cause: ...
- Solution: ...
- Related: [OTHER-BUG-UID] (if applicable)
```
**Example:**
```
3:00pm CST EMAIL-001 FIXED HIGH get_email_content not working [30m]
- Root cause: MCP pointing to old deployment @23
- Solution: Created deployment @25, updated MCP URL
- Related: DEPLOY-002
```
### Bug Status Values
- **NEW** - Just discovered
- **INVESTIGATING** - Root cause analysis in progress
- **IN PROGRESS** - Actively working on fix
- **TESTING** - Fix deployed, needs verification
- **FIXED** - Verified working
- **WONTFIX** - Not addressing (document reason)
### Bug Severity Levels
- **CRITICAL** - System down, data loss, security breach
- **HIGH** - Major feature broken, blocking work
- **MEDIUM** - Feature partially broken, workaround exists
- **LOW** - Minor issue, cosmetic, edge case
---
## โ
Feature Entries
### Format
```
[TIME] [EMOJI] Feature name/description [TIME_SPENT]
- Key details or sub-features
- Implementation notes
```
**Examples:**
```
3:30pm CST โ
Added matrix_daily_summary tool [2h]
- Parses timestamps, bug UIDs, time spent
- Supports bullet, prose, and Slack formats
- Auto-calculates session stats
```
---
## ๐งช Testing Results
### Format
```
[TIME] ๐งช What was tested [TIME_SPENT]
- Test scenarios covered
- Results/findings
- Issues discovered (link to bug UIDs if created)
```
**Example:**
```
3:15pm CST ๐งช Email fetching fully tested [15m]
- Test email: "Check this out" from Chris
- Successfully retrieved 3 attachments (19.1MB total)
- All metadata working: labels, unread status, importance
```
---
## ๐ฏ Decisions & Direction
### Format
```
[TIME] ๐ฏ Decision made or direction set
- Context/reasoning
- Alternatives considered
- Expected impact
```
**Example:**
```
3:20pm CST ๐ฏ Learned deployment workflow
- Apps Script deployments are immutable
- Process: Edit code โ clasp push โ clasp deploy โ update MCP URL โ restart Claude
- Each deploy creates new version and URL
```
---
## ๐ Documentation Updates
### Format
```
[TIME] ๐ What was documented
- Files affected
- Key additions or changes
```
**Example:**
```
3:30pm CST ๐ Created Bug Tracking System documentation
- File: BUG-TRACKING-SYSTEM.md
- UID format: [CATEGORY]-[NUMBER]
- 10 categories, 4 severity levels, 6 status values
```
---
## โก Next Session Goals
### Format
```
[PRIORITY] Goal description
- Sub-goals or requirements
- Blockers (if any)
- Related context
```
**Priority Indicators:**
- ๐ด **HIGH** - Critical, blocking, or time-sensitive
- ๐ก **MEDIUM** - Important but not urgent
- ๐ข **LOW** - Nice to have, low priority
**Example:**
```
๐ด HIGH: Deploy and test new Matrix tools
- Restart Claude to pick up v1.7.0
- Test matrix_daily_summary with today's data
- Test matrix_time_analysis across week
๐ก MEDIUM: Build analyze_pipeline_health tool
- Identify stale leads
- Calculate conversion metrics
```
---
## ๐ Cross-Referencing
### Linking Items
- **Bugs to Bugs:** `Related: EMAIL-002`
- **Features to Bugs:** `Fixed EMAIL-001, DEPLOY-003`
- **Sessions to Bugs:** Reference bug UIDs naturally in text
### Searching
The `query_matrix` tool can find:
- Bug UIDs: Search for `EMAIL-001`
- Keywords: Search for `deployment`, `gmail`, `matrix`
- Time periods: Use `read_matrix_snapshot` with date ranges
---
## โ ๏ธ Common Mistakes to Avoid
โ **Missing timestamps**
```
Fixed a bug in email fetching
```
โ
**Correct:**
```
3:00pm CST ๐ Fixed EMAIL-001 [30m]
```
---
โ **Vague time notation**
```
Took about an hour to debug
```
โ
**Correct:**
```
Debugging session [1h]
```
---
โ **No bug UID**
```
3:00pm CST Fixed email content retrieval
```
โ
**Correct:**
```
3:00pm CST EMAIL-001 FIXED HIGH Fixed email content retrieval [30m]
```
---
โ **Incomplete bug entry**
```
EMAIL-001 Fixed
```
โ
**Correct:**
```
3:00pm CST EMAIL-001 FIXED HIGH get_email_content not working [30m]
- Root cause: MCP pointing to old deployment
- Solution: Created deployment @25
```
---
## ๐ Automation Tools
### `matrix_daily_summary`
**What it parses:**
- Timestamps (for chronological ordering)
- Bug UIDs (counts and lists)
- Time spent markers `[30m]`, `[2h]`
- Topic content
**Output formats:**
- `bullet` - Markdown with headers and bullets
- `prose` - Natural paragraph format
- `slack` - Formatted for Slack with emojis
**Usage:**
```javascript
matrix_daily_summary({
date: "2025-10-16",
format: "bullet"
})
```
---
### `matrix_time_analysis`
**What it parses:**
- Time spent markers `[30m]`, `[2h]`
- Bug UIDs (for bug-specific tracking)
- Dates (for grouping)
**Grouping options:**
- `topic` - Time by Matrix topic (Bugs, Features, etc.)
- `bug` - Time per bug UID
- `week` - Weekly totals
- `day` - Daily breakdown
**Usage:**
```javascript
matrix_time_analysis({
startDate: "2025-10-01",
endDate: "2025-10-16",
groupBy: "bug"
})
```
---
## โ
Complete Entry Examples
### Bug Fix Entry
```
3:00pm CST EMAIL-001 FIXED HIGH get_email_content tool not working [30m]
- Root cause: MCP server pointing to old deployment @23, thread.isStarred() not valid
- Solution: Removed isStarred(), created deployment @25, updated MCP URL
- Status: โ
VERIFIED - successfully fetching emails with attachments
```
### Feature Addition
```
3:35pm CST โ
Implemented Bug Tracking System [45m]
- Structured UID format with categories and numbers
- 10 system categories for classification
- Severity levels (CRITICAL/HIGH/MEDIUM/LOW)
- Status tracking (NEW โ INVESTIGATING โ IN PROGRESS โ TESTING โ FIXED)
- Matrix entry format standardized
- First bug registered: EMAIL-001
```
### Testing Session
```
3:15pm CST ๐งช Email fetching fully tested [15m]
- Test email: "Check this out" from Chris Waldenberger
- Successfully retrieved: subject, from/to, date, body, 3 attachments (19.1MB total)
- Returns complete thread metadata: labels, unread status, importance
- All message properties working: id, plainBody, htmlBody, attachments array
```
### Decision Documentation
```
3:20pm CST ๐ฏ Learned deployment workflow [20m]
- Apps Script deployments are immutable - can't modify existing
- Process: Edit code โ clasp push โ clasp deploy โ update MCP URL โ restart Claude
- Each deploy creates new version number and new URL
- MCP server needs restart to pick up config changes
- Two restarts required today for versions @24 and @25
```
---
## ๐ Best Practices
1. **Write as you go** - Don't batch document at end of session
2. **Be specific** - "Fixed email bug" โ "Fixed EMAIL-001: thread.isStarred() error"
3. **Include context** - Why decisions were made, what was learned
4. **Link related items** - Reference other bugs, features, decisions
5. **Time everything** - Even quick 5-minute fixes should be noted
6. **Use emojis consistently** - They make scanning easier
7. **Think future-you** - Will you understand this in 3 months?
---
## ๐ Reference
### Quick Emoji Guide
- ๐ Bugs & Fixes
- โ
Features Added
- ๐งช Testing Results
- ๐ฏ Decisions & Direction
- ๐ Documentation Updates
- โก Next Session Goals
- ๐ด High Priority
- ๐ก Medium Priority
- ๐ข Low Priority
- โ
Verified/Complete
- โฑ๏ธ Time
- ๐ Related/Linked
### Time Conversion Reference
- 15m = 0.25h = [15m]
- 30m = 0.5h = [30m]
- 45m = 0.75h = [45min]
- 1h = 60m = [1h]
- 1.5h = 90m = [1.5h]
- 2h = 120m = [2h]
---
**Remember:** Good notes today = powerful analysis tomorrow. The tools are only as good as the data you feed them!