Note -- Persistent Working Memory

Notes are the cross-cutting memory layer. They persist across sessions, survive context resets, and -- for Priority Context -- are automatically injected into every worker prompt.

Core principle: If a future session needs this to avoid a mistake, capture it. If not, skip it.

Mental Model

Two-tier system:

• Priority Context = pinned message in a channel. Every agent sees it, every time. Hard constraints that, if violated, produce wrong code. Workers cannot ask clarifying questions -- they need these upfront.
• Working Memory = searchable thread history. Insights, learnings, and soft observations accumulated during implementation. Available on demand, pruned periodically.
• Manual = user sticky notes. Never auto-touched, never pruned. The user manages these directly.

When to Capture

Always:

• Decisions that constrain future work (API choice, library version, architecture direction)
• Constraints discovered mid-implementation (rate limits, API quirks, platform bugs)
• User decisions on blockers (the "why" behind the choice, so no one re-asks)
• Cross-track dependencies ("track X depends on auth refactor from track Y")

Never:

• Status updates ("started task 3") -- use task-update
• Things already in spec or plan -- don't duplicate
• Temporary debugging notes ("tried X, didn't work") -- ephemeral, discard
• Obvious codebase facts -- use context-write for codebase knowledge

Decision heuristic: "Will a future session need this to avoid a mistake?" Yes = capture. No = skip.

Priority Context vs Working Memory

Promoting to Priority: If a Working Memory note keeps causing mistakes across sessions, promote it to Priority Context. If a Priority note no longer applies, demote or delete it.

Good Notes vs Bad Notes

See reference/note-patterns.md for more examples across decisions, constraints, discoveries, and dependencies.

Arguments

$ARGUMENTS

Execution

Step 1: Ensure Notepad Exists

If .maestro/notepad.md does not exist, create it with section headers:

# Notepad
## Priority Context

## Working Memory

## Manual

Step 2: Parse and Execute

Add (default, --priority, --manual):

1. Read .maestro/notepad.md
2. Find the target section header
3. Append - <content> after the header, before the next ##
4. Write the updated file
5. Display the updated section to confirm

Show (--show):

1. Read and display .maestro/notepad.md
2. If missing: "No notepad found. Use /maestro:note <content> to start."

Prune (--prune):

1. Review each bullet in ## Working Memory
2. Remove items that are stale, resolved, or superseded
3. Keep ## Priority Context and ## Manual intact
4. Show what was removed and what was kept
5. If uncertain about an item, ask the user

Clear (--clear <section>):

1. Parse section: priority, working, or all
2. If clearing Priority Context or all: confirm with user first
3. Remove all bullets from specified section(s), keep headers intact

Note Lifecycle

Create --> Review (session start) --> Update (constraint changes) --> Archive/Delete (resolved)

Anti-Patterns

Section Contracts

Relationship to Other Commands

• /maestro:setup -- Scaffold project context (run first)
• /maestro:new-track -- Create a feature/bug track with spec and plan
• /maestro:implement -- Execute implementation (reads Priority Context at Step 3.8)
• /maestro:review -- Verify implementation correctness
• /maestro:status -- Check progress across all tracks
• /maestro:note -- You are here. Capture decisions and context to persistent notepad

Priority Context is automatically loaded by /maestro:implement at execution start and injected into worker prompts in team mode. Working Memory accumulates insights from both manual notes and auto-capture during implementation. Use --prune after each feature completion to keep Working Memory relevant.