Available with any of the following subscriptions, except where noted:
🟢 Starter (up to the plan’s step limit) | 🔵 Builder | 🟣 Optimizer | Enterprise
Operational changes happen fast. A new tool is introduced, a workflow step is removed, ownership shifts between teams, and before long, the original reasoning behind those decisions fades.
Puzzle’s built-in decision log, Changelog, gives your team a centralized place to document operational changes as they happen. Capture what changed, why the decision was made, who made it, and which steps or tools were affected. Instead of relying on scattered Slack messages, meeting notes, or memory, your team has a permanent operational record directly in Puzzle.
Designed for operators, consultants, and internal teams, Changelog turns documentation into institutional memory. Every decision stays connected to the workflows and systems it affects, making it easier to maintain clarity as your operations evolve.
In this guide, you’ll learn how to create and manage changelog entries, link them to affected steps and tools, search past operational decisions, and extend your decision history using Nova and Puzzle MCP. By the end, your team will have a clear, searchable record of operational changes — ready for the next time someone asks, “Why was this changed?”
Benefits of Using the Changelog
🧠 Capture the Reasoning: Record why each change was made so the thinking survives turnover, handoffs, and time.
🔗 Connect Decisions to Your Operations: Associate changes with the exact steps and tools they affect, keeping documentation and decisions in one place.
🚦 Track Changes Across Their Lifecycle: Move entries through Idea, Planned, In Progress, Completed, and Archived to see what's shipped, what's coming, and what's been set aside.
🔎 Find Past Decisions Fast: Search and filter by status, owner, tool, or date range to recall any change in seconds.
🤖 Work With AI on Your Decision History: Use Nova inside every entry and Puzzle MCP to bring Claude into your Changelog.
💳 Pricing: Unlimited Changelog entries are included on every paid plan.
🎥 Video Guide: Using Changelog
Step-by-Step Guides on How to Use the Changelog
1️⃣ Log a Changelog
1️⃣ Log a Changelog
Create a new entry from the feed and start writing the rationale.
📍 Click on Changelog from the top navigation.
✍️ In the What changed? form at the top of the feed, enter a title.
🚦 Pick a Status from the dropdown. Status moves through four lifecycle stages:
Idea - A change you're considering but haven't committed to
Planned - A decision that's been made and scheduled
In Progress - Work that's actively happening in the workspace
Completed - Changes that have shipped and are now part of operations
Archived - Decisions that are no longer active or that the team has set aside, kept on file for reference.
👤 Pick an Owner from the dropdown.
➕ Click Log Change to open the new entry.
📝 Write the rationale in the body. It auto-saves as you type.
2️⃣ Open, Update, or Delete a Changelog
2️⃣ Open, Update, or Delete a Changelog
Open an existing entry to read it, update any field, or remove it from your changelog.
🖱 Click anywhere on an entry card in the feed (the pencil icon does the same) to open it.
🛠 Inside the entry, update from one view:
✏️ Title at the top
📝 Rationale in the body, using the formatting toolbar (Bold, Italic, H1, H2, Link, Lists, Code, plus image and video embeds)
🎬 Embed a video for visual context: Copy the embed code from Loom, YouTube, or any video platform and paste it into the rationale. The video renders inside the entry so reviewers can watch the walkthrough alongside the written decision.
🚦 Status, Owner, Completion Date, Creation Date, Tools, Steps in the right sidebar.
📅 Completion Date: Set the completion date manually to record when the change actually shipped, or let Puzzle fill it in automatically when Status moves to Completed. Adjust the date afterward if the auto-filled value differs from the real completion date.
💾 Everything auto-saves. Click Close Entry at the top right to return to the feed.
🗑 To delete the entry, click the delete icon at the bottom of the right sidebar and confirm in the modal. The entry and all its associations are removed.
3️⃣ Associate Steps and Tools With a Changelog
3️⃣ Associate Steps and Tools With a Changelog
Link a change to the specific steps and tools it affected, either from inside the entry or directly from the workflow canvas.
🔧 Tools: Inside the entry, click + next to Associated Tools to attach a tool. Remove with the X.
🔗 Steps (from inside the entry): Click + next to Associated Steps and pick steps from any workflow.
🎯 Steps (from the canvas): Multi-select steps on a workflow, then click Add to change in the pill bar to attach them to an existing entry.
🌐 Once linked, the entry also shows pills for the related sections, tools, roles, and people connected through those steps. Click any pill to open the item in a new tab.
After you associate steps or tools with a change, you can view the impact from either direction. Pair the change with a Conditional Coloring rule to highlight every associated step on the workflow canvas. Or open a tool on the Tool Canvas to see all associated Changelog entries under the tool's Changes tab. See the Conditional Step Coloring and Utilizing the Tool Canvas articles for details.
4️⃣ Find Past Changes
4️⃣ Find Past Changes
Search, filter, and sort your Changelog to recall a past decision in seconds.
🔎 Inline search: Use the Search Changes box above the feed to keyword-search within the Changelog.
🎛 Filter the feed: Use the Filters panel on the left to narrow by Status, Owner, Tool, or Creation Date Range. Click Clear All to reset.
🔃 Sort: Switch between Last Updated and Recently Created above the feed.
5️⃣ Switch Between Feed, Board, and Calendar Views
5️⃣ Switch Between Feed, Board, and Calendar Views
Pick the view that matches how you want to read the record.
📋 Feed: The default vertical list. Every entry with title, status, owner, and a rationale preview.
🗂 Board: A board grouped by status columns (Idea, Planned, In Progress, Completed, Archived). Drag any card between columns to change its status. Filters and sort apply to the board the same way they apply to the feed.
📅 Calendar: A month view of your entries. Toggle between organizing by Creation Date or Completion Date at the top of the calendar. Click any entry chip on a date to open it.
Switch views from the view selector at the top of the Changelog page.
6️⃣ See Changes From a Step in a Workflow
6️⃣ See Changes From a Step in a Workflow
View every change logged for a specific step directly from the workflow canvas.
🪜 Open the Workflow canvas and click on the step card.
📍 In the step's side icon panel, click the Changelog icon (the last icon, below sync/refresh).
👀 The Associated Changes panel opens with every entry linked to that step.
⚙️ Show or hide the panel: Turn the Associated Changes panel on or off per workflow in Workspace Settings → Workflow Settings. Toggle it on to make the panel visible on every step, or off to hide it from workflows where it isn't needed.
7️⃣ Draft a Changelog With Nova
7️⃣ Draft a Changelog With Nova
Use Nova inside an entry to turn meeting notes, transcripts, or chat conversations into a structured changelog entry.
📍 Open an entry (existing or new).
🤖 The Nova chat panel sits on the left side of the entry, scoped to that change.
📋 Paste a meeting transcript, chat conversation, or your notes into Nova.
✍️ Ask Nova to draft the rationale, summarize the decision, or propose which steps to associate. Nova writes directly into the entry.
Sample output based on my prompt shown in the video:
7️⃣ Work With Your Changelog From Claude
7️⃣ Work With Your Changelog From Claude
Use Puzzle MCP to let Claude search your changelog from outside Puzzle.
🔌 Connect your workspace to your AI tool through Puzzle MCP.
➕ Create: At the end of a Claude or ChatGPT conversation, ask the AI to log the outcome as a change, associate the affected steps and tools, and capture the full rationale.
🔎 Search: Ask "why is this step set up this way" and the AI will search the Changelog and answer from the actual decision record.
🔄 Every entry created or read through MCP shows up the same as a manually logged change.
Sample output from Claude:
💡 Best Practices for Using Changelog
✍️ Log changes the moment they happen: Capturing the reasoning while it's fresh produces a richer record than reconstructing it weeks later.
🎯 Center the entry on the rationale: Focus on why the change was made and what it replaces, so future readers understand the trade-off.
🔗 Link every entry to steps or tools: Associations turn the Changelog into a working part of your workflows.
🚦 Use status to show momentum: Move entries from Idea to Completed as work progresses so the team can see what's in flight.
👤 Assign an owner to every entry: Ownership makes follow-up obvious and keeps decisions from going stale.
🤖 Use Nova inside entries for context: Ask Nova to summarize related workflows or draft rationale when you're documenting after the fact.
🔌 Connect external AI through MCP: For teams already working in Claude, Puzzle MCP brings Changelog into the chat without context switching.
Conclusion
As workflows evolve, clarity becomes harder to maintain. Small operational decisions accumulate over time, and without a reliable record, teams eventually spend more time retracing decisions than improving processes.
Changelog instills a consistent habit of documenting operational changes while the context is still fresh. Instead of relying on memory, your team builds a searchable history of decisions directly tied to the workflows they impact.
Start logging changes as they happen. Over time, the Changelog becomes more than documentation — it becomes a living operational timeline your team can trust!